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.

Timestamps may omit the offset

The schema says RFC 3339, which requires an offset, but producers write 2024-01-01T00:00:00, so all three packages accept it and read it as UTC. An offset is kept; a bare date or text that is not a timestamp is rejected. Fields are typed power_openapi_models.timestamps.UtcDatetime, so they always hold an aware datetime.

from power_openapi_models.infrastructure_core.models import DataSource

source = DataSource(id=1, fields=[], retrieved_at="2024-01-01T00:00:00")
assert source.retrieved_at.utcoffset().total_seconds() == 0

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, for a document in canonical form. Optional properties that are absent, null or equal to their schema default (an empty trading_hub_associations, say) are omitted rather than written back, top-level keys are sorted after the schema_version stamp, and the file ends with a newline.

Schema versions

Both documents carry a required schema_version: the schema release that wrote them. read_document and read_portfolio_document check it on the raw JSON, before decoding, and raise SchemaVersionError (with outcome, reader and document attributes) unless the document is from this package's schema version or an older one on the same compatibility line. check_schema_version(raw) runs the same rule on a parsed dict and returns the outcome without raising (a non-object root raises pydantic's ValidationError).

from power_openapi_models.document import get_source_schema_version, read_document

doc = read_document("../fixtures/case14_operations.NATURAL_UNITS.json")
print(get_source_schema_version(doc))

write_document(doc, path) stamps this package's version, so reading then writing upgrades a document; upgrade_document(src, dst) does exactly that. To keep the version a document was read at, pass schema_version="source". When that version is older, the encoded document is validated against that version's strict schema first, and the write fails listing every path that version does not know; nothing is dropped. That check needs pip install "power-openapi-models[source-version]".

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.2.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.2.0
File Size Uploaded Provenance Actions
power_openapi_models-0.2.0.tar.gz 160.1 kB With provenance Details for power_openapi_models-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for power-openapi-models 0.2.0
File Interpreter ABI Platform Actions
power_openapi_models-0.2.0-py3-none-any.whl Python 3 none any Details for power_openapi_models-0.2.0-py3-none-any.whl

Total release size: 311.7 kB

Release files / power_openapi_models-0.2.0.tar.gz

Download URL power_openapi_models-0.2.0.tar.gz
Size 160.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6450ae6605ca856b4fddc22d86a3174ca9e5a5d849692285ac6f48a39861a8b9
BLAKE2b-256 checksum
How to use checksums
c001cbe0a041b902e5a13effe9f569647a50ee62ea4dfc32db467b52f9fbd22e
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 Oct 6, 2026.

Transparency log

Release files / power_openapi_models-0.2.0-py3-none-any.whl

Download URL power_openapi_models-0.2.0-py3-none-any.whl
Size 151.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
57228392dee13800fe46e0b610861b9ea75c11d2197254a2744c3bde45dc5527
BLAKE2b-256 checksum
How to use checksums
0dc010e5e0ffe56b7aa0dc9d9079028581e5bddd2c0b658b384aff1d678c806d
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 Oct 6, 2026.

Transparency log

Security for power-openapi-models 0.2.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.2.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 Oct 6, 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