Model

model

Package containing models, the pythonic representation of feature classes.

They inherit from BaseFeature, which extends the Pydantic BaseModel with some utility, and are usually instantiated with the model_factory method. A feature collection is represented by the BaseCollection class.

Example

Load the BP_Plan model for XPlanung v6.0 and instantiate it with some data:

plan = model_factory("BP_Plan", "6.0")
instance = plan.model_validate(
    {
        "name": "Testplan",
        "gemeinde": [
            {
                "ags": "1234"
            }
        ],
        "raeumlicherGeltungsbereich": {
            "srid": 25832,
            "wkt": <WKT-String>
        }
    }
)

model_factory(model_name, model_version, data_type='xplan')

Factory method for retrieving the corresponding pydantic model representation of a feature class.

Parameters:

Name	Type	Description	Default
model_name	str	name of the feature class	required
model_version	str | None	version of the specification release	required
data_type	Literal['xplan', 'xtrasse', 'plu', 'def']	Specification of either XPlanung, INSPIRE PLU, or general definitions used by both application schemas.	'xplan'

Raises:

Type	Description
ValueError	raises error for invalid model name and/or incompatible data version.

Returns:

Name	Type	Description
BaseFeature	BaseFeature	The concrete feature class inheriting from BaseFeature.

Source code in xplan_tools/model/__init__.py

def model_factory(
    model_name: str,
    model_version: str | None,
    data_type: Literal["xplan", "xtrasse", "plu", "def"] = "xplan",
) -> "BaseFeature":
    """Factory method for retrieving the corresponding pydantic model representation of a feature class.

    Args:
        model_name: name of the feature class
        model_version: version of the specification release
        data_type: Specification of either XPlanung, INSPIRE PLU, or general definitions used by both application schemas.

    Raises:
        ValueError: raises error for invalid model name and/or incompatible data version.

    Returns:
        BaseFeature: The concrete feature class inheriting from BaseFeature.
    """
    match data_type:
        case "xplan":
            if model_version[0] == "5":
                model_version = "5.4"
            model = locate(
                f"xplan_tools.model.appschema.xplan{model_version.replace('.', '')}.{model_name.replace('_', '')}"
            )
        case "plu":
            model = locate(
                f"xplan_tools.model.appschema.inspire_plu{model_version.replace('.', '')}.{model_name}"
            )
            model.model_config["extra"] = "ignore"
        case "def":
            model = locate(f"xplan_tools.model.appschema.definitions.{model_name}")
        case "xtrasse":
            model = locate(
                f"xplan_tools.model.appschema.xtrasse{model_version.replace('.', '')}.{model_name.replace('_', '')}"
            )

    if not model:
        raise ValueError(
            f"Invalid model name '{model_name}' or version '{model_version}' for data type '{data_type}'"
        )
    return model

BaseFeature

Bases: BaseModel, GMLAdapter, CoretableAdapter, JsonFGAdapter

Base class for application schema classes.

It extends pydantic BaseModel with Feature-related helper methods as well as conversion capabilities from/to other formats via inheriting from respective adapter classes.

deserialization_hook(data, info) classmethod

Provides deserialization for different formats/representations before validation.

Source code in xplan_tools/model/base.py

@model_validator(mode="before")
@classmethod
def deserialization_hook(cls, data: Any, info: ValidationInfo) -> Any:
    """Provides deserialization for different formats/representations before validation."""
    if isinstance(data, _Element):
        return cls._from_etree(data, info)
    if isinstance(data, Feature):
        return cls._from_coretable(data)
    if isinstance(data, dict) and data.get("featureType", None):
        return cls._from_jsonfg(data, info)
    return data

get_associations() classmethod

Returns the classes association fields.

Source code in xplan_tools/model/base.py

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

get_data_type() classmethod

Return the data type.

Source code in xplan_tools/model/base.py

@classmethod
def get_data_type(cls) -> Literal["xplan", "xtrasse", "plu"]:
    """Return the data type."""
    # return re.match("xplan|plu|xtrasse", self.__module__)[0]
    # liefert bei input 'xplan_tools.model.appschema.xtrasse20'
    # den output 'xplan' statt 'xtrasse'
    return cls.__module__[:-2].split(".")[-1].split("_")[-1]

get_geom_field() classmethod

Returns the classes geometry field name, if any.

Source code in xplan_tools/model/base.py

@classmethod
def get_geom_field(cls) -> Optional[str]:
    """Returns the classes geometry field name, if any."""
    if attr := {
        "position",
        "geltungsbereich",
        "raeumlicherGeltungsbereich",
        "extent",
        "geometry",
    }.intersection(set(cls.model_fields.keys())):
        return attr.pop()

get_geom_srid()

Returns the object's geometry's SRID, if any.

Source code in xplan_tools/model/base.py

def get_geom_srid(self) -> Optional[int]:
    """Returns the object's geometry's SRID, if any."""
    if geom_field := self.get_geom_field():
        if geom := getattr(self, geom_field, None):
            return geom.srid

get_geom_types() classmethod

Returns the canonical name of the FeatureClass.

Source code in xplan_tools/model/base.py

@classmethod
def get_geom_types(cls) -> list["BaseFeature"] | None:
    """Returns the canonical name of the FeatureClass."""
    if geom_field := cls.get_geom_field():
        geom_annotation = cls.model_fields[geom_field].annotation
        args = get_args(geom_annotation)
        if not args:
            geom_model = [geom_annotation]
        else:
            geom_model = [arg for arg in args if arg is not NoneType]
        return geom_model

get_geom_wkt()

Returns the object's eWKT geometry's WKT representation withouth SRID, if any.

Source code in xplan_tools/model/base.py

def get_geom_wkt(self) -> Optional[str]:
    """Returns the object's eWKT geometry's WKT representation withouth SRID, if any."""
    if geom_field := self.get_geom_field():
        if geom := getattr(self, geom_field, None):
            return geom.wkt

get_name() classmethod

Returns the canonical name of the FeatureClass.

Source code in xplan_tools/model/base.py

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

get_properties() classmethod

Returns a slimmed down model with just the properties, i.e. exluding id and geometry attributes as well as utility methods.

Source code in xplan_tools/model/base.py

@classmethod
def get_properties(cls) -> BaseModel:
    """Returns a slimmed down model with just the properties, i.e. exluding id and geometry attributes as well as utility methods."""
    properties = {
        k: (v.annotation, v)
        for k, v in cls.model_fields.items()
        if k not in ["id", cls.get_geom_field()]
    }
    return create_model(cls.get_name(), **properties)

get_property_info(name) classmethod

Property information.

Returns a dict containing the following property information which might be useful e.g. for de-/serialization:

• stereotype: the property's stereotype, e.g. DataType or Association
• typename: the concrete type(s) of the property; may be an array, especially for associations
• list: whether the property has a multiplicity > 1
• nullable: whether the property is optional
• uom: unit of measure for measure types
• enum_info: names, aliases, description and, if available, tokens for codes from enumeration types
• assoc_info: reverse properties and whether it's a source or a target end for associations

Parameters:

Name	Type	Description	Default
name	str	The property's name.	required

Raises:

Type	Description
AttributeError	The name was not found in the model fields.

Source code in xplan_tools/model/base.py

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

    Returns a dict containing the following property information which might be useful e.g. for de-/serialization:

    - `stereotype`: the property's stereotype, e.g. DataType or Association
    - `typename`: the concrete type(s) of the property; may be an array, especially for associations
    - `list`: whether the property has a multiplicity > 1
    - `nullable`: whether the property is optional
    - `uom`: unit of measure for measure types
    - `enum_info`: names, aliases, description and, if available, tokens for codes from enumeration types
    - `assoc_info`: reverse properties and whether it's a source or a target end for associations

    Args:
        name: The property's name.

    Raises:
        AttributeError: The name was not found in the model fields.
    """
    try:
        field_info = cls.model_fields[name]
        extra_info = field_info.json_schema_extra or {}
    except KeyError:
        raise AttributeError(f"Unknown property: {name}")
    else:
        return {
            "stereotype": extra_info.get("stereotype", None),
            "typename": extra_info.get("typename", None),
            "list": get_origin(field_info.annotation) is list
            or list
            in [
                arg.__origin__
                for arg in get_args(field_info.annotation)
                if getattr(arg, "__origin__", None)
            ],
            "nullable": NoneType in get_args(field_info.annotation),
            "uom": extra_info.get("uom", None),
            "enum_info": extra_info.get("enumDescription", None),
            "assoc_info": None
            if extra_info.get("stereotype", None) != "Association"
            else {
                "reverse": extra_info.get("reverseProperty", None),
                "source_or_target": extra_info.get("sourceOrTarget", None),
            },
        }

get_version() classmethod

Returns the application schema version of the object.

Source code in xplan_tools/model/base.py

@classmethod
def get_version(cls) -> str:
    """Returns the application schema version of the object."""
    return f"{cls.__module__[-2:-1]}.{cls.__module__[-1:]}"

model_dump_coretable()

Dumps the model data to a coretable Feature object to store in a database.

Source code in xplan_tools/model/base.py

def model_dump_coretable(self) -> Feature:
    """Dumps the model data to a coretable Feature object to store in a database."""
    return self._to_coretable()

model_dump_gml(data_type='xplan', **kwargs)

Dumps the model data to a GML structure held in an etree.Element.

Source code in xplan_tools/model/base.py

def model_dump_gml(
    self,
    data_type: Literal["xplan", "xtrasse", "plu"] = "xplan",
    **kwargs,
) -> _Element:
    """Dumps the model data to a GML structure held in an etree.Element."""
    return self._to_etree(data_type, **kwargs)

model_dump_jsonfg(**kwargs)

Dumps the model data to a JSON-FG object.

Source code in xplan_tools/model/base.py

def model_dump_jsonfg(
    self,
    **kwargs,
) -> dict:
    """Dumps the model data to a JSON-FG object."""
    return self._to_jsonfg(**kwargs)

BaseCollection

Bases: BaseModel

Container for features that provides validation of references.

The features are stored in a dictionary with their ID as key and the feature instance as value.

add_style_properties(to_text=False, always_populate_schriftinhalt=False)

Add styling properties to presentational objects.

This method parses object (dientZurDarstellungVon) and property (art) references from presentational objects and derives styling information (stylesheetId, schriftinhalt) based on a set of defined rules.

Parameters:

Name	Type	Description	Default
to_text	bool	Whether to convert symbolic presentational objects to textual ones. Defaults to False.	False
always_populate_schriftinhalt	bool	Populate schriftinhalt even if a rule has no text template.	False

Source code in xplan_tools/model/base.py

def add_style_properties(
    self, to_text: bool = False, always_populate_schriftinhalt: bool = False
) -> None:
    """Add styling properties to presentational objects.

    This method parses object (dientZurDarstellungVon) and property (art) references from
    presentational objects and derives styling information (stylesheetId, schriftinhalt)
    based on a set of defined rules.

    Args:
        to_text: Whether to convert symbolic presentational objects to textual ones. Defaults to False.
        always_populate_schriftinhalt: Populate `schriftinhalt` even if a rule has no text template.
    """
    logger.info("adding style properties to collection")

    for obj in filter(lambda x: hasattr(x, "stylesheetId"), self.get_features()):
        if not obj.dientZurDarstellungVon:
            logger.info(
                f"Feature {obj.id}: dientZurDarstellungVon not set, skipping"
            )
            continue
        elif len(obj.dientZurDarstellungVon) > 1:
            logger.warning(
                f"Feature {obj.id}: references to multiple objects '{obj.dientZurDarstellungVon}' not supported, skipping"
            )
            continue
        elif not obj.art:
            logger.info(f"Feature {obj.id}: art not set, skipping")
            continue
        ref_obj = self.features.get(str(obj.dientZurDarstellungVon[0]))
        new_obj = add_style_properties_to_feature(
            obj, ref_obj, to_text, always_populate_schriftinhalt
        )
        self.features[obj.id] = new_obj

    logger.info("finished adding style properties to collection")

check_references_and_srs()

Checks if all objects referenced via UUID are part of the collection and if all features have the same SRS.

Source code in xplan_tools/model/base.py

@model_validator(mode="after")
def check_references_and_srs(self) -> "BaseCollection":
    """Checks if all objects referenced via UUID are part of the collection and if all features have the same SRS."""
    logger.debug("checking feature references")
    keys = self.features.keys()
    srids = []
    for feature in self.features.values():
        if srid := feature.get_geom_srid():
            if srids and srid not in srids:
                raise ValueError(
                    f"Multiple SRS within collection not supported: SRID {srid} != {srids[0]} for feature {feature.id}"
                )
            else:
                srids.append(srid)
        for name, value in feature:
            if isinstance(value, UUID):
                if str(value) not in keys:
                    raise ValueError(
                        f"reference {name}: {value} in object {feature.id} not resolvable"
                    )
            elif isinstance(value, list):
                for item in value:
                    if isinstance(item, UUID) and str(item) not in keys:
                        raise ValueError(
                            f"reference {name}: {item} in object {feature.id} not resolvable"
                        )
    logger.debug("all feature references resolvable")
    return self

get_features()

Yields features stored in the collection.

Source code in xplan_tools/model/base.py

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

get_single_plans(with_name=False)

Yields BaseCollection objects for every plan in the original collection.

Source code in xplan_tools/model/base.py

def get_single_plans(
    self, with_name: bool = False
) -> Iterator["BaseCollection"] | Iterator[Tuple[str, "BaseCollection"]]:
    """Yields BaseCollection objects for every plan in the original collection."""
    for plan in filter(lambda x: "Plan" in x.get_name(), self.features.values()):
        collection = {plan.id: plan}
        for attr in ["texte", "begruendungsTexte"]:
            if refs := getattr(plan, attr):
                collection.update(
                    {str(ref): self.features[str(ref)] for ref in refs}
                )
        for bereich in filter(
            lambda x: str(getattr(x, "gehoertZuPlan", "")) == plan.id,
            self.features.values(),
        ):
            collection[bereich.id] = bereich
            for feature in filter(
                lambda x: str(getattr(x, "gehoertZuBereich", "")) == bereich.id,
                self.features.values(),
            ):
                collection[feature.id] = feature
                for attr in ["refBegruendungInhalt", "refTextInhalt"]:
                    if refs := getattr(feature, attr, None):
                        collection.update(
                            {str(ref): self.features[str(ref)] for ref in refs}
                        )
            if raster := getattr(bereich, "rasterBasis", None):
                collection[str(raster)] = self.features[str(raster)]
        yield (
            plan.name,
            BaseCollection(features=collection, srid=self.srid)
            if with_name
            else BaseCollection(features=collection, srid=self.srid),
        )

list_to_dict(data) classmethod

Takes a list of BaseFeatures and returns a BaseCollection dict.

Source code in xplan_tools/model/base.py

@model_validator(mode="before")
@classmethod
def list_to_dict(cls, data: Any) -> Any:
    """Takes a list of BaseFeatures and returns a BaseCollection dict."""
    if isinstance(data, list):
        data_dict = {}
        for feature in data:
            if not isinstance(feature, BaseFeature):
                raise TypeError(
                    f"Object is not an instance of BaseFeature: {feature}"
                )
            data_dict[feature.id] = feature
        return data_dict
    return data