Pydantic package organization episode 5: "Only mostly dead"

Makefile

@@ -11,17 +11,17 @@ check: test doctest
 	@uv run ruff format --check packages/
 
 test-all: uv-sync
-	@uv run pytest packages/
+	@uv run pytest -W error packages/
 
 test: uv-sync
-	@uv run pytest packages/ -x
+	@uv run pytest -W error packages/ -x
 
 coverage: uv-sync
 	@uv run pytest packages/ --cov overture.schema --cov-report=term --cov-report=html && open htmlcov/index.html
 
 docformat:
 	@find packages/*/src -name "*.py" -type f -not -name "__*" \
-		| xargs uv run pydocstyle --convention=numpy --add-ignore=D105
+		| xargs uv run pydocstyle --convention=numpy --add-ignore=D102,D105,D200,D205,D400
 
 doctest: uv-sync
 	@# $$ escapes $ for make - sed needs literal $ for end-of-line anchor

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

@@ -1,4 +1,6 @@
-"""Address feature model."""
+"""
+The `Address` feature type model and supporting types.
+"""
 
 import textwrap
 from typing import Annotated, Literal
@@ -64,7 +66,8 @@ class Address(OvertureFeature[Literal["addresses"], Literal["address"]]):
 
     model_config = ConfigDict(title="address")
 
-    # Core
+    # Overture Feature
+
     geometry: Annotated[
         Geometry,
         GeometryTypeConstraint(GeometryType.POINT),

packages/overture-schema-addresses-theme/tests/address_baseline_schema.json

@@ -15,12 +15,12 @@
       "title": "AddressLevel",
       "type": "object"
     },
-    "SourcePropertyItem": {
+    "SourceItem": {
       "additionalProperties": false,
-      "description": "An object storing the source for a specified property.\n\nThe property is a reference to the property element within this Feature, and will be\nreferenced using JSON Pointer Notation RFC 6901 (\nhttps://datatracker.ietf.org/doc/rfc6901/).\nThe source dataset for that referenced property will be specified in the overture list of approved sources from the Overture Data Working Group that contains the relevant metadata for that dataset including license source organization.",
+      "description": "Specifies the source of the data used for a feature or one of its properties.",
       "properties": {
         "between": {
-          "description": "Linear reference range [start, end] where 0.0 <= start < end <= 1.0",
+          "description": "The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to.",
           "items": {
             "maximum": 1.0,
             "minimum": 0.0,
@@ -32,34 +32,35 @@
           "type": "array"
         },
         "confidence": {
-          "description": "Confidence score between 0.0 and 1.0",
+          "description": "Confidence value from the source dataset.\n\nThis is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data.",
           "maximum": 1.0,
           "minimum": 0.0,
           "title": "Confidence",
           "type": "number"
         },
         "dataset": {
+          "description": "Name of the dataset where the source data can be found.",
           "title": "Dataset",
           "type": "string"
         },
         "license": {
-          "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.",
+          "description": "Source data license name.\n\nThis should be a valid SPDX license identifier when available.\n\nIf omitted, contact the data provider for more license information.",
           "pattern": "^(\\S.*)?\\S$",
           "title": "License",
           "type": "string"
         },
         "property": {
-          "description": "JSON Pointer (RFC 6901)",
+          "description": "A JSON Pointer identifying the property (field) that this source information applies to.\n\nThe root document value `\"\"` indicates that this source information applies to the\nentire feature, excepting properties (fields) for which a dedicated source information\nrecord exists.\n\nAny other JSON Pointer apart from `\"\"` indicates that this source record provides\ndedicated source information for the property at the path in the JSON Pointer. As an\nexample, the value `\"/names/common/en\"` indicates that the source information applies to\nthe English common name of a named feature, while the value `\"/geometry\"` indicates that\nit applies to the feature geometry.",
           "title": "Property",
           "type": "string"
         },
         "record_id": {
-          "description": "Refers to the specific record within the dataset that was used.",
+          "description": "Identifies the specific record within the source dataset where the source data can\nbe found.\n\nThe format of record identifiers is dataset-specific.",
           "title": "Record Id",
           "type": "string"
         },
         "update_time": {
-          "description": "Timestamp when the feature was last updated",
+          "description": "Last update time of the source data record.",
           "format": "date-time",
           "title": "Update Time",
           "type": "string"
@@ -69,7 +70,7 @@
         "property",
         "dataset"
       ],
-      "title": "SourcePropertyItem",
+      "title": "SourceItem",
       "type": "object"
     }
   },
@@ -178,9 +179,9 @@
           "type": "string"
         },
         "sources": {
-          "description": "The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset approved sources from the Overture Data Working Group that contains the relevant metadata for that dataset including license source organization.",
+          "description": "Information about the source data used to assemble the feature.",
           "items": {
-            "$ref": "#/$defs/SourcePropertyItem"
+            "$ref": "#/$defs/SourceItem"
           },
           "minItems": 1,
           "title": "Sources",

packages/overture-schema-addresses-theme/tests/test_address_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.addresses import Address
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_address_json_schema_baseline() -> None:

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

@@ -68,6 +68,7 @@ class Dataset(BaseModel):
         str,
         Field(description="Any attribution required by this source."),
     ]
+    # FIXME: This should be a `BBox` primitive, not a `list[float]`.
     coverage_bbox: Annotated[
         list[float],
         Field(

packages/overture-schema-annex/tests/test_sources_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.annex import Sources
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_sources_json_schema_baseline() -> None:

packages/overture-schema-base-theme/pyproject.toml

@@ -25,9 +25,9 @@ path = "src/overture/schema/base/__about__.py"
 packages = ["src/overture"]
 
 [project.entry-points."overture.models"]
-"base.bathymetry" = "overture.schema.base.bathymetry.models:Bathymetry"
-"base.infrastructure" = "overture.schema.base.infrastructure.models:Infrastructure"
-"base.land" = "overture.schema.base.land.models:Land"
-"base.land_cover" = "overture.schema.base.land_cover.models:LandCover"
-"base.land_use" = "overture.schema.base.land_use.models:LandUse"
-"base.water" = "overture.schema.base.water.models:Water"
+"base.bathymetry" = "overture.schema.base:Bathymetry"
+"base.infrastructure" = "overture.schema.base:Infrastructure"
+"base.land" = "overture.schema.base:Land"
+"base.land_cover" = "overture.schema.base:LandCover"
+"base.land_use" = "overture.schema.base:LandUse"
+"base.water" = "overture.schema.base:Water"

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

@@ -6,11 +6,41 @@
 
 __path__ = __import__("pkgutil").extend_path(__path__, __name__)
 
+
+from ._common import (
+    Depth,
+    Elevation,
+    Height,
+    SourcedFromOpenStreetMap,
+    SourceTags,
+    SurfaceMaterial,
+)
 from .bathymetry import Bathymetry
-from .infrastructure import Infrastructure
-from .land import Land
-from .land_cover import LandCover
-from .land_use import LandUse
-from .water import Water
+from .infrastructure import Infrastructure, InfrastructureClass, InfrastructureSubtype
+from .land import Land, LandClass, LandSubtype
+from .land_cover import LandCover, LandCoverSubtype
+from .land_use import LandUse, LandUseClass, LandUseSubtype
+from .water import Water, WaterClass, WaterSubtype
 
-__all__ = ["Bathymetry", "Infrastructure", "Land", "LandCover", "LandUse", "Water"]
+# Only the theme's feature type classes should be available for `import *`.
+__all__ = [
+    "Bathymetry",
+    "Depth",
+    "Elevation",
+    "Height",
+    "Infrastructure",
+    "InfrastructureClass",
+    "InfrastructureSubType",
+    "Land",
+    "LandClass",
+    "LandCover",
+    "LandCoverSubtype",
+    "LandSubtype",
+    "LandUse",
+    "SourcedFromOpenStreetMap",
+    "SourceTags",
+    "SurfaceMaterial",
+    "Water",
+    "WaterClass",
+    "WaterSubtype",
+]

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

@@ -0,0 +1,89 @@
+import textwrap
+from enum import Enum
+from typing import Annotated, Any, NewType
+
+from pydantic import BaseModel, Field
+
+from overture.schema.system.primitive import float64, int32
+from overture.schema.system.string import WikidataId
+
+Depth = NewType(
+    "Depth",
+    Annotated[
+        int32,
+        Field(
+            ge=0,
+            description="Depth below surface level of the feature in meters.",
+        ),
+    ],
+)
+
+Elevation = NewType(
+    "Elevation",
+    Annotated[
+        int32,
+        Field(
+            le=9000,
+            description="Elevation above sea level of the feature in meters.",
+        ),
+    ],
+)
+
+Height = NewType(
+    "Height",
+    Annotated[float64, Field(gt=0, description="Height of the feature in meters.")],
+)
+
+
+SourceTags = NewType(
+    "SourceTags",
+    Annotated[
+        dict[str, Any],
+        Field(
+            description=textwrap.dedent("""
+                Key/value pairs imported directly from the source data without change.
+
+                This field provides access to raw OSM entity tags for features sourced from
+                OpenStreetMap.
+            """).strip()
+        ),
+    ],
+)
+
+
+class SourcedFromOpenStreetMap(BaseModel):
+    """
+    Model derived from an OpenStreetMap entity and containing the entity's OSM tags and wikidata ID.
+    """
+
+    source_tags: SourceTags | None = None
+    wikidata: WikidataId | None = None
+
+
+class SurfaceMaterial(str, Enum):
+    """Material that makes up the surface of `Infrastructure` and `Land` features."""
+
+    ASPHALT = "asphalt"
+    COBBLESTONE = "cobblestone"
+    COMPACTED = "compacted"
+    CONCRETE = "concrete"
+    CONCRETE_PLATES = "concrete_plates"
+    DIRT = "dirt"
+    EARTH = "earth"
+    FINE_GRAVEL = "fine_gravel"
+    GRASS = "grass"
+    GRAVEL = "gravel"
+    GROUND = "ground"
+    PAVED = "paved"
+    PAVING_STONES = "paving_stones"
+    PEBBLESTONE = "pebblestone"
+    RECREATION_GRASS = "recreation_grass"
+    RECREATION_PAVED = "recreation_paved"
+    RECREATION_SAND = "recreation_sand"
+    RUBBER = "rubber"
+    SAND = "sand"
+    SETT = "sett"
+    TARTAN = "tartan"
+    UNPAVED = "unpaved"
+    WOOD = "wood"
+    WOODCHIPS = "woodchips"

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

@@ -1,35 +1,42 @@
-"""Bathymetry feature models for Overture Maps base theme."""
+"""
+The `Bathymetry` feature type model and supporting types.
+"""
 
 from typing import Annotated, Literal
 
 from pydantic import ConfigDict, Field
 
-from overture.schema.base.types import Depth
 from overture.schema.core import (
     OvertureFeature,
 )
-from overture.schema.core.models import CartographicallyHinted
+from overture.schema.core.cartography import CartographicallyHinted
 from overture.schema.system.primitive import (
     Geometry,
     GeometryType,
     GeometryTypeConstraint,
 )
 
+from ._common import Depth
+
 
 class Bathymetry(
     OvertureFeature[Literal["base"], Literal["bathymetry"]], CartographicallyHinted
 ):
-    """Topographic representation of an underwater area, such as a part of the ocean
-    floor."""
+    """
+    Bathymetry features provide topographic representations of underwater areas, such as parts of
+    lake beds or ocean floors.
+    """
 
     model_config = ConfigDict(title="bathymetry")
 
-    # Core
+    # Overture Feature
 
     geometry: Annotated[
         Geometry,
         GeometryTypeConstraint(GeometryType.POLYGON, GeometryType.MULTI_POLYGON),
-        Field(description="Geometry (Polygon or MultiPolygon)"),
+        Field(
+            description="Shape of the underwater area, which may be a polygon or multi-polygon."
+        ),
     ]
 
     # Required