power-openapi-models (Python)
Typed Python models for the Sienna power system data format — every component, association, and time series row as a validated pydantic v2 model.
Install
pip install power-openapi-models
uv add power-openapi-models
Quickstart
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.
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 RootModels, and the concrete variant is reached through
.root.
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)
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.
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
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:
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:
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 — the schemas these models are generated from, and where schema bugs belong
- @sienna-platform/power-openapi-models — the TypeScript package generated from the same schemas, kept in lockstep by a CI equivalence gate
- PowerOpenAPIModels.jl — the Julia packages generated from the same schemas
- CONTRIBUTING.md — regenerating, and why you must not edit the models by hand
- CHANGELOG.md
License
BSD 3-Clause. See LICENSE.
Metadata
Release files for power-openapi-models 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| power_openapi_models-0.1.0.tar.gz | 59.0 kB | With provenance | Details for power_openapi_models-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| power_openapi_models-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for power_openapi_models-0.1.0-py3-none-any.whl |
Total release size: 111.7 kB
Release files / power_openapi_models-0.1.0.tar.gz
| Download URL | power_openapi_models-0.1.0.tar.gz |
|---|---|
| Size | 59.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd220b4ebf49063220b2e03633ae6e2f1aca6c393dc50c88569314eab981eb42
|
|
BLAKE2b-256 checksum How to use checksums |
d973f7a8044990765777eb0379c4f40abfaa7a65efda6d492cc4cc3c80984d24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / power_openapi_models-0.1.0-py3-none-any.whl
| Download URL | power_openapi_models-0.1.0-py3-none-any.whl |
|---|---|
| Size | 52.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d53a4666c78384c97e52f51c6560c3d80ed36410f1b572c60a2def95c5d18e36
|
|
BLAKE2b-256 checksum How to use checksums |
d50ceed6314a5fe3289ee229168c5ec4efaef987d78e1a1ec394461258d3e184
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logSecurity for power-openapi-models 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for power_openapi_models-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.