power-openapi-models 0.1.0__tar.gz

power_openapi_models-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 Alliance for Energy Innovation, LLC and QXT Energy
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

power_openapi_models-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: power-openapi-models
+Version: 0.1.0
+Summary: Typed Python models for the Sienna power system data format
+Author: Sienna Platform
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/Sienna-Platform/power-openapi-models
+Project-URL: Repository, https://github.com/Sienna-Platform/power-openapi-models
+Project-URL: Issues, https://github.com/Sienna-Platform/power-openapi-models/issues
+Project-URL: Changelog, https://github.com/Sienna-Platform/power-openapi-models/blob/main/CHANGELOG.md
+Keywords: power-systems,energy,openapi,pydantic,sienna,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pyright>=1.1.380; extra == "dev"
+Requires-Dist: datamodel-code-generator; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# power-openapi-models (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/power-openapi-models.svg)](https://pypi.org/project/power-openapi-models/)
+[![Python](https://img.shields.io/pypi/pyversions/power-openapi-models.svg)](https://pypi.org/project/power-openapi-models/)
+[![CI](https://github.com/Sienna-Platform/power-openapi-models/actions/workflows/test.yml/badge.svg)](https://github.com/Sienna-Platform/power-openapi-models/actions/workflows/test.yml)
+[![License](https://img.shields.io/pypi/l/power-openapi-models.svg)](../LICENSE)
+
+Typed Python models for the Sienna power system data format — every
+component, association, and time series row as a validated pydantic v2
+model.
+
+> [!WARNING]
+> **Pre-release.** Every version below `1.0` can change incompatibly in any
+> release; no stability is promised until `1.0`. Under PEP 440, `0.1.0` is
+> not itself a "pre-release" version, so `pip install power-openapi-models`
+> installs it with no `--pre` flag and no warning. Pin an exact version.
+
+## Install
+
+```bash
+pip install power-openapi-models
+```
+
+```bash
+uv add power-openapi-models
+```
+
+## Quickstart
+
+```python
+from power_openapi_models.core.models import ACBus, ACBusType
+
+bus = ACBus(
+    id=1,
+    name="bus-1",
+    available=True,
+    number=1,
+    bustype=ACBusType.PV,
+    base_voltage=230.0,
+)
+print(bus.name, bus.bustype, bus.base_voltage)
+print(bus.model_dump_json(exclude_none=True))
+```
+
+## The modules
+
+| Module | Holds | Reach for it when |
+|---|---|---|
+| `infrastructure_core` | Units (`UnitSystem`), function data, shared value shapes (`MinMax`, `UpDown`, ...) | You need a domain-neutral building block used across every other module |
+| `core` | Power enums, curves, costs, buses | You are working with shared power types or need `ACBus`/`DCBus` |
+| `operations` | Topology, branches, injections, services, market | You are working with the grid itself |
+| `investments` | Technologies, financials, requirements, regions | You are doing capacity expansion |
+| `dynamics` | Dynamic generator and inverter components | You are doing transient stability |
+| `timeseries` | The six time series association types | You are handling forecasts or profiles |
+| `document` | `SystemDocument`, the hand-written envelope, plus `read_document`/`write_document` | You are loading or saving a whole serialized system |
+
+Import a class from its module's `.models` submodule:
+`from power_openapi_models.core.models import ACBus`.
+
+## Concepts worth knowing before you start
+
+### Unit systems
+
+Many component fields carry a sibling `*_units` field (for example
+`ThermalStandard.power_units`) that says how to read every other power-family
+field on that same component. There is no document-level unit system: each
+component blob is self-describing.
+
+```python
+from power_openapi_models.infrastructure_core.models import UnitSystem
+
+print(list(UnitSystem))
+print(UnitSystem.NATURAL_UNITS.value)
+```
+
+`NATURAL_UNITS` means values are in physical units — MW, MVAr, kV, ohm.
+`COMPONENT_BASE` means per-unit against the component's own recorded
+`base_power`. Getting this wrong is the most common source of
+wrong-by-a-factor-of-100 bugs across the ecosystem.
+
+### Discriminated unions carry a `.root`
+
+Several types are one of several shapes, chosen by a discriminator field.
+They are pydantic `RootModel`s, and the concrete variant is reached through
+`.root`.
+
+```python
+from power_openapi_models.infrastructure_core.models import (
+    FunctionData,
+    LinearFunctionData,
+)
+
+parsed = FunctionData.model_validate(
+    {"function_type": "LINEAR", "proportional_term": 2.0, "constant_term": 5.0}
+)
+assert isinstance(parsed.root, LinearFunctionData)
+print(parsed.root.proportional_term)
+```
+
+> [!IMPORTANT]
+> **This differs from the TypeScript package**, where the same types are zod
+> unions and `parse` returns the variant directly, with no `.root`. Porting
+> code between the two languages, this is the first thing that breaks.
+
+### Components reference each other by integer id
+
+There are no object references on the wire. `ThermalStandard.bus`, for
+example, names its bus by id, and resolving it is the reader's job.
+
+```python
+from power_openapi_models.core.models import ACBus
+
+buses = [
+    ACBus(id=1, name="a", available=True, number=1, base_voltage=230.0),
+    ACBus(id=2, name="b", available=True, number=2, base_voltage=230.0),
+]
+by_id = {bus.id: bus for bus in buses}
+print(by_id[2].name)
+```
+
+### The document envelope
+
+A serialized system is one object: `components` keyed by type name, a flat
+`supplemental_attributes` array, several association arrays, and
+`time_series_storage_file` naming a sidecar. There is no document-level
+`unit_system` or `base_power` — `SystemDocument` forbids both fields
+outright, since every component already carries its own basis.
+
+**Time series values never appear in the document.**
+`time_series_associations` carries only the metadata rows; the values live
+in the sidecar named by `time_series_storage_file`, and reading it is the
+consumer's job.
+
+## Round-tripping
+
+`read_document` followed by `write_document` reproduces the input byte for
+byte. Fields the input never carried stay omitted rather than being written
+back as explicit nulls, top-level keys are sorted, and the file ends with a
+newline.
+
+## Worked example
+
+```python
+from power_openapi_models.document import read_document
+
+doc = read_document("../fixtures/case14_operations.NATURAL_UNITS.json")
+
+buses = doc.components["ACBus"]
+generators = doc.components["ThermalStandard"]
+print(f"{len(buses)} buses, {len(generators)} thermal generators")
+
+gen = generators[0]
+limits = gen["active_power_limits"]
+print(gen["name"], "active power limits (MW):", limits["min"], "-", limits["max"])
+```
+
+## Validation
+
+Bad data raises `pydantic.ValidationError`, which names the field and the
+rule:
+
+```python
+from pydantic import ValidationError
+
+from power_openapi_models.infrastructure_core.models import LinearFunctionData
+
+try:
+    LinearFunctionData(function_type="NOT_A_TYPE", proportional_term=1.0, constant_term=0.0)
+except ValidationError as exc:
+    print(exc.error_count(), "error(s)")
+    print(exc.errors()[0]["loc"], exc.errors()[0]["type"])
+```
+
+## Type checking
+
+The package ships a PEP 561 `py.typed` marker, so mypy and pyright pick the
+annotations up with no configuration.
+
+## Versioning and provenance
+
+These models are generated. The schema release they came from is recorded
+in the package:
+
+```python
+import power_openapi_models
+
+print(power_openapi_models.__version__)
+print(power_openapi_models.__schema_version__)
+```
+
+Quote `__schema_version__` in bug reports — it identifies the exact schema
+release the models were built from.
+
+## Links
+
+- [SiennaSchemas](https://github.com/Sienna-Platform/SiennaSchemas) — the schemas these models are generated from, and where schema bugs belong
+- [@sienna-platform/power-openapi-models](../typescript/README.md) — the TypeScript package generated from the same schemas, kept in lockstep by a CI equivalence gate
+- [PowerOpenAPIModels.jl](https://github.com/Sienna-Platform/PowerOpenAPIModels) — the Julia packages generated from the same schemas
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — regenerating, and why you must not edit the models by hand
+- [CHANGELOG.md](../CHANGELOG.md)
+
+## License
+
+BSD 3-Clause. See [LICENSE](../LICENSE).

power_openapi_models-0.1.0/README.md

@@ -0,0 +1,204 @@
+# power-openapi-models (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/power-openapi-models.svg)](https://pypi.org/project/power-openapi-models/)
+[![Python](https://img.shields.io/pypi/pyversions/power-openapi-models.svg)](https://pypi.org/project/power-openapi-models/)
+[![CI](https://github.com/Sienna-Platform/power-openapi-models/actions/workflows/test.yml/badge.svg)](https://github.com/Sienna-Platform/power-openapi-models/actions/workflows/test.yml)
+[![License](https://img.shields.io/pypi/l/power-openapi-models.svg)](../LICENSE)
+
+Typed Python models for the Sienna power system data format — every
+component, association, and time series row as a validated pydantic v2
+model.
+
+> [!WARNING]
+> **Pre-release.** Every version below `1.0` can change incompatibly in any
+> release; no stability is promised until `1.0`. Under PEP 440, `0.1.0` is
+> not itself a "pre-release" version, so `pip install power-openapi-models`
+> installs it with no `--pre` flag and no warning. Pin an exact version.
+
+## Install
+
+```bash
+pip install power-openapi-models
+```
+
+```bash
+uv add power-openapi-models
+```
+
+## Quickstart
+
+```python
+from power_openapi_models.core.models import ACBus, ACBusType
+
+bus = ACBus(
+    id=1,
+    name="bus-1",
+    available=True,
+    number=1,
+    bustype=ACBusType.PV,
+    base_voltage=230.0,
+)
+print(bus.name, bus.bustype, bus.base_voltage)
+print(bus.model_dump_json(exclude_none=True))
+```
+
+## The modules
+
+| Module | Holds | Reach for it when |
+|---|---|---|
+| `infrastructure_core` | Units (`UnitSystem`), function data, shared value shapes (`MinMax`, `UpDown`, ...) | You need a domain-neutral building block used across every other module |
+| `core` | Power enums, curves, costs, buses | You are working with shared power types or need `ACBus`/`DCBus` |
+| `operations` | Topology, branches, injections, services, market | You are working with the grid itself |
+| `investments` | Technologies, financials, requirements, regions | You are doing capacity expansion |
+| `dynamics` | Dynamic generator and inverter components | You are doing transient stability |
+| `timeseries` | The six time series association types | You are handling forecasts or profiles |
+| `document` | `SystemDocument`, the hand-written envelope, plus `read_document`/`write_document` | You are loading or saving a whole serialized system |
+
+Import a class from its module's `.models` submodule:
+`from power_openapi_models.core.models import ACBus`.
+
+## Concepts worth knowing before you start
+
+### Unit systems
+
+Many component fields carry a sibling `*_units` field (for example
+`ThermalStandard.power_units`) that says how to read every other power-family
+field on that same component. There is no document-level unit system: each
+component blob is self-describing.
+
+```python
+from power_openapi_models.infrastructure_core.models import UnitSystem
+
+print(list(UnitSystem))
+print(UnitSystem.NATURAL_UNITS.value)
+```
+
+`NATURAL_UNITS` means values are in physical units — MW, MVAr, kV, ohm.
+`COMPONENT_BASE` means per-unit against the component's own recorded
+`base_power`. Getting this wrong is the most common source of
+wrong-by-a-factor-of-100 bugs across the ecosystem.
+
+### Discriminated unions carry a `.root`
+
+Several types are one of several shapes, chosen by a discriminator field.
+They are pydantic `RootModel`s, and the concrete variant is reached through
+`.root`.
+
+```python
+from power_openapi_models.infrastructure_core.models import (
+    FunctionData,
+    LinearFunctionData,
+)
+
+parsed = FunctionData.model_validate(
+    {"function_type": "LINEAR", "proportional_term": 2.0, "constant_term": 5.0}
+)
+assert isinstance(parsed.root, LinearFunctionData)
+print(parsed.root.proportional_term)
+```
+
+> [!IMPORTANT]
+> **This differs from the TypeScript package**, where the same types are zod
+> unions and `parse` returns the variant directly, with no `.root`. Porting
+> code between the two languages, this is the first thing that breaks.
+
+### Components reference each other by integer id
+
+There are no object references on the wire. `ThermalStandard.bus`, for
+example, names its bus by id, and resolving it is the reader's job.
+
+```python
+from power_openapi_models.core.models import ACBus
+
+buses = [
+    ACBus(id=1, name="a", available=True, number=1, base_voltage=230.0),
+    ACBus(id=2, name="b", available=True, number=2, base_voltage=230.0),
+]
+by_id = {bus.id: bus for bus in buses}
+print(by_id[2].name)
+```
+
+### The document envelope
+
+A serialized system is one object: `components` keyed by type name, a flat
+`supplemental_attributes` array, several association arrays, and
+`time_series_storage_file` naming a sidecar. There is no document-level
+`unit_system` or `base_power` — `SystemDocument` forbids both fields
+outright, since every component already carries its own basis.
+
+**Time series values never appear in the document.**
+`time_series_associations` carries only the metadata rows; the values live
+in the sidecar named by `time_series_storage_file`, and reading it is the
+consumer's job.
+
+## Round-tripping
+
+`read_document` followed by `write_document` reproduces the input byte for
+byte. Fields the input never carried stay omitted rather than being written
+back as explicit nulls, top-level keys are sorted, and the file ends with a
+newline.
+
+## Worked example
+
+```python
+from power_openapi_models.document import read_document
+
+doc = read_document("../fixtures/case14_operations.NATURAL_UNITS.json")
+
+buses = doc.components["ACBus"]
+generators = doc.components["ThermalStandard"]
+print(f"{len(buses)} buses, {len(generators)} thermal generators")
+
+gen = generators[0]
+limits = gen["active_power_limits"]
+print(gen["name"], "active power limits (MW):", limits["min"], "-", limits["max"])
+```
+
+## Validation
+
+Bad data raises `pydantic.ValidationError`, which names the field and the
+rule:
+
+```python
+from pydantic import ValidationError
+
+from power_openapi_models.infrastructure_core.models import LinearFunctionData
+
+try:
+    LinearFunctionData(function_type="NOT_A_TYPE", proportional_term=1.0, constant_term=0.0)
+except ValidationError as exc:
+    print(exc.error_count(), "error(s)")
+    print(exc.errors()[0]["loc"], exc.errors()[0]["type"])
+```
+
+## Type checking
+
+The package ships a PEP 561 `py.typed` marker, so mypy and pyright pick the
+annotations up with no configuration.
+
+## Versioning and provenance
+
+These models are generated. The schema release they came from is recorded
+in the package:
+
+```python
+import power_openapi_models
+
+print(power_openapi_models.__version__)
+print(power_openapi_models.__schema_version__)
+```
+
+Quote `__schema_version__` in bug reports — it identifies the exact schema
+release the models were built from.
+
+## Links
+
+- [SiennaSchemas](https://github.com/Sienna-Platform/SiennaSchemas) — the schemas these models are generated from, and where schema bugs belong
+- [@sienna-platform/power-openapi-models](../typescript/README.md) — the TypeScript package generated from the same schemas, kept in lockstep by a CI equivalence gate
+- [PowerOpenAPIModels.jl](https://github.com/Sienna-Platform/PowerOpenAPIModels) — the Julia packages generated from the same schemas
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — regenerating, and why you must not edit the models by hand
+- [CHANGELOG.md](../CHANGELOG.md)
+
+## License
+
+BSD 3-Clause. See [LICENSE](../LICENSE).

power_openapi_models-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "power-openapi-models"
+version = "0.1.0"
+description = "Typed Python models for the Sienna power system data format"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Sienna Platform" }]
+keywords = [
+    "power-systems",
+    "energy",
+    "openapi",
+    "pydantic",
+    "sienna",
+    "time-series",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Sienna-Platform/power-openapi-models"
+Repository = "https://github.com/Sienna-Platform/power-openapi-models"
+Issues = "https://github.com/Sienna-Platform/power-openapi-models/issues"
+Changelog = "https://github.com/Sienna-Platform/power-openapi-models/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.6",
+    "pytest>=8",
+    "pyright>=1.1.380",
+    "datamodel-code-generator",
+    "build",
+    "twine",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+power_openapi_models = ["py.typed", "_schema_version.txt"]
+
+[tool.ruff]
+line-length = 100
+# models.py files are generated; their formatting is the generator's business.
+# SiennaSchemas is a sibling checkout (local dev) or a CI-only checkout for the
+# document tests (see .github/workflows/test.yml); its own scripts are out of scope.
+extend-exclude = ["src/power_openapi_models/*/models.py", "SiennaSchemas"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+# E741 (ambiguous variable name): the generated models are field-for-field with
+# SiennaSchemas' power-system quantities, which use standard electrical-engineering
+# single-letter names (e.g. `l` for inductance) -- not something to rename away from.
+ignore = ["E741"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.pyright]
+include = ["src"]
+extraPaths = ["src"]
+pythonVersion = "3.10"

power_openapi_models-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

power_openapi_models-0.1.0/src/power_openapi_models/__init__.py

@@ -0,0 +1,52 @@
+"""Typed Python models for the Sienna power system data format.
+
+Generated from SiennaSchemas. See `__schema_version__` for the schema release
+these models were built from.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+from pathlib import Path
+
+from power_openapi_models import (
+    core,
+    document,
+    dynamics,
+    infrastructure_core,
+    investments,
+    operations,
+    timeseries,
+)
+
+try:
+    __version__ = _version("power-openapi-models")
+except PackageNotFoundError:  # running from a source tree, not installed
+    __version__ = "0.0.0.dev0"
+
+
+def _read_schema_version() -> str:
+    """The SiennaSchemas release these models were generated from.
+
+    Shipped as package data so it is answerable at runtime -- the first
+    question worth asking about a generated model is which schema produced it.
+    """
+    marker = Path(__file__).parent / "_schema_version.txt"
+    try:
+        return marker.read_text().strip()
+    except OSError:
+        return "unknown"
+
+
+__schema_version__ = _read_schema_version()
+
+__all__ = [
+    "core",
+    "document",
+    "dynamics",
+    "infrastructure_core",
+    "investments",
+    "operations",
+    "timeseries",
+    "__version__",
+    "__schema_version__",
+]

power_openapi_models-0.1.0/src/power_openapi_models/_schema_version.txt

@@ -0,0 +1 @@
+v0.1.0

power_openapi_models-0.1.0/src/power_openapi_models/core/__init__.py

@@ -0,0 +1,5 @@
+"""Auto-generated stubs for the core domain."""
+
+from power_openapi_models.core import models
+
+__all__ = ["models"]