Model

@classmethod
@functools.cache
def enum(cls) -> type[_SupportedAppschema]:
    """Return an enumeration of supported appschemas."""
    members = {
        f"{appschema.prefix.upper()}_{appschema.full_version.major}_{appschema.full_version.minor}": (
            f"{appschema.prefix.upper()}_{appschema.version.replace('.', '_')}",
            appschema,
        )
        for appschema in cls.supported_appschemas()
    }
    # The functional API, called on the metaclass: a checker reads a call on an enum class
    # that defines `__new__` as constructing one member, and types the result `type[Enum]`.
    return cast(
        type[_SupportedAppschema],
        EnumType.__call__(_SupportedAppschema, "SupportedAppschemas", members),
    )

@classmethod
def from_enum(cls, code: str) -> Appschema:
    """Return an Appschema instance from enum code.

    Args:
        code: an appschema code, e.g. `XPLAN_6_0`
    """
    try:
        return cls.enum()[code].appschema
    except KeyError:
        raise NotImplementedError(f"no appschema with code {code!r}") from None

@classmethod
@functools.cache
def from_module(cls, module_name: str) -> Appschema:
    """Builds an Appschema instance from module name.

    Args:
        module_name: the fully qualified module name
    """
    try:
        # module_name is APPSCHEMA_MODULE_NAMES-derived or a cls.__module__, never input
        # nosemgrep: python.lang.security.audit.non-literal-import.non-literal-import
        module = import_module(module_name)
        model_cls: type[RootModel[Any]] = module.Model
    except (ImportError, AttributeError) as exc:
        raise RuntimeError(
            f"Unable to resolve appschema metadata for module {module_name!r}"
        ) from exc

    if not issubclass(model_cls, RootModel):
        raise TypeError(f"expected RootModel, got {model_cls!r}")

    metadata = model_cls.model_fields["root"]

    return cls.model_validate(
        _schema_extra(metadata)
        | {"description": metadata.description, "module": module}
    )

@classmethod
def from_namespace(cls, namespace: str) -> Appschema:
    """Builds an Appschema instance from the appschema's namespace.

    Might return a compatible appschema version if no exact match is found.

    Args:
        namespace: the namespace URI of the appschema
    """
    uri = AnyUrl(namespace)
    candidates: list[Appschema] = []
    for appschema in cls.supported_appschemas():
        if appschema.namespace_uri == uri:
            return appschema
        elif str(appschema.namespace_uri)[:-1] == namespace[:-1]:
            candidates.append(appschema)
    if candidates:
        return max(candidates)
    raise NotImplementedError(f"no appschema with namespace {namespace!r}")

@classmethod
def from_prefix(cls, prefix: str, version: str) -> Appschema:
    """Builds an Appschema instance from the appschema's prefix and version.

    Might return a compatible appschema version if no exact match is found.

    Args:
        prefix: the namespace prefix of the appschema, e.g. `xplan` or `xtrasse`
        version: the version of the appschema; major and minor are required
    """
    sem_version = Version.parse(version, optional_minor_and_patch=True)
    versions = []
    candidates = []
    for appschema in filter(
        lambda appschema: appschema.prefix == prefix, cls.supported_appschemas()
    ):
        # if exact match, return
        if (
            sem_version.major == appschema.full_version.major
            and sem_version.minor == appschema.full_version.minor
        ):
            return appschema
        # if versions are compatible (modules minor version higher or equal), add to candidates
        elif sem_version.is_compatible(appschema.full_version):
            candidates.append(appschema)
        else:
            versions.append(
                f"{appschema.full_version.major}.{appschema.full_version.minor}"
            )
    # return appschema with newer minor version, if found
    # TODO: ensure minor version compatibility without version migration, e.g. via model_validator
    # - in GML it's automatic though
    if candidates:
        return max(candidates)
    if versions:
        e = NotImplementedError(
            f"version {version!r} not supported for prefix {prefix!r}"
        )
        e.add_note(f"available versions: {', '.join(sorted(versions))}")
        raise e
    else:
        raise NotImplementedError(f"no appschema with prefix {prefix!r}")

def model_factory(
    self, name: str, expect: type[BaseType] | None = None
) -> type[BaseType]:
    """Factory method for retrieving the corresponding pydantic model representation of a feature class.

    Args:
        name: name of the feature class or enumeration
        expect: the base class the result has to derive from. Pass `FeatureType` where only
            an identifiable feature will do, so the result is typed as one and a data type
            raises instead of failing later on a missing `id`. Defaults to `BaseType`,
            which accepts either kind - and since every appschema class is exactly one of
            the two (pinned by `test_every_appschema_class_is_a_featuretype_or_a_datatype`),
            the bare call is typed as `type[FeatureType | DataType]` rather than the
            abstract base, so its result can be passed on where either kind is expected.

    Raises:
        ValueError: requested class not found, or it is not a subclass of `expect`.

    Returns:
        The concrete class, typed as the requested `expect`.
    """
    try:
        cls = getattr(self.module, name)
    except AttributeError:
        raise ValueError(f"featuretype {name!r} not found for appschema {self!r}")
    return _ensure_subclass(cls, expect if expect is not None else BaseType)

@classmethod
@functools.cache
def supported_appschemas(cls) -> list[Appschema]:
    """Return a list of currently supported appschemas."""
    return [
        cls.from_module(f"{__package__}.appschema.{module_name}")
        for module_name in APPSCHEMA_MODULE_NAMES
    ]

@classmethod
def from_features(
    cls,
    features: dict[UUID, FeatureType],
    srid: int | None,
    appschema: Appschema,
    *,
    context: dict[str, Any] | None = None,
) -> FeatureCollection:
    """Builds a collection, passing `context` to the reference check.

    The one constructor every repository uses, so the read options a caller can set -
    `DROP_INVALID_REFS` above all - reach the validator the same way whichever format
    was read.

    Args:
        features: The features, keyed by id.
        srid: The collection's spatial reference system identifier. `None`, for a
            document whose SRS could not be resolved, fails validation.
        appschema: The appschema every feature belongs to.
        context: Pydantic validation context; see `check_references_and_srs`.

    Returns:
        The validated collection.
    """
    return cls.model_validate(
        {"features": features, "srid": srid, "appschema": appschema},
        context=context,
    )

def get_features(self) -> Iterator[FeatureType]:
    """Yields features stored in the collection."""
    return (feature for feature in self.features.values())

def get_single_plans(self) -> Iterator[FeatureCollection]:
    """Yields FeatureCollection objects for every plan in the original collection.

    Each one holds exactly one plan, which its `plans` names: a top-level feature type is
    never the part of another, so no closure reaches a second.

    A plan collection is the containment closure of a top-level feature type, derived
    from the appschema's `dependent_part` metadata rather than from hardcoded role
    names: a role marked `target` points at a part the feature owns, a role marked
    `source` points back at its owner. Both directions are followed, since a file may
    populate only one of them.

    A plan is self-contained, so a reference leaving its collection is invalid data and
    raises when the yielded collection validates its references.

    Raises:
        ValueError: If the appschema declares no `dependent_part` metadata, so no
            containment closure can be derived. Every supported appschema declares it.
    """
    if not self.appschema.top_level_featuretypes:
        raise ValueError(
            f"appschema {self.appschema.full_name} declares no ownership metadata, "
            "single plans cannot be derived"
        )
    return self._single_plans()

def make_copy(
    self, with_id_map: bool = False
) -> FeatureCollection | tuple[FeatureCollection, dict[UUID, UUID]]:
    """Return a copy of the collection with new IDs.

    All feature IDs are renewed and respective references are updated.

    Args:
        with_id_map: whether to additionally return a map of old IDs to new IDs
    """
    id_map = {key: uuid7() for key in self.features}
    new_features = {}
    for old_feature in self.features.values():
        new_id = id_map[old_feature.id]
        new_feature = old_feature.model_copy(deep=True)
        new_feature.id = new_id
        for assocation in old_feature.get_associations():
            old_value = getattr(old_feature, assocation)
            if isinstance(old_value, UUID):
                new_value = id_map[old_value]
                setattr(new_feature, assocation, new_value)
            elif isinstance(old_value, list):
                new_list = [
                    id_map[item] if isinstance(item, UUID) else item
                    for item in old_value
                ]
                setattr(new_feature, assocation, new_list)
        new_features[new_id] = new_feature

    new_collection = FeatureCollection(
        features=new_features,
        srid=self.srid,
        appschema=self.appschema,
    )
    if with_id_map:
        return new_collection, id_map
    else:
        return new_collection

@classmethod
@functools.cache
def get_geom_field(cls) -> str | None:
    """Returns the classes geometry field name, if any."""
    for name in cls.model_fields:
        if cls.get_property_info(name).stereotype == "Geometry":
            return name
    return None

def get_geom_srid(self) -> int | None:
    """Returns the object's geometry's SRID, if any."""
    return geom.srid if (geom := self._geom()) else None

@classmethod
@functools.cache
def get_geom_types(cls) -> frozenset[type[GeometryType]]:
    """Returns the types of the geometry attribute."""
    if geom_field := cls.get_geom_field():
        geom_annotation = cls.model_fields[geom_field].annotation
        if not (args := get_args(geom_annotation)):
            return frozenset({cast(type[GeometryType], geom_annotation)})
        return frozenset(arg for arg in args if arg is not NoneType)
    return frozenset()

def get_geom_wkt(self) -> str | None:
    """Returns the object's eWKT geometry's WKT representation withouth SRID, if any."""
    return geom.wkt if (geom := self._geom()) else None

@classmethod
@functools.cache
def appschema(cls) -> Appschema:
    """Return metadata about the application schema for the feature class."""
    # circular: `meta` imports this module. Cached, so the import runs once per class.
    from xmas_core.model.meta import Appschema

    return Appschema.from_module(cls.__module__)

@classmethod
@functools.cache
def get_associations(cls) -> frozenset[str]:
    """Returns the classes association fields."""
    return frozenset(
        assoc
        for assoc in cls.model_fields
        if cls.get_property_info(assoc).stereotype == "Association"
    )

@classmethod
@functools.cache
def get_measure_fields(cls) -> frozenset[str]:
    """Returns the classes measure fields."""
    return frozenset(
        measure
        for measure in cls.model_fields
        if cls.get_property_info(measure).stereotype == "Measure"
    )

@classmethod
@functools.cache
def get_name(cls) -> str:
    """Returns the canonical name of the class."""
    return cls.__name__

@classmethod
@functools.cache
def get_polymorphic_fields(cls) -> frozenset[str]:
    """The data type fields that admit more than one class.

    A mapping does not say which of them it was built from, and where the classes
    share their fields the reader cannot tell either, so these are the fields whose
    values carry their class as `datatype` when a dump is asked for it.
    """
    return frozenset(
        name
        for name in cls.model_fields
        if (prop_info := cls.get_property_info(name)).stereotype == "DataType"
        and isinstance(prop_info.typename, list)
    )

@classmethod
@functools.cache
def get_property_info(cls, name: str) -> PropertyInfo:
    """Property information.

    Args:
        name: The property's name.

    Returns:
        A typed dataclass holding the information.

    Raises:
        AttributeError: The name was not found in the model fields.
    """
    try:
        extra_info = _schema_extra(cls.model_fields[name])
    except KeyError:
        raise AttributeError(f"Unknown property: {name}")
    else:
        stereotype: Final = extra_info["stereotype"]
        typename: str | list[str] = extra_info["typename"]
        return PropertyInfo(
            stereotype=stereotype,
            typename=typename,
            list=not extra_info["multiplicity"].endswith("1"),
            nullable=extra_info["multiplicity"].startswith("0"),
            uom=extra_info.get("uom", None),
            enum=_ensure_subclass(
                getattr(cls.appschema().module, str(typename)), BaseEnum
            )
            if stereotype == "Enumeration"
            else None,
            assoc_info=None
            if stereotype != "Association"
            else AssocInfo(
                reverse=extra_info.get("reverseProperty"),
                source_or_target=extra_info.get("sourceOrTarget"),
                dependent_part=extra_info.get("dependent_part"),
            ),
        )

@classmethod
@functools.cache
def get_geom_field(cls) -> str | None:
    """Returns the classes geometry field name, if any."""
    for name in cls.model_fields:
        if cls.get_property_info(name).stereotype == "Geometry":
            return name
    return None

def get_geom_srid(self) -> int | None:
    """Returns the object's geometry's SRID, if any."""
    return geom.srid if (geom := self._geom()) else None

@classmethod
@functools.cache
def get_geom_types(cls) -> frozenset[type[GeometryType]]:
    """Returns the types of the geometry attribute."""
    if geom_field := cls.get_geom_field():
        geom_annotation = cls.model_fields[geom_field].annotation
        if not (args := get_args(geom_annotation)):
            return frozenset({cast(type[GeometryType], geom_annotation)})
        return frozenset(arg for arg in args if arg is not NoneType)
    return frozenset()

def get_geom_wkt(self) -> str | None:
    """Returns the object's eWKT geometry's WKT representation withouth SRID, if any."""
    return geom.wkt if (geom := self._geom()) else None

def is_type_ok(self, typename: str | builtins.list[str]) -> bool:
    """Return whether a single typename or all typenames in a list are valid."""
    test_types = set(typename) if isinstance(typename, list) else {typename}
    return test_types.issubset(self.type_set)

@classmethod
@functools.cache
def enum(cls) -> type[_SupportedAppschema]:
    """Return an enumeration of supported appschemas."""
    members = {
        f"{appschema.prefix.upper()}_{appschema.full_version.major}_{appschema.full_version.minor}": (
            f"{appschema.prefix.upper()}_{appschema.version.replace('.', '_')}",
            appschema,
        )
        for appschema in cls.supported_appschemas()
    }
    # The functional API, called on the metaclass: a checker reads a call on an enum class
    # that defines `__new__` as constructing one member, and types the result `type[Enum]`.
    return cast(
        type[_SupportedAppschema],
        EnumType.__call__(_SupportedAppschema, "SupportedAppschemas", members),
    )

@classmethod
def from_enum(cls, code: str) -> Appschema:
    """Return an Appschema instance from enum code.

    Args:
        code: an appschema code, e.g. `XPLAN_6_0`
    """
    try:
        return cls.enum()[code].appschema
    except KeyError:
        raise NotImplementedError(f"no appschema with code {code!r}") from None

@classmethod
@functools.cache
def from_module(cls, module_name: str) -> Appschema:
    """Builds an Appschema instance from module name.

    Args:
        module_name: the fully qualified module name
    """
    try:
        # module_name is APPSCHEMA_MODULE_NAMES-derived or a cls.__module__, never input
        # nosemgrep: python.lang.security.audit.non-literal-import.non-literal-import
        module = import_module(module_name)
        model_cls: type[RootModel[Any]] = module.Model
    except (ImportError, AttributeError) as exc:
        raise RuntimeError(
            f"Unable to resolve appschema metadata for module {module_name!r}"
        ) from exc

    if not issubclass(model_cls, RootModel):
        raise TypeError(f"expected RootModel, got {model_cls!r}")

    metadata = model_cls.model_fields["root"]

    return cls.model_validate(
        _schema_extra(metadata)
        | {"description": metadata.description, "module": module}
    )

@classmethod
def from_namespace(cls, namespace: str) -> Appschema:
    """Builds an Appschema instance from the appschema's namespace.

    Might return a compatible appschema version if no exact match is found.

    Args:
        namespace: the namespace URI of the appschema
    """
    uri = AnyUrl(namespace)
    candidates: list[Appschema] = []
    for appschema in cls.supported_appschemas():
        if appschema.namespace_uri == uri:
            return appschema
        elif str(appschema.namespace_uri)[:-1] == namespace[:-1]:
            candidates.append(appschema)
    if candidates:
        return max(candidates)
    raise NotImplementedError(f"no appschema with namespace {namespace!r}")

@classmethod
def from_prefix(cls, prefix: str, version: str) -> Appschema:
    """Builds an Appschema instance from the appschema's prefix and version.

    Might return a compatible appschema version if no exact match is found.

    Args:
        prefix: the namespace prefix of the appschema, e.g. `xplan` or `xtrasse`
        version: the version of the appschema; major and minor are required
    """
    sem_version = Version.parse(version, optional_minor_and_patch=True)
    versions = []
    candidates = []
    for appschema in filter(
        lambda appschema: appschema.prefix == prefix, cls.supported_appschemas()
    ):
        # if exact match, return
        if (
            sem_version.major == appschema.full_version.major
            and sem_version.minor == appschema.full_version.minor
        ):
            return appschema
        # if versions are compatible (modules minor version higher or equal), add to candidates
        elif sem_version.is_compatible(appschema.full_version):
            candidates.append(appschema)
        else:
            versions.append(
                f"{appschema.full_version.major}.{appschema.full_version.minor}"
            )
    # return appschema with newer minor version, if found
    # TODO: ensure minor version compatibility without version migration, e.g. via model_validator
    # - in GML it's automatic though
    if candidates:
        return max(candidates)
    if versions:
        e = NotImplementedError(
            f"version {version!r} not supported for prefix {prefix!r}"
        )
        e.add_note(f"available versions: {', '.join(sorted(versions))}")
        raise e
    else:
        raise NotImplementedError(f"no appschema with prefix {prefix!r}")

def model_factory(
    self, name: str, expect: type[BaseType] | None = None
) -> type[BaseType]:
    """Factory method for retrieving the corresponding pydantic model representation of a feature class.

    Args:
        name: name of the feature class or enumeration
        expect: the base class the result has to derive from. Pass `FeatureType` where only
            an identifiable feature will do, so the result is typed as one and a data type
            raises instead of failing later on a missing `id`. Defaults to `BaseType`,
            which accepts either kind - and since every appschema class is exactly one of
            the two (pinned by `test_every_appschema_class_is_a_featuretype_or_a_datatype`),
            the bare call is typed as `type[FeatureType | DataType]` rather than the
            abstract base, so its result can be passed on where either kind is expected.

    Raises:
        ValueError: requested class not found, or it is not a subclass of `expect`.

    Returns:
        The concrete class, typed as the requested `expect`.
    """
    try:
        cls = getattr(self.module, name)
    except AttributeError:
        raise ValueError(f"featuretype {name!r} not found for appschema {self!r}")
    return _ensure_subclass(cls, expect if expect is not None else BaseType)