[REFACTOR] Organize divisions theme Pydantic package, add missing relationships, tidy and add docs#469
Merged
Victor Schappert (vcschapp) merged 2 commits intodevfrom Mar 12, 2026
Merged
Conversation
Victor Schappert (vcschapp)
force-pushed
the
reorg-divisions
branch
2 times, most recently
from
79c15e7 to
5aaded3
Compare
Signed-off-by: schapper <schapper@amazon.com>
Victor Schappert (vcschapp)
force-pushed
the
reorg-divisions
branch
from
5aaded3 to
a2a0002
Compare
Comment on lines
+26
to
+33
| CAPITAL_OF = "capital_of", "The relator is a capital of the relatee" | ||
| CAPITALLED_BY = "capitalled_by", "the relatee is a capital of the relator" | ||
| CHILD_OF = "child_of", "The relator is a child of the relatee" | ||
| CONNECTS_TO = "connects_to", "The relator connects to the relatee" | ||
| DESCENDANT_OF = ( | ||
| "descendant_of", | ||
| "The relator is a hierarchical descentant of the relatee", | ||
| ) |
Collaborator
Author
There was a problem hiding this comment.
TristanDiet-TomTom, it happened exactly as you predicted!
I found that four relationships in divisions weren't modeled yet. Since none of them had an appropriate relationship, I had to add four new relationship types: CAPITAL_OF, CAPITALLED_BY, CHILD_OF, and DESCENDANT_OF.
These should be thought of as temporary, since when we put your new system in place all the existing relationship types will fold into the new system.
Seth Fitzsimmons (mojodna)
previously approved these changes
Mar 12, 2026
packages/overture-schema-system/src/overture/schema/system/ref/ref.py
Outdated
Show resolved
Hide resolved
Collaborator
|
The docs preview link is wrong and the staging link (https://staging.overturemaps.org/docs/pr/469/...) isn't working either. I wanted to see how this affected the nav. |
Collaborator
Author
Interesting. I'm guessing that structural change has broken the previously working staging links, which haven't been used much lately? |
This commit organizes the divisions Pydantic package to align with the
other packages that have been done so far: addresses, base, buildings,
and places. After this commit there remains only: transportation and
core (the latter will soon be renamed common).
Organization work done:
1. Common code into `_common.py`.
2. Each feature type gets its own main module, e.g., `division.py`.
3. Types used exclusively by a feature type into that feature type's main
module, regardless of whether the type is an enum, model, NewType, etc.
4. Eliminate sub-directories.
5. Curate `__all__` in `__init__.py`.
Missing relationships added:
1. `CapitalOfItem`
2. `HierarchyItem`
3. `parent_division_id` in `Division`
4. `capital_division_ids` in `Division`
Getting this to work required extending the list of relationships in the
system package's `ref.py`. (On this, note, that Tristan will likely
shrink it back to managable size when he rationalizes the
relationships.) It also required solving an issue with Python forward
references being in the Pydantic field annotations for `CapitalOfItem`
and `HierarchyItem`, which was breaking codegen. I fixed this issue by
using `.model_rebuild()` on both models, see `divisions.py`.
Docs tidied and updated:
1. Eliminated all `make docformat` errors pertaining to divisions.
2. Converted several enums to `DocumentedEnum` so they can have a richer
presence in the schema reference.
3. Added missing docstrings and `Field(description="...")` annotations.
4. Edited and refined some of the documentation wording where it wasn't
fully up to standard.
5. Wrapped long doc/desc lines using `textwrap.dedent("...").strip()` so
the docs are easier to read and edit in a code editor.
Signed-off-by: schapper <schapper@amazon.com>
Victor Schappert (vcschapp)
force-pushed
the
reorg-divisions
branch
from
a2a0002 to
f2f96a1
Compare
Seth Fitzsimmons (mojodna)
approved these changes
Mar 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Continuing the Pydantic package polishing journey from late 2025, this PR cleans up the divisions theme. After this,
only transportation and some final tweaks to core (soon to be common) will remain.
tl;dr
Merge guidance: Rebase
Two two commits in the history are intentional. This PR should be rebased.
Journey
This PR follows a sequence of PRs I published in late 2025 that started the cleanup process, but did leave it somewhat incomplete. These are the earlier ones.
This PR is basically episode 6.
Documentation website
Update the hyperlink below to put the pull request number in.
Docs preview for this PR.