Pydantic package organization episode 1: "Making huge mess"

Makefile

@@ -1,11 +1,11 @@
-.PHONY: default uv-sync check test-all test mypy reset-baseline-schemas
+.PHONY: default uv-sync check test-all test docformat doctest mypy reset-baseline-schemas
 
 default: test-all
 
 uv-sync:
 	@uv sync --all-packages
 
-check: test uv-sync
+check: test doctest
 	@uv run ruff check -q packages/
 	@$(MAKE) mypy
 	@uv run ruff format --check packages/
@@ -16,18 +16,27 @@ test-all: uv-sync
 test: uv-sync
 	@uv run pytest packages/ -x
 
+docformat:
+	@find packages/*/src -name "*.py" -type f -not -name "__*" \
+		| xargs uv run pydocstyle --convention=numpy --add-ignore=D105
+
+doctest: uv-sync
+	@# $$ escapes $ for make - sed needs literal $ for end-of-line anchor
+	@find packages/*/src -name "*.py" -type f -not -name "__*" \
+		| sed 's|^packages/[^/]*/src/||' \
+		| sed 's|/|.|g' \
+		| sed 's|\.py$$||' \
+		| xargs uv run python -c 'import doctest, importlib, sys; [doctest.testmod(importlib.import_module(m)) for m in sys.argv[1:]]'
+
 # mypy type checking with namespace package support
 mypy: uv-sync
-	@cd packages && uv run mypy --no-error-summary --namespace-packages \
-		-p overture.schema \
-		-p overture.schema.addresses \
-		-p overture.schema.base \
-		-p overture.schema.buildings \
-		-p overture.schema.core \
-		-p overture.schema.divisions \
-		-p overture.schema.places \
-		-p overture.schema.transportation \
-		-p overture.schema.validation
+	@# $$ escapes $ for make - sed needs literal $ for end-of-line anchor
+	@find packages -maxdepth 1 -type d -name "overture-schema*" \
+		| sort \
+		| sed 's|-theme$$||' \
+		| tr - . \
+		| sed 's|^packages/|-p |' \
+		| xargs uv run mypy --no-error-summary
 	@uv run mypy --no-error-summary packages/*/tests/*.py
 
 reset-baseline-schemas:

packages/overture-schema-addresses-theme/src/overture/schema/addresses/address/models.py

@@ -8,12 +8,13 @@
     Feature,
     StrictBaseModel,
 )
-from overture.schema.core.geometry import (
+from overture.schema.core.types import CountryCode
+from overture.schema.system.primitive import (
     Geometry,
     GeometryType,
     GeometryTypeConstraint,
 )
-from overture.schema.core.types import CountryCode, TrimmedString
+from overture.schema.system.string import StrippedString
 
 
 class AddressLevel(StrictBaseModel):
@@ -26,7 +27,7 @@ class AddressLevel(StrictBaseModel):
     """
 
     value: Annotated[
-        TrimmedString | None,
+        StrippedString | None,
         Field(
             min_length=1,
         ),
@@ -67,14 +68,14 @@ class Address(Feature[Literal["addresses"], Literal["address"]]):
     ] = None
     country: CountryCode | None = None
     number: Annotated[
-        TrimmedString | None,
+        StrippedString | None,
         Field(
             min_length=1,
             description="""The house number for this address. This field may not strictly be a number. Values such as "74B", "189 1/2", "208.5" are common as the number part of an address and they are not part of the "unit" of this address.""",
         ),
     ] = None
     postal_city: Annotated[
-        TrimmedString | None,
+        StrippedString | None,
         Field(
             min_length=1,
             description="""In some countries or regions, a mailing address may need to specify a different city name than the city that actually contains the address coordinates. This optional field can be used to specify the alternate city name to use.
@@ -87,21 +88,21 @@ class Address(Feature[Literal["addresses"], Literal["address"]]):
         ),
     ] = None
     postcode: Annotated[
-        TrimmedString | None,
+        StrippedString | None,
         Field(
             min_length=1,
             description="The postcode for the address",
         ),
     ] = None
     street: Annotated[
-        TrimmedString | None,
+        StrippedString | None,
         Field(
             min_length=1,
             description="""The street name associated with this address. The street name can include the street "type" or street suffix, e.g., Main Street. Ideally this is fully spelled out and not abbreviated but we acknowledge that many address datasets abbreviate the street name so it is acceptable.""",
         ),
     ] = None
     unit: Annotated[
-        TrimmedString | None,
+        StrippedString | None,
         Field(
             min_length=1,
             description="The suite/unit/apartment/floor number",

packages/overture-schema-base-theme/src/overture/schema/base/bathymetry/models.py

@@ -8,8 +8,12 @@
 from overture.schema.core import (
     Feature,
 )
-from overture.schema.core.geometry import Geometry, GeometryType, GeometryTypeConstraint
 from overture.schema.core.models import CartographicallyHinted
+from overture.schema.system.primitive import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
 
 
 class Bathymetry(

packages/overture-schema-base-theme/src/overture/schema/base/infrastructure/models.py

@@ -13,8 +13,12 @@
 from overture.schema.core import (
     Feature,
 )
-from overture.schema.core.geometry import Geometry, GeometryType, GeometryTypeConstraint
 from overture.schema.core.models import Named, Stacked
+from overture.schema.system.primitive import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
 
 from ..enums import SurfaceMaterial
 

packages/overture-schema-base-theme/src/overture/schema/base/land/models.py

@@ -10,8 +10,12 @@
 from overture.schema.core import (
     Feature,
 )
-from overture.schema.core.geometry import Geometry, GeometryType, GeometryTypeConstraint
 from overture.schema.core.models import Named, Stacked
+from overture.schema.system.primitive import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
 
 from ..enums import SurfaceMaterial
 

packages/overture-schema-base-theme/src/overture/schema/base/land_cover/models.py

@@ -8,8 +8,12 @@
 from overture.schema.core import (
     Feature,
 )
-from overture.schema.core.geometry import Geometry, GeometryType, GeometryTypeConstraint
 from overture.schema.core.models import CartographicallyHinted
+from overture.schema.system.primitive import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
 
 
 class LandCover(

packages/overture-schema-base-theme/src/overture/schema/base/land_use/models.py

@@ -10,8 +10,12 @@
 from overture.schema.core import (
     Feature,
 )
-from overture.schema.core.geometry import Geometry, GeometryType, GeometryTypeConstraint
 from overture.schema.core.models import Named, Stacked
+from overture.schema.system.primitive import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
 
 from ..enums import SurfaceMaterial
 

packages/overture-schema-base-theme/src/overture/schema/base/models.py

@@ -1,7 +1,7 @@
 from pydantic import BaseModel
 
 from overture.schema.base.types import SourceTags
-from overture.schema.core.types import WikidataId
+from overture.schema.system.string import WikidataId
 
 
 class SourcedFromOpenStreetMap(BaseModel):

packages/overture-schema-base-theme/src/overture/schema/base/types.py

@@ -2,7 +2,7 @@
 
 from pydantic import Field
 
-from overture.schema.core.primitives import float64, int32
+from overture.schema.system.primitive import float64, int32
 
 Elevation = NewType(
     "Elevation",

packages/overture-schema-base-theme/src/overture/schema/base/water/models.py

@@ -9,8 +9,12 @@
 from overture.schema.core import (
     Feature,
 )
-from overture.schema.core.geometry import Geometry, GeometryType, GeometryTypeConstraint
 from overture.schema.core.models import Named, Stacked
+from overture.schema.system.primitive import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
 
 
 class Water(

packages/overture-schema-buildings-theme/src/overture/schema/buildings/building/models.py

@@ -5,8 +5,12 @@
 from pydantic import ConfigDict, Field
 
 from overture.schema.core import Feature
-from overture.schema.core.geometry import Geometry, GeometryType, GeometryTypeConstraint
 from overture.schema.core.models import Named, Stacked
+from overture.schema.system.primitive import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
 
 from ..models import Shape
 from .enums import (

packages/overture-schema-buildings-theme/src/overture/schema/buildings/building_part/models.py

@@ -5,10 +5,14 @@
 from pydantic import Field
 
 from overture.schema.core import Feature
-from overture.schema.core.geometry import Geometry, GeometryType, GeometryTypeConstraint
 from overture.schema.core.models import Named, Stacked
 from overture.schema.core.ref import Reference, Relationship
 from overture.schema.core.types import Id
+from overture.schema.system.primitive import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
 
 from ..building.models import Building
 from ..models import Shape

packages/overture-schema-buildings-theme/src/overture/schema/buildings/models.py

@@ -8,8 +8,8 @@
     RoofOrientation,
     RoofShape,
 )
-from overture.schema.core.primitives import float64, int32
-from overture.schema.core.types import HexColor
+from overture.schema.system.primitive import float64, int32
+from overture.schema.system.string import HexColor
 
 
 class Shape(BaseModel):

packages/overture-schema-core/src/overture/schema/core/models.py

@@ -12,32 +12,37 @@
 )
 from pydantic_core import core_schema
 
-from overture.schema.core.bbox import BBox
+from overture.schema.system.constraint import UniqueItemsConstraint
+from overture.schema.system.primitive import (
+    BBox,
+    Geometry,
+)
+from overture.schema.system.string import (
+    JsonPointer,
+    LanguageTag,
+    RegionCode,
+    StrippedString,
+)
 from overture.schema.validation import (
     allow_extension_fields,
 )
 
 from .enums import NameVariant, PerspectiveMode, Side
-from .geometry import Geometry
 from .types import (
     CommonNames,
     ConfidenceScore,
     CountryCode,
     FeatureUpdateTime,
     FeatureVersion,
     Id,
-    JsonPointer,
-    LanguageTag,
     Level,
     LinearlyReferencedRange,
     MaxZoom,
     MinZoom,
     Prominence,
-    RegionCode,
     SortKey,
-    TrimmedString,
 )
-from .validation import ConstraintValidatedModel, UniqueItemsConstraint
+from .validation import ConstraintValidatedModel
 
 
 class StrictBaseModel(BaseModel):
@@ -96,7 +101,7 @@ class SourcePropertyItem(GeometricRangeScope):
     # Optional
 
     license: Annotated[
-        TrimmedString | None,
+        StrippedString | None,
         Field(
             description="License name. This should be a valid SPDX license identifier when available. If the license is NULL, contact the data provider for more license information.",
         ),
@@ -264,7 +269,7 @@ class NameRule(GeometricRangeScope, SideScope):
 
     # Required
 
-    value: Annotated[TrimmedString, Field(min_length=1)]
+    value: Annotated[StrippedString, Field(min_length=1)]
     variant: NameVariant
 
     # Optional
@@ -287,7 +292,7 @@ class Names(StrictBaseModel):
     # Required
 
     primary: Annotated[
-        TrimmedString, Field(min_length=1, description="The most commonly used name.")
+        StrippedString, Field(min_length=1, description="The most commonly used name.")
     ]
 
     # Optional

packages/overture-schema-core/src/overture/schema/core/primitives/__init__.py

@@ -1,28 +0,0 @@
-"""Primitive data types.
-
-This module provides additional, more specific primitive types that come with automatic
-constraint validation and are intended to support multi-target serialization support
-(where the list of and names for these types vary).
-"""
-
-from .numeric import (
-    float32,
-    float64,
-    int8,
-    int32,
-    int64,
-    uint8,
-    uint16,
-    uint32,
-)
-
-__all__ = [
-    "uint8",
-    "uint16",
-    "uint32",
-    "int8",
-    "int32",
-    "int64",
-    "float32",
-    "float64",
-]

packages/overture-schema-core/src/overture/schema/core/ref.py

@@ -53,9 +53,9 @@ class that is said to "hold the reference") and the relatee.
     >>> from overture.schema.core.ref import Reference, Relationship
     >>> from overture.schema.core.types import Id
     >>> class Park(Feature):
-    >>>     pass
+    ...     pass
     >>> class ParkBench(Feature):
-    >>>    park_id: Annotated[Id, Reference(Relationship.BELONGS_TO, Park)]
+    ...    park_id: Annotated[Id, Reference(Relationship.BELONGS_TO, Park)]
     """
 
     relationship: Relationship