Metadata-Version: 2.5
Name: xmas-core
Version: 2.0.0-rc.2
Summary: Model, encode, migrate and store XLeitstelle application schema data
Project-URL: Homepage, https://gitlab.opencode.de/xleitstelle/xmas-core
Project-URL: Issues, https://gitlab.opencode.de/xleitstelle/xmas-core/-/issues
Author-email: Tobias Kraft <tobias.kraft@gv.hamburg.de>, Polichronis Muratidis <polichronis.muratidis@gv.hamburg.de>
License-Expression: EUPL-1.2
License-File: LICENSE.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pydantic :: 2
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.14
Requires-Dist: alembic<2,>=1.16.4
Requires-Dist: asyncpg>=0.29
Requires-Dist: gdal>=3.11.0
Requires-Dist: geoalchemy2>=0.20
Requires-Dist: httpx2<3,>=2.4.0
Requires-Dist: lxml>=6.1.0
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: pydantic-extra-types[semver]
Requires-Dist: pydantic-settings<3,>=2.12.0
Requires-Dist: pydantic>=2.10.3
Requires-Dist: pyyaml>=6
Requires-Dist: sqlalchemy>=2.0.54
Requires-Dist: typer>=0.27.0
Description-Content-Type: text/markdown

# XMAS-Core

[![coverage report](https://gitlab.opencode.de/xleitstelle/xmas-core/badges/main/coverage.svg)](https://gitlab.opencode.de/xleitstelle/xmas-core/-/commits/main)
[![pipeline status](https://gitlab.opencode.de/xleitstelle/xmas-core/badges/main/pipeline.svg)](https://gitlab.opencode.de/xleitstelle/xmas-core/-/commits/main)
[![Latest Release](https://gitlab.opencode.de/xleitstelle/xmas-core/-/badges/release.svg)](https://gitlab.opencode.de/xleitstelle/xmas-core/-/releases)

**[Documentation](https://xleitstelle.usercontent.opencode.de/xmas-core)** | **[Repository](https://gitlab.opencode.de/xleitstelle/xmas-core)**

Model, encode, migrate and store XPlanung, XTrasse and XWärmeplan data. XMAS-Core represents the
application schemas as [Pydantic](https://pydantic.dev) models and is meant as a library for other
applications to build on; the `xmas` CLI exposes the same operations on the command line.

Supported appschemas:

- XPlanung 4.1, 5.4, 6.0, 6.1
- XTrasse 2.0, 2.1
- XWärmeplan 0.9

The UML model of each appschema is the single source of truth. Every schema version is generated
from it into a Pydantic module that also records each class's and property's UML metadata:
stereotype, type name, unit of measure and association ends. Everything else is driven by that metadata,
not by per-class code. The GML and JSON-FG codecs encode and decode any class generically. The database
stores every schema in one generic table, and the navigable roles it follows are derived from the
associations. Migration and style rules are checked against the schemas when they load. A new
schema version starts as generated code, not hand-written classes.

## Features

* Reading and writing GML and [JSON-FG](https://docs.ogc.org/is/21-045r1/21-045r1.html), from files, stdin, URLs or a WFS.
* Storing plans in [PostgreSQL](https://www.postgresql.org)/[PostGIS](https://postgis.net), with Alembic-managed schemas and several tenant schemas served from one process.
* Migrating XPlanung documents to a later version, several hops in one call, with a per-feature report of what could not be carried over.
* Adding style properties (stylesheetId, schriftinhalt) to XPlanung presentational objects based on [defined rules](https://xleitstelle.usercontent.opencode.de/xmas-core/style_defs/).

## Installation

From [PyPI](https://pypi.org/project/xmas-core/) (Python 3.14):
```shell
pip install xmas-core
```
[GDAL](https://gdal.org) and its Python bindings are required; the GDAL system library and Python package versions must match.

With [Pixi](https://pixi.sh), which brings GDAL along:
```shell
git clone https://gitlab.opencode.de/xleitstelle/xmas-core.git
cd xmas-core
pixi install -e prod
```

As a container: images are in the [container registry](https://gitlab.opencode.de/xleitstelle/xmas-core/container_registry) (see [usage](https://xleitstelle.usercontent.opencode.de/xmas-core/how-to-guides/#container-image-usage)).

## Quickstart

```shell
xmas convert input.gml output.json                        # GML -> JSON-FG
xmas convert xplan41.gml xplan61.gml --to 6.1 --report issues.json
xmas db create-schema postgresql://user@host/db
xmas convert input.gml postgresql://user@host/db          # GML -> PostGIS
```

From Python:
```python
from xmas_core import codec
from xmas_core.processing.transform import migrate

collection = codec.read("xplan41.gml")
result = migrate(collection, "6.1")
```

More in the [how-to guides](https://xleitstelle.usercontent.opencode.de/xmas-core/how-to-guides/).

## Development

With [Pixi](https://pixi.sh) installed:
```shell
git clone https://gitlab.opencode.de/xleitstelle/xmas-core.git
cd xmas-core
pixi run dev                              # environment + pre-commit hooks
pixi run test                             # full suite with coverage
pixi run test tests/path.py::test_name    # one test
pixi run test -m db                       # by marker (see pyproject.toml)
pixi run docs-serve                       # documentation preview
```
DB tests start their own PostGIS container (podman or Docker).

The design is documented in the module docstrings; for architecture and workflows see the [Developer Guide](https://gitlab.opencode.de/xleitstelle/xmas-core/-/blob/main/developer_guides/developer_guide.md).

## License

The code in this repository is licensed under the [EUPL-1.2+](https://joinup.ec.europa.eu/collection/eupl)

&copy; [XLeitstelle](https://xleitstelle.de), 2025-2026
