Skip to main content

power-openapi-models (Python)

PyPI Python CI License

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.

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)

Source distribution for power-openapi-models 0.1.0
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)

Table of built distributions (wheels) for power-openapi-models 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page