overture-schema-cli 0.1.1.dev0__py3-none-any.whl

overture/schema/cli/tag_options.py

@@ -0,0 +1,69 @@
+"""Shared Click options for tag-based model selection."""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+import click
+
+from overture.schema.system.discovery import TagSelector
+
+F = TypeVar("F", bound=Callable[..., object])
+
+# Every tag named here must be one discovery actually emits -- a tag in help
+# text reads as runnable. The namespaced form has no shipped example, so it is
+# described rather than illustrated.
+_TAG_SYNTAX_NOTE = (
+    "Accepts plain tags (e.g. feature, overture) and compound key/value tags "
+    "(e.g. overture:theme=buildings). A namespaced form, namespace:predicate, "
+    "is also accepted for tags that third-party packages register."
+)
+
+
+def tag_selection_options(func: F) -> F:
+    """Decorate a Click command with --tag, --filter, and --exclude options.
+
+    The decorated command receives `tags`, `filters`, and `excludes`
+    keyword arguments (each a `tuple[str, ...]`), suitable for passing to
+    `build_selector`.
+    """
+    func = click.option(
+        "--exclude",
+        "excludes",
+        multiple=True,
+        help=(
+            "Exclude feature types with these tags — removes from scope (OR-NOT; "
+            f"repeatable). {_TAG_SYNTAX_NOTE}"
+        ),
+    )(func)
+    func = click.option(
+        "--filter",
+        "filters",
+        multiple=True,
+        help=(
+            "Require feature types to have these tags — narrows scope (AND; "
+            f"repeatable). {_TAG_SYNTAX_NOTE}"
+        ),
+    )(func)
+    func = click.option(
+        "--tag",
+        "tags",
+        multiple=True,
+        help=(
+            "Include feature types with these tags — defines scope (OR; repeatable). "
+            f"{_TAG_SYNTAX_NOTE}"
+        ),
+    )(func)
+    return func
+
+
+def build_selector(
+    tags: tuple[str, ...],
+    filters: tuple[str, ...],
+    excludes: tuple[str, ...],
+) -> TagSelector:
+    """Map `tag_selection_options` arguments to a `TagSelector`."""
+    return TagSelector(
+        include_any=tags,
+        require_all=filters,
+        exclude_any=excludes,
+    )

overture/schema/cli/type_analysis.py

@@ -0,0 +1,448 @@
+"""Type introspection and structural analysis for union types."""
+
+import inspect
+from dataclasses import dataclass
+from typing import Annotated as AnnotatedType
+from typing import Any, Literal, get_args, get_origin
+
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+
+from overture.schema.system.feature import resolve_discriminator_field_name
+
+from .types import ErrorLocation, ValidationErrorDict
+
+# Type aliases for structural tuple elements
+StructuralElement = Literal["list_index", "union", "model", "discriminator", "field"]
+StructuralTuple = tuple[StructuralElement, ...]
+
+
+@dataclass
+class UnionMetadata:
+    """Metadata about a union type's structure."""
+
+    is_discriminated: bool
+    discriminator_field: str | None
+    # Map discriminator values to their corresponding model types
+    discriminator_to_model: dict[str, type[BaseModel]]
+    # Map model class names to their types (for non-discriminated unions)
+    model_name_to_model: dict[str, type[BaseModel]]
+    # Nested union metadata for union members that are themselves unions
+    nested_unions: dict[str, "UnionMetadata"]
+
+
+def _extract_literal_value(model: type[BaseModel], field_name: str) -> str | None:
+    """Extract the single Literal value from a model field as a string, if present."""
+    field_info = model.model_fields.get(field_name)
+    if field_info is None or field_info.annotation is None:
+        return None
+    if get_origin(field_info.annotation) is Literal:
+        args = get_args(field_info.annotation)
+        return str(args[0]) if args else None
+    return None
+
+
+def _process_union_member(
+    member: Any,  # noqa: ANN401
+    discriminator_to_model: dict[str, type[BaseModel]],
+    model_name_to_model: dict[str, type[BaseModel]],
+    nested_unions: dict[str, UnionMetadata],
+    discriminator_field: str | None = None,
+) -> None:
+    """Process a single union member, handling nesting recursively.
+
+    Args
+    ----
+        member: A union member type (could be Annotated, BaseModel, or nested union)
+        discriminator_to_model: Dict to populate with discriminator value mappings
+        model_name_to_model: Dict to populate with model name mappings
+        nested_unions: Dict to populate with nested union metadata
+        discriminator_field: The discriminator field name from the parent union annotation
+    """
+    member_origin = get_origin(member)
+
+    # Case 1: Annotated type (might contain nested union or Tag)
+    if member_origin is AnnotatedType:
+        member_args = get_args(member)
+        if not member_args:
+            return
+
+        # Check for discriminator in annotations
+        has_discriminator = any(
+            isinstance(metadata, FieldInfo) and hasattr(metadata, "discriminator")
+            for metadata in member_args[1:]
+        )
+
+        if has_discriminator or get_origin(member_args[0]) is not None:
+            # Nested union (with or without discriminator)
+            nested_metadata = introspect_union(member)
+            nested_unions[str(member)] = nested_metadata
+            discriminator_to_model.update(nested_metadata.discriminator_to_model)
+            # The nested union's discriminator_to_model uses the nested discriminator
+            # field (e.g. "subtype"). Re-extract using the parent discriminator field
+            # (e.g. "type") so leaf models are also reachable by the parent's values.
+            if discriminator_field is not None:
+                for model in nested_metadata.model_name_to_model.values():
+                    value = _extract_literal_value(model, discriminator_field)
+                    if value is not None:
+                        discriminator_to_model[value] = model
+            return
+
+        # Unwrap Annotated to get the actual type (e.g., Annotated[Building, Tag('building')])
+        # and process it recursively
+        _process_union_member(
+            member_args[0],
+            discriminator_to_model,
+            model_name_to_model,
+            nested_unions,
+            discriminator_field,
+        )
+        return
+
+    # Case 2: BaseModel class
+    if inspect.isclass(member) and issubclass(member, BaseModel):
+        model_name_to_model[member.__name__] = member
+
+        if discriminator_field is not None:
+            value = _extract_literal_value(member, discriminator_field)
+            if value is not None:
+                discriminator_to_model[value] = member
+
+
+def introspect_union(union_type: Any) -> UnionMetadata:  # noqa: ANN401
+    """Introspect a union type to extract structural information.
+
+    Analyzes a union type (which may be discriminated or non-discriminated) to
+    extract metadata about its structure, including discriminator fields, model
+    mappings, and nested union information. This metadata is used for structural
+    analysis of validation error paths.
+
+    Args
+    ----
+        union_type: A union type (may be Annotated with discriminator)
+
+    Returns
+    -------
+        UnionMetadata describing the structure of the union
+
+    Examples
+    --------
+        >>> from typing import Annotated, Union
+        >>> from pydantic import Field
+        >>> from overture.schema.buildings import Building, BuildingPart
+        >>> from overture.schema.transportation import Segment, Connector
+        >>> # Discriminated union with 'type' field
+        >>> BuildingUnion = Annotated[
+        ...     Union[Building, BuildingPart],
+        ...     Field(discriminator='type')
+        ... ]
+        >>> metadata = introspect_union(BuildingUnion)
+        >>> metadata.is_discriminated
+        True
+        >>> metadata.discriminator_field
+        'type'
+        >>> 'building' in metadata.discriminator_to_model
+        True
+
+        >>> # Non-discriminated union (using plain Union without discriminator)
+        >>> from overture.schema.transportation import Connector
+        >>> PlainUnion = Union[Building, Connector]
+        >>> metadata = introspect_union(PlainUnion)
+        >>> metadata.is_discriminated
+        False
+        >>> 'Connector' in metadata.model_name_to_model
+        True
+
+        >>> # List of discriminated union (unwraps to element type)
+        >>> FeatureList = list[BuildingUnion]
+        >>> metadata = introspect_union(FeatureList)
+        >>> metadata.is_discriminated
+        True
+    """
+    # Check if this is a list type - unwrap to get the element type
+    origin = get_origin(union_type)
+    if origin is list:
+        args = get_args(union_type)
+        if args:
+            # Recursively introspect the list element type
+            return introspect_union(args[0])
+
+    # Check if this is an Annotated type with a discriminator
+    discriminator_field = None
+    actual_union = union_type
+
+    # Unwrap Annotated ONLY if the top level is Annotated
+    if origin is AnnotatedType:
+        # This is Annotated[Union[...], ...]
+        args = get_args(union_type)
+        if args:
+            # First arg is the actual type, rest are metadata
+            actual_union = args[0]
+            # Look for Field with discriminator in metadata
+            for metadata in args[1:]:
+                if isinstance(metadata, FieldInfo) and hasattr(
+                    metadata, "discriminator"
+                ):
+                    discriminator_field = resolve_discriminator_field_name(
+                        metadata.discriminator
+                    )
+                    break
+
+    # Get union members
+    union_origin = get_origin(actual_union)
+    if union_origin is None:
+        # Not a union, might be a single model
+        union_members = [actual_union]
+    else:
+        union_members = list(get_args(actual_union))
+
+    discriminator_to_model: dict[str, type[BaseModel]] = {}
+    model_name_to_model: dict[str, type[BaseModel]] = {}
+    nested_unions: dict[str, UnionMetadata] = {}
+
+    # Process each union member
+    for member in union_members:
+        _process_union_member(
+            member,
+            discriminator_to_model,
+            model_name_to_model,
+            nested_unions,
+            discriminator_field,
+        )
+
+    return UnionMetadata(
+        is_discriminated=discriminator_field is not None,
+        discriminator_field=discriminator_field,
+        discriminator_to_model=discriminator_to_model,
+        model_name_to_model=model_name_to_model,
+        nested_unions=nested_unions,
+    )
+
+
+def get_or_create_structural_tuple(
+    loc: ErrorLocation,
+    metadata: UnionMetadata,
+    cache: dict[ErrorLocation, StructuralTuple] | None = None,
+) -> StructuralTuple:
+    """Get structural tuple with optional caching for systematic errors.
+
+    When validating collections with systematic errors (e.g., same field missing
+    across many rows), this cache dramatically reduces redundant classification work.
+
+    Args
+    ----
+        loc: The location tuple from a Pydantic validation error
+        metadata: Pre-computed UnionMetadata from introspect_union()
+        cache: Optional dict to cache results (same cache used across all errors)
+
+    Returns
+    -------
+        Tuple of same length as loc with structural labels for each element
+    """
+    if cache is not None and loc in cache:
+        return cache[loc]
+
+    structural = create_structural_tuple(loc, metadata)
+
+    if cache is not None:
+        cache[loc] = structural
+
+    return structural
+
+
+def create_structural_tuple(
+    loc: ErrorLocation,
+    metadata: UnionMetadata,
+) -> StructuralTuple:
+    """Create a structural tuple parallel to error['loc'] describing each element.
+
+    The structural tuple helps identify which parts of an error path are:
+    - list_index: Indices from array iteration
+    - union: Pydantic's tagged union markers (e.g., 'tagged-union[type]')
+    - discriminator: Discriminator values (e.g., 'building', 'segment')
+    - model: Model class names in non-discriminated unions (e.g., 'Segment')
+    - field: Actual data field names (e.g., 'height', 'id')
+
+    Args
+    ----
+        loc: The location tuple from a Pydantic validation error
+        metadata: Pre-computed UnionMetadata from introspect_union()
+
+    Returns
+    -------
+        Tuple of same length as loc with structural labels for each element
+
+    Examples
+    --------
+        >>> from typing import Annotated, Union
+        >>> from pydantic import Field
+        >>> from overture.schema.buildings import Building, BuildingPart
+        >>> from overture.schema.transportation import Connector
+        >>> BuildingUnion = Annotated[
+        ...     Union[Building, BuildingPart],
+        ...     Field(discriminator='type')
+        ... ]
+        >>> PlainUnion = Union[Building, Connector]
+        >>> # Error in first feature of a list, in a building's height field
+        >>> loc = (0, 'tagged-union[type]', 'building', 'height')
+        >>> metadata = introspect_union(BuildingUnion)
+        >>> create_structural_tuple(loc, metadata)
+        ('list_index', 'union', 'discriminator', 'field')
+
+        >>> # Error in a non-discriminated union (uses model name)
+        >>> loc = ('Connector', 'connectors', 0)
+        >>> metadata = introspect_union(PlainUnion)
+        >>> create_structural_tuple(loc, metadata)
+        ('model', 'field', 'list_index')
+
+        >>> # Simple field error (no union involved)
+        >>> loc = ('id',)
+        >>> metadata = introspect_union(Building)
+        >>> create_structural_tuple(loc, metadata)
+        ('field',)
+    """
+
+    def classify(element: str | int) -> StructuralElement:
+        """Classify a single location element."""
+        if isinstance(element, int):
+            return "list_index"
+        if isinstance(element, str):
+            # Pydantic generates various union marker formats
+            if (
+                element.startswith("tagged-union[")
+                or element.startswith("function-after[")
+                or element.startswith("function-wrap[")
+            ):
+                return "union"
+            if element in metadata.model_name_to_model:
+                return "model"
+            if element in metadata.discriminator_to_model:
+                return "discriminator"
+        return "field"
+
+    return tuple(classify(e) for e in loc)
+
+
+def get_item_index(loc: ErrorLocation) -> int | None:
+    """Extract the top-level list index from an error location, if present.
+
+    Args
+    ----
+        loc: The location tuple from a Pydantic validation error
+
+    Returns
+    -------
+        The list index if the error is within a list item, otherwise None
+    """
+    if loc and isinstance(loc[0], int):
+        return loc[0]
+    return None
+
+
+def infer_model_from_error(
+    error: ValidationErrorDict,
+    metadata: UnionMetadata,
+    structural_cache: dict[ErrorLocation, StructuralTuple] | None = None,
+) -> type[BaseModel] | None:
+    """Infer the model type that an error is associated with.
+
+    Uses the LAST (most specific) discriminator or model name found in the
+    error path, as nested unions may have multiple discriminators.
+
+    Args
+    ----
+        error: Pydantic validation error dict
+        metadata: Pre-computed UnionMetadata from introspect_union()
+        structural_cache: Optional cache for structural tuple computation
+
+    Returns
+    -------
+        The inferred model type, or None if it cannot be determined
+    """
+    loc = error["loc"]
+    try:
+        structural = get_or_create_structural_tuple(loc, metadata, structural_cache)
+
+        # Look for discriminator value or model name in the location path
+        # Use the LAST one found (most specific) rather than the first
+        inferred_model = None
+        for element, struct_type in zip(loc, structural, strict=False):
+            if struct_type == "discriminator" and isinstance(element, str):
+                model = metadata.discriminator_to_model.get(element)
+                if model is not None:
+                    inferred_model = model
+            elif struct_type == "model" and isinstance(element, str):
+                model = metadata.model_name_to_model.get(element)
+                if model is not None:
+                    inferred_model = model
+
+        return inferred_model
+    except (KeyError, TypeError, IndexError):
+        # Structural analysis can fail for unexpected error path formats
+        pass
+
+    return None
+
+
+def extract_discriminator_path(
+    loc: ErrorLocation,
+    structural: StructuralTuple,
+) -> ErrorLocation:
+    """Extract the discriminator path from a location tuple.
+
+    The discriminator path includes model names and discriminator values - everything
+    up to (but not including) the first field. List indices and union markers are
+    excluded to prevent false ambiguity when validating lists of features or complex
+    union structures.
+
+    This path uniquely identifies which model variant was selected during validation,
+    allowing errors to be grouped by the type they're associated with.
+
+    Args
+    ----
+        loc: The location tuple from a Pydantic validation error
+        structural: The parallel structural tuple
+
+    Returns
+    -------
+        The discriminator path portion of the location tuple (excluding list_index and union)
+
+    Examples
+    --------
+        >>> # Discriminated union with field error
+        >>> loc = (0, 'tagged-union[type]', 'building', 'height')
+        >>> structural = ('list_index', 'union', 'discriminator', 'field')
+        >>> extract_discriminator_path(loc, structural)
+        ('building',)
+
+        >>> # Non-discriminated union
+        >>> loc = ('Segment', 'connectors', 0)
+        >>> structural = ('model', 'field', 'list_index')
+        >>> extract_discriminator_path(loc, structural)
+        ('Segment',)
+
+        >>> # Root field error (no discriminator)
+        >>> loc = ('id',)
+        >>> structural = ('field',)
+        >>> extract_discriminator_path(loc, structural)
+        ()
+
+        >>> # Multiple list items with same error type are grouped together
+        >>> loc1 = (0, 'tagged-union[type]', 'building', 'height')
+        >>> loc2 = (5, 'tagged-union[type]', 'building', 'height')
+        >>> structural = ('list_index', 'union', 'discriminator', 'field')
+        >>> extract_discriminator_path(loc1, structural)
+        ('building',)
+        >>> extract_discriminator_path(loc2, structural)
+        ('building',)
+        >>> # Both produce same discriminator path despite different list indices and union markers
+    """
+    discriminator_path = []
+    for element, struct_type in zip(loc, structural, strict=False):
+        if struct_type == "field":
+            # Stop at the first field
+            break
+        if struct_type not in ("list_index", "union"):
+            # Include only discriminator and model elements
+            discriminator_path.append(element)
+    return tuple(discriminator_path)

overture/schema/cli/types.py

@@ -0,0 +1,17 @@
+"""Type aliases for CLI module."""
+
+from typing import Any, TypeAlias
+
+from pydantic import BaseModel
+from pydantic_core import ErrorDetails
+
+# Type alias for union types created from Pydantic models
+# This represents either a single model or a discriminated union of models
+UnionType: TypeAlias = type[BaseModel] | Any
+
+# Pydantic validation error dictionary structure
+# In Pydantic v2, ValidationError.errors() returns list[ErrorDetails]
+ValidationErrorDict: TypeAlias = ErrorDetails
+
+# Error location tuple (mix of field names and list indices)
+ErrorLocation: TypeAlias = tuple[str | int, ...]

overture_schema_cli-0.1.1.dev0.dist-info/METADATA

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: overture-schema-cli
+Version: 0.1.1.dev0
+Summary: Command-line interface for Overture Maps schema validation and JSON Schema generation
+License-Expression: MIT
+Requires-Dist: overture-schema-common>=0.1.1
+Requires-Dist: overture-schema-system>=0.1.1
+Requires-Dist: pydantic>=2.13.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: yamlcore>=0.0.4
+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-cli
+
+Command-line interface for validating and working with Overture Maps schema.
+
+This package provides the `overture-schema` command for validating GeoJSON and YAML files against Overture Maps schemas.
+
+## Installation
+
+```bash
+pip install overture-schema-cli
+```
+
+## Usage
+
+```bash
+overture-schema validate <file>
+```
+
+See the main [overture-schema](https://github.com/OvertureMaps/schema) documentation for more details.

overture_schema_cli-0.1.1.dev0.dist-info/RECORD

@@ -0,0 +1,15 @@
+overture/schema/cli/__init__.py,sha256=dk5358XqAdAnJJ1GRqZH6QA-lYyHXf5NgpUU4JEfPJg,561
+overture/schema/cli/__main__.py,sha256=4AxLsgs7Z4GpmyoaIFR2V7dEaICsxkKkOObYGO-cAZw,114
+overture/schema/cli/commands.py,sha256=XoVyzts1tpSsK7mw6b1ouqtM5eVP86_Dib5wZerUuwc,31372
+overture/schema/cli/data_display.py,sha256=CdNvXnc9bRI7N_P4ijaIBE_pE0d5iPvj8muuIhqWbqg,26637
+overture/schema/cli/docstrings.py,sha256=04FUkV0m4tlHleijl7cr2QLJBkKvh3hFT1qwVjNYEXU,686
+overture/schema/cli/error_formatting.py,sha256=3VIpFRk0RzsIcpZpTRzrJ_oyBy1_X0j-fG0IHOQUo2s,22805
+overture/schema/cli/output.py,sha256=gGXAv3iVlEpeR9vu-gFVJ7UsnJA6etuycL_WjPwRxoQ,841
+overture/schema/cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+overture/schema/cli/tag_options.py,sha256=TUABBbmGwr6PCJCSbMflMvsczltCE5e4i2OLD5xEXJU,2060
+overture/schema/cli/type_analysis.py,sha256=WDmCGavb7NYHHTnXaTpm_So5SxHIq84fjqIhfze_mpU,16722
+overture/schema/cli/types.py,sha256=auIcqPAFbRSq7K4vL4pllKMlWsSI7LsUZxc74yS1Z2o,597
+overture_schema_cli-0.1.1.dev0.dist-info/WHEEL,sha256=Lkz__M3n3EKWmzMwHnFILNW2SHO43bOxmbqnBjwb--4,80
+overture_schema_cli-0.1.1.dev0.dist-info/entry_points.txt,sha256=j5ikYUcZV73gU4RHwRHwzKuZBts0BjK0mrOMo5ELQN8,61
+overture_schema_cli-0.1.1.dev0.dist-info/METADATA,sha256=rCWurIj0FzT1gufZPJj7wTYZm0WPJAuhKfl_UKJ2zEk,1151
+overture_schema_cli-0.1.1.dev0.dist-info/RECORD,,

overture_schema_cli-0.1.1.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.6
+Root-Is-Purelib: true
+Tag: py3-none-any

overture_schema_cli-0.1.1.dev0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+overture-schema = overture.schema.cli:cli
+