overture-schema-validation 2.0.0__tar.gz

overture_schema_validation-2.0.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: overture-schema-validation
+Version: 2.0.0
+Summary: Validation helpers for the union of all discovered Overture models
+License-Expression: MIT
+Requires-Dist: overture-schema-common>=2.0.0
+Requires-Dist: overture-schema-system>=2.0.0
+Requires-Dist: pydantic>=2.12.0
+Maintainer: Overture Maps Schema Working Group
+Requires-Python: >=3.10
+Project-URL: Homepage, https://overturemaps.org
+Project-URL: Source, https://github.com/OvertureMaps/schema
+Project-URL: Issues, https://github.com/OvertureMaps/schema/issues
+Description-Content-Type: text/markdown
+
+# overture-schema-validation
+
+Validate data against the union of all discovered Overture Maps models.
+
+This package provides `validate` and `validate_json`, which check a Python object or JSON document against every Overture model registered on the `overture.models` entry point and return the matching validated model instance.
+
+## Installation
+
+```bash
+pip install overture-schema-validation
+```
+
+## Usage
+
+```python
+from overture.schema.validation import validate, validate_json
+
+# A Python object -- the flat, tabular (Parquet-style) shape
+feature = validate(feature_row)
+
+# A JSON document -- GeoJSON
+feature = validate_json(geojson_text)
+```
+
+The two entry points are not interchangeable. `validate` runs Pydantic's Python mode, which reads the flat column layout of the Parquet release -- the shape Overture publishes. `validate_json` runs JSON mode, which reads the GeoJSON representation the models support for compatibility with tools that expect features rather than rows. Handing a GeoJSON dict to `validate` reports `theme` and `version` missing and `type` set to `'Feature'`.
+
+Both raise `pydantic.ValidationError` when the input matches no model. Which models participate is resolved at runtime by entry-point discovery, so installing additional Overture theme packages widens what these functions accept.

overture_schema_validation-2.0.0/README.md

@@ -0,0 +1,27 @@
+# overture-schema-validation
+
+Validate data against the union of all discovered Overture Maps models.
+
+This package provides `validate` and `validate_json`, which check a Python object or JSON document against every Overture model registered on the `overture.models` entry point and return the matching validated model instance.
+
+## Installation
+
+```bash
+pip install overture-schema-validation
+```
+
+## Usage
+
+```python
+from overture.schema.validation import validate, validate_json
+
+# A Python object -- the flat, tabular (Parquet-style) shape
+feature = validate(feature_row)
+
+# A JSON document -- GeoJSON
+feature = validate_json(geojson_text)
+```
+
+The two entry points are not interchangeable. `validate` runs Pydantic's Python mode, which reads the flat column layout of the Parquet release -- the shape Overture publishes. `validate_json` runs JSON mode, which reads the GeoJSON representation the models support for compatibility with tools that expect features rather than rows. Handing a GeoJSON dict to `validate` reports `theme` and `version` missing and `type` set to `'Feature'`.
+
+Both raise `pydantic.ValidationError` when the input matches no model. Which models participate is resolved at runtime by entry-point discovery, so installing additional Overture theme packages widens what these functions accept.

overture_schema_validation-2.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["uv_build>=0.11.32,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "overture-schema-validation"
+version = "2.0.0"
+description = "Validation helpers for the union of all discovered Overture models"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+dependencies = [
+    "overture-schema-common>=2.0.0",
+    "overture-schema-system>=2.0.0",
+    "pydantic>=2.12.0",
+]
+
+[[project.maintainers]]
+name = "Overture Maps Schema Working Group"
+
+[project.urls]
+Homepage = "https://overturemaps.org"
+Source = "https://github.com/OvertureMaps/schema"
+Issues = "https://github.com/OvertureMaps/schema/issues"
+
+[tool.uv.sources.overture-schema-common]
+workspace = true
+
+[tool.uv.sources.overture-schema-system]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "overture.schema.validation"
+
+[dependency-groups]
+dev = [
+    "pyyaml>=6.0.2",
+    "yamlcore>=0.0.4",
+]

overture_schema_validation-2.0.0/pyproject.toml.orig

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["uv_build>=0.11.32,<0.13"]
+build-backend = "uv_build"
+
+[project]
+maintainers = [
+    {name = "Overture Maps Schema Working Group"},
+]
+name = "overture-schema-validation"
+version = "2.0.0"
+description = "Validation helpers for the union of all discovered Overture models"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+dependencies = [
+    "overture-schema-common>=2.0.0",
+    "overture-schema-system>=2.0.0",
+    "pydantic>=2.12.0",
+]
+
+[project.urls]
+Homepage = "https://overturemaps.org"
+Source = "https://github.com/OvertureMaps/schema"
+Issues = "https://github.com/OvertureMaps/schema/issues"
+
+[tool.uv.sources]
+overture-schema-common = { workspace = true }
+overture-schema-system = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pyyaml>=6.0.2",
+    "yamlcore>=0.0.4",
+]
+
+[tool.uv.build-backend]
+module-name = "overture.schema.validation"

overture_schema_validation-2.0.0/src/overture/schema/validation/__init__.py

@@ -0,0 +1,169 @@
+from collections.abc import Generator
+from functools import reduce
+from operator import or_
+from types import UnionType
+from typing import Annotated, Any, Literal, cast, get_args, get_origin
+
+from pydantic import BaseModel, Field, Tag, TypeAdapter
+
+from overture.schema.common import OvertureFeature
+from overture.schema.system.discovery import discover_models
+from overture.schema.system.feature import Feature
+
+
+def validate(data: object) -> BaseModel:
+    """
+    Validate a Python object, which can be a dictionary or model instance, using the union of all
+    discovered Overture models.
+
+    Parameters
+    ----------
+    data : object
+        Python object to validate against the model.
+
+    Returns
+    -------
+    BaseModel
+        Validated model class
+
+    Raises
+    ------
+    ValidationError
+        If `data` is not valid according to one of the discovered Overture models
+    """
+    tap = _union_type_adapter()
+
+    return cast(BaseModel, tap.validate_python(data))
+
+
+def validate_json(json_data: str | bytes | bytearray) -> BaseModel:
+    """
+    Validate JSON data using the union of all discovered Overture models.
+
+    Parameters
+    ----------
+    json_data : str | bytes | bytearray
+        JSON data to validate
+
+    Returns
+    -------
+    BaseModel
+        Validated model class
+
+    Raises
+    ------
+    ValidationError
+        If `json_data` is not valid according to one of the discovered Overture models
+    """
+    tap = _union_type_adapter()
+
+    return cast(BaseModel, tap.validate_json(json_data))
+
+
+__all__ = [
+    "validate",
+    "validate_json",
+]
+
+
+def _union_type_adapter() -> TypeAdapter:
+    """
+    Return a Pydantic type adapter that can validate the union of all models discovered using entry
+    points.
+    """
+    models = discover_models()
+    if not models:
+        raise RuntimeError("no registered models found via entry points")
+
+    discriminated_models: tuple[type[OvertureFeature], ...] = tuple(
+        cast(type[OvertureFeature], m) for m in models.values() if _can_discriminate(m)
+    )
+    discriminated_union: UnionType | None = _discriminated_union(discriminated_models)
+
+    non_discriminated_models: Generator[type[BaseModel], None, None] = (
+        m for m in models.values() if not _can_discriminate(m)
+    )
+    non_discriminated_union: UnionType | None = reduce(
+        or_, non_discriminated_models, None
+    )
+
+    if discriminated_union and non_discriminated_union:
+        model_union = discriminated_union | non_discriminated_union
+    elif discriminated_union:
+        model_union = discriminated_union
+    elif non_discriminated_union:
+        model_union = non_discriminated_union
+    else:
+        raise RuntimeError("logic error: unreachable code")
+
+    return TypeAdapter(model_union)
+
+
+def _discriminated_union(
+    feature_classes: tuple[type[OvertureFeature], ...],
+) -> Any:  # noqa: ANN401
+    """
+    Create a discriminated union of the Overture features since they can be discriminated on the
+    `type` field. This is just a performance optimization, and the union will work even if no models
+    are discriminated.
+    """
+    if not feature_classes:
+        return None
+    else:
+        return Annotated[
+            reduce(
+                or_,
+                (
+                    Annotated[f, Tag(cast(str, _typeliteral(f)))]
+                    for f in feature_classes
+                ),
+            ),
+            Field(discriminator=Feature.field_discriminator("type", *feature_classes)),
+        ]
+
+
+def _can_discriminate(model_class: object) -> bool:
+    """
+    Return true if given value can participate in a discriminated union on the `type` field because
+    it is an Overture feature with where the `type` field has a single literal value.
+    """
+    return (
+        isinstance(model_class, type)
+        and issubclass(model_class, OvertureFeature)
+        and _typeliteral(cast(type[OvertureFeature], model_class)) is not None
+    )
+
+
+def _typeliteral(feature_class: type[OvertureFeature]) -> object:
+    """
+    Return the literal value of the Overture Feature model's `type` field, if it has one, or `None`
+    if it does not.
+
+    Parameters
+    ----------
+    feature_class : type[OvertureFeature]
+        Overture feature model class
+
+    Returns
+    -------
+    object
+        The literal constrained value of the model class' `type` field, or `None` if the `type`
+        field does not have a literal value
+
+    Raises
+    ------
+    TypeError
+        If the `type` field is constrained to `Literal[None]`, as this is absurd
+    """
+    type_type = feature_class.model_fields["type"].annotation
+    while get_origin(type_type) is Annotated:
+        type_type = get_args(type_type)[0]
+    if get_origin(type_type) is not Literal:
+        return None
+    literal = get_args(type_type)[0]
+    if literal is None:
+        raise TypeError(
+            f"literal value of `type` field for `{OvertureFeature.__name__}` class "
+            f"`{feature_class.__name__}` is constrained to `None`"
+        )
+    return literal