leancpms-cli 0.1.0__py3-none-any.whl

cpms/manifest/documents.py

@@ -0,0 +1,118 @@
+"""Reading, writing and diffing manifest documents. No framework, no I/O."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+from pydantic import TypeAdapter, ValidationError
+
+from .schema import MANIFEST_VERSION, Document
+
+_adapter: TypeAdapter[Document] = TypeAdapter(Document)
+
+
+class ManifestError(ValueError):
+    """A document that does not validate. `errors` is a list of readable lines."""
+
+    def __init__(self, errors: list[str]):
+        super().__init__("; ".join(errors))
+        self.errors = errors
+
+
+def parse(data: Any) -> Document:
+    try:
+        return _adapter.validate_python(data)
+    except ValidationError as e:
+        raise ManifestError(
+            [f"{'.'.join(str(p) for p in err['loc']) or '(document)'}: {err['msg']}" for err in e.errors()]
+        ) from None
+
+
+def parse_yaml(text: str) -> list[Document]:
+    """One or more documents separated by `---`."""
+    try:
+        raw = [d for d in yaml.safe_load_all(text) if d is not None]
+    except yaml.YAMLError as e:
+        raise ManifestError([f"YAML: {e}"]) from None
+    return [parse(d) for d in raw]
+
+
+def json_schema() -> dict[str, Any]:
+    """The JSON Schema of a document of any kind, for editors (`cpms manifest schema`).
+
+    It says less than `parse`: the checks across fields (budget within the
+    fuse, unique keys, references between plans and tariffs, valid time
+    zones) are only in the validators, so `validate` and `plan` still decide.
+    """
+    return {"$schema": "https://json-schema.org/draft/2020-12/schema",
+            "title": f"LeanCPMS manifest document ({MANIFEST_VERSION})",
+            **_adapter.json_schema()}
+
+
+def to_data(doc: Document) -> dict[str, Any]:
+    """The stored form: JSON-safe, money as strings, defaults left out."""
+    return doc.model_dump(mode="json", by_alias=True, exclude_defaults=True)
+
+
+def to_yaml(docs: list[dict[str, Any]]) -> str:
+    return "---\n".join(yaml.safe_dump(d, sort_keys=False, allow_unicode=True) for d in docs)
+
+
+def digest(data: dict[str, Any] | None) -> str:
+    """Stable hash of a stored document; `apply` uses it for optimistic concurrency."""
+    if data is None:
+        return "none"
+    return hashlib.sha256(json.dumps(data, sort_keys=True).encode()).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class Change:
+    op: str  # "+", "-", "~"
+    path: str
+    old: Any = None
+    new: Any = None
+
+    def __str__(self) -> str:
+        if self.op == "~":
+            return f"~ {self.path}: {_short(self.old)} → {_short(self.new)}"
+        return f"{self.op} {self.path}"
+
+
+def _short(v: Any) -> str:
+    s = json.dumps(v, ensure_ascii=False) if not isinstance(v, str) else v
+    return s if len(s) <= 60 else s[:57] + "..."
+
+
+def _keyed(items: list[Any]) -> bool:
+    return bool(items) and all(isinstance(i, dict) and "key" in i for i in items)
+
+
+def diff(old: Any, new: Any, path: str = "") -> list[Change]:
+    """Changes from `old` to `new`; lists of objects with `key` are matched by key."""
+    if isinstance(old, dict) and isinstance(new, dict):
+        out: list[Change] = []
+        for k in list(old) + [k for k in new if k not in old]:
+            p = f"{path}.{k}" if path else k
+            if k not in new:
+                out.append(Change("-", p, old[k], None))
+            elif k not in old:
+                out.append(Change("+", p, None, new[k]))
+            else:
+                out.extend(diff(old[k], new[k], p))
+        return out
+    if isinstance(old, list) and isinstance(new, list) and (_keyed(old) or _keyed(new)) and (
+        all(isinstance(i, dict) and "key" in i for i in old + new)
+    ):
+        o = {i["key"]: i for i in old}
+        n = {i["key"]: i for i in new}
+        out = []
+        for k in o:
+            p = f"{path}[{k}]"
+            out.extend([Change("-", p, o[k], None)] if k not in n else diff(o[k], n[k], p))
+        out.extend(Change("+", f"{path}[{k}]", None, n[k]) for k in n if k not in o)
+        return out
+    return [] if old == new else [Change("~", path, old, new)]

cpms/manifest/schema.py

@@ -0,0 +1,374 @@
+"""The manifest: three kinds of document per organization (architecture §6.1).
+
+Plain Pydantic, no framework. The same models are the JSON Schema of the
+files, the payload of the API, and the balancer's input.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from decimal import Decimal
+from typing import Annotated, Literal, Sequence, Union
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from pydantic import (
+    BaseModel,
+    AfterValidator,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    StringConstraints,
+    WithJsonSchema,
+    model_validator,
+)
+
+MANIFEST_VERSION = "cpms/v1"
+
+Key = Annotated[str, StringConstraints(pattern=r"^[a-z0-9][a-z0-9_-]{0,62}$")]
+Phase = Literal["L1", "L2", "L3"]
+
+
+def _no_float(value: object) -> object:
+    # YAML turns 4.50 into a float, and a float is not money. Quote it.
+    if isinstance(value, float):
+        raise ValueError("amounts must be quoted strings, e.g. \"4.50\", not floats")
+    return value
+
+
+# What the JSON Schema says (an editor's view): an integer or a string, never a float.
+_DECIMAL_TEXT = WithJsonSchema({"anyOf": [{"type": "integer"}, {"type": "string"}],
+                                "description": 'quoted, e.g. "4.50"; a float is not money'})
+Money = Annotated[Decimal, BeforeValidator(_no_float), _DECIMAL_TEXT]
+
+
+def _quoted(value: object) -> object:
+    # A coordinate as a YAML float loses its trailing zeros; OCPI sends it as a string.
+    if isinstance(value, (float, int)) and not isinstance(value, bool):
+        raise ValueError("coordinates must be quoted strings, e.g. \"59.3600000\"")
+    return value
+
+
+def _zone(value: str) -> str:
+    try:
+        ZoneInfo(value)
+    except (ZoneInfoNotFoundError, ValueError):
+        raise ValueError(f"unknown time zone {value!r} (an IANA name such as Europe/Stockholm)") from None
+    return value
+
+
+TimeZone = Annotated[str, AfterValidator(_zone)]
+
+# The portal's own pages under /portal/ (cpms/portal/urls.py): an organization keyed so would be hidden
+# behind them, since /portal/<organization>/ is matched after them. A test keeps the list complete.
+RESERVED_ORGANIZATION_KEYS = frozenset({"cli", "login", "logout", "inactive"})
+
+
+def _not_reserved(value: str) -> str:
+    if value in RESERVED_ORGANIZATION_KEYS:
+        raise ValueError(f"{value!r} is reserved (a portal page); choose another organization key")
+    return value
+
+
+OrganizationKey = Annotated[Key, AfterValidator(_not_reserved)]
+Rate = Annotated[Decimal, BeforeValidator(_no_float), Field(ge=0, le=1), _DECIMAL_TEXT]
+
+
+class Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+def _unique(items: Sequence[object], attr: str, what: str) -> None:
+    seen: set[object] = set()
+    for item in items:
+        value = getattr(item, attr)
+        if value in seen:
+            raise ValueError(f"duplicate {what} {value!r}")
+        seen.add(value)
+
+
+# --- organization -----------------------------------------------------------
+
+
+class Theme(Strict):
+    """How the organization's driver pages look (architecture §14). Optional; the default is neutral."""
+
+    primary: Annotated[str, StringConstraints(pattern=r"^#[0-9a-fA-F]{6}$")] | None = None
+    logo_url: Annotated[str, StringConstraints(pattern=r"^https://\S+$", max_length=500)] | None = None
+
+
+class Organization(Strict):
+    key: OrganizationKey
+    name: str
+    org_number: str | None = None
+    vat_number: str | None = None
+    address: str | None = None
+    email: str | None = None
+    payment_mode: Literal["direct", "platform"] = "direct"
+    currency: Literal["SEK", "EUR", "NOK", "DKK"] = "SEK"
+    display_timezone: str = "Europe/Stockholm"
+    # The eMI3 operator id, e.g. "SE*KEL": the OCPI party (country code, party id) and the EVSE ids' prefix.
+    operator_id: Annotated[str, StringConstraints(pattern=r"^[A-Z]{2}\*[A-Z0-9]{3}$")] | None = None
+    theme: Theme | None = None
+
+
+class OrganizationDocument(Strict):
+    manifest: Literal["cpms/v1"]
+    kind: Literal["organization"]
+    organization: Organization
+
+    @property
+    def org_key(self) -> str:
+        return self.organization.key
+
+    @property
+    def doc_key(self) -> str:
+        return self.organization.key
+
+
+# --- price list -------------------------------------------------------------
+
+
+class FlatPrice(Strict):
+    from_: dt.date = Field(alias="from")
+    per_kwh: Money = Field(ge=0)
+
+
+class SpotPrice(Strict):
+    from_: dt.date = Field(alias="from")
+    spot_markup_per_kwh: Money = Field(ge=0)
+    fallback_per_kwh: Money | None = Field(default=None, ge=0)
+
+
+class _TariffBase(Strict):
+    key: Key
+    name: str | None = None
+    amounts: Literal["incl_vat", "excl_vat"]  # required: which side of the price is exact
+    vat_rate: Rate
+
+    @model_validator(mode="after")
+    def _dated_rows(self):  # type: ignore[no-untyped-def]
+        prices = getattr(self, "prices")
+        if not prices:
+            raise ValueError(f"tariff {self.key!r} has no price rows")
+        dates = [p.from_ for p in prices]
+        if dates != sorted(dates) or len(set(dates)) != len(dates):
+            raise ValueError(f"tariff {self.key!r}: price rows must be in strictly increasing date order")
+        return self
+
+
+class FlatTariff(_TariffBase):
+    kind: Literal["flat"]
+    prices: list[FlatPrice]
+
+
+class SpotTariff(_TariffBase):
+    kind: Literal["spot"]
+    spot_area: Literal["SE1", "SE2", "SE3", "SE4"]
+    prices: list[SpotPrice]
+
+
+Tariff = Annotated[Union[FlatTariff, SpotTariff], Field(discriminator="kind")]
+
+
+class Fee(Strict):
+    from_: dt.date = Field(alias="from")
+    monthly: Money = Field(ge=0)
+
+
+class Billing(Strict):
+    period: Literal["month"] = "month"
+    fee: Literal["in_advance"] = "in_advance"
+    energy: Literal["in_arrears"] = "in_arrears"
+    on_end: Literal["public"] = "public"
+
+
+class Plan(Strict):
+    key: Key
+    name: str | None = None
+    tariff: Key
+    requires: Literal["none", "subscription", "roaming"]
+    preauth_amount: Money | None = Field(default=None, gt=0)  # incl. VAT, reserved on the card
+    fees: list[Fee] = []
+    billing: Billing | None = None
+
+
+class RoamingChannel(Strict):
+    default: Key
+
+
+class Channels(Strict):
+    adhoc: list[Key] = []
+    roaming: RoamingChannel | None = None
+
+
+class PricelistDocument(Strict):
+    manifest: Literal["cpms/v1"]
+    kind: Literal["pricelist"]
+    organization: Key
+    tariffs: list[Tariff]
+    plans: list[Plan]
+    channels: Channels
+
+    @property
+    def org_key(self) -> str:
+        return self.organization
+
+    @property
+    def doc_key(self) -> str:
+        return "pricelist"
+
+    @model_validator(mode="after")
+    def _references(self):  # type: ignore[no-untyped-def]
+        _unique(self.tariffs, "key", "tariff")
+        _unique(self.plans, "key", "plan")
+        tariffs = {t.key for t in self.tariffs}
+        plans = {p.key: p for p in self.plans}
+        for p in self.plans:
+            if p.tariff not in tariffs:
+                raise ValueError(f"plan {p.key!r} names unknown tariff {p.tariff!r}")
+        for key in self.channels.adhoc:
+            if key not in plans:
+                raise ValueError(f"channel adhoc names unknown plan {key!r}")
+            if plans[key].requires != "none":
+                raise ValueError(f"channel adhoc plan {key!r} must have requires: none")
+            if plans[key].preauth_amount is None:
+                raise ValueError(f"channel adhoc plan {key!r} needs a preauth_amount")
+        if self.channels.roaming and self.channels.roaming.default not in plans:
+            raise ValueError(f"channel roaming names unknown plan {self.channels.roaming.default!r}")
+        return self
+
+
+# --- site -------------------------------------------------------------------
+
+
+class Policy(Strict):
+    mode: Literal["fair_share"] = "fair_share"
+    min_amps: int = Field(default=6, ge=6, le=32)
+    max_amps: int = Field(default=32, ge=6, le=63)
+    single_phase_threshold_amps: int = Field(default=10, ge=6, le=32)
+    single_phase_amps: int = Field(default=16, ge=6, le=32)
+    pause_allowed: bool = True
+    hysteresis_amps: int = Field(default=2, ge=0, le=10)
+    phase_switch_cooldown_s: int = Field(default=300, ge=0)
+
+
+class PostgresMeter(Strict):
+    type: Literal["postgres_energy_readings"]
+    dsn_env: str
+    location: str
+    max_age_s: int = Field(default=30, gt=0)
+    margin_amps: int = Field(default=2, ge=0)
+    fallback_external_amps: int | None = Field(default=None, ge=0)
+
+
+class HttpMeter(Strict):
+    type: Literal["http"]
+    url: str
+    auth_header_env: str | None = None
+    max_age_s: int = Field(default=30, gt=0)
+    margin_amps: int = Field(default=2, ge=0)
+    fallback_external_amps: int | None = Field(default=None, ge=0)
+
+
+ExternalMeter = Annotated[Union[PostgresMeter, HttpMeter], Field(discriminator="type")]
+
+
+class Outlet(Strict):
+    connector: int = Field(ge=1, le=8)
+    key: Key
+    public: bool = True
+    max_amps: int | None = Field(default=None, ge=6, le=32)  # the balancer's cap and the connector's rating
+    # What OCPI says about the outlet. Required on a published site (plan checks), defaults otherwise.
+    plug: Literal["type2_socket", "type2_cable"] | None = None
+    phases: Literal[1, 3] | None = None
+    evse_id: Annotated[str, StringConstraints(max_length=48)] | None = None  # overrides the derived eMI3 id
+
+
+class ChargePoint(Strict):
+    key: Key
+    ocpp_id: Annotated[str, StringConstraints(min_length=1, max_length=64)]
+    name: str | None = None
+    phase_rotation: list[Phase] = ["L1", "L2", "L3"]
+    rotation_verified: bool = False
+    auth: Literal["none", "basic"] = "none"  # the key is generated server-side, never in the file
+    outlets: list[Outlet]
+
+    @model_validator(mode="after")
+    def _physics(self):  # type: ignore[no-untyped-def]
+        if sorted(self.phase_rotation) != ["L1", "L2", "L3"]:
+            raise ValueError(f"charge point {self.key!r}: phase_rotation must be a permutation of L1, L2, L3")
+        if not self.outlets:
+            raise ValueError(f"charge point {self.key!r} has no outlets")
+        _unique(self.outlets, "connector", f"connector on {self.key!r}")
+        return self
+
+
+class FuseGroup(Strict):
+    key: Key
+    name: str | None = None
+    physical_fuse_amps: int = Field(gt=0)
+    budget_amps: int = Field(gt=0)
+    balancing: bool = True
+    policy: Policy = Policy()
+    external_meter: ExternalMeter | None = None
+    charge_points: list[ChargePoint] = []
+
+    @model_validator(mode="after")
+    def _physics(self):  # type: ignore[no-untyped-def]
+        if self.budget_amps > self.physical_fuse_amps:
+            raise ValueError(
+                f"fuse group {self.key!r}: budget_amps {self.budget_amps} exceeds physical_fuse_amps {self.physical_fuse_amps}"
+            )
+        _unique(self.charge_points, "key", "charge point")
+        return self
+
+
+class Coordinates(Strict):
+    """WGS 84, as OCPI writes them: decimal degrees as strings with 5 to 7 decimals."""
+
+    # The validator outermost, so the pattern also reaches the JSON Schema.
+    latitude: Annotated[str, StringConstraints(pattern=r"^-?[0-9]{1,2}\.[0-9]{5,7}$"), BeforeValidator(_quoted)]
+    longitude: Annotated[str, StringConstraints(pattern=r"^-?[0-9]{1,3}\.[0-9]{5,7}$"), BeforeValidator(_quoted)]
+
+
+class Site(Strict):
+    key: Key
+    name: str
+    address: str | None = None  # street and number
+    city: str | None = None
+    postal_code: str | None = None
+    country: Annotated[str, StringConstraints(pattern=r"^[A-Z]{3}$")] = "SWE"  # ISO 3166-1 alpha-3
+    coordinates: Coordinates | None = None
+    timezone: TimeZone | None = None  # defaults to the organization's display_timezone
+    publish: bool = False  # in OCPI (Nobil, roaming) only when true
+    notes: str | None = None
+    fuse_groups: list[FuseGroup]
+
+    @model_validator(mode="after")
+    def _unique_keys(self):  # type: ignore[no-untyped-def]
+        _unique(self.fuse_groups, "key", "fuse group")
+        cps = [cp for fg in self.fuse_groups for cp in fg.charge_points]
+        _unique(cps, "key", "charge point")
+        _unique(cps, "ocpp_id", "ocpp_id")
+        _unique([o for cp in cps for o in cp.outlets], "key", "outlet")
+        return self
+
+
+class SiteDocument(Strict):
+    manifest: Literal["cpms/v1"]
+    kind: Literal["site"]
+    organization: Key
+    site: Site
+
+    @property
+    def org_key(self) -> str:
+        return self.organization
+
+    @property
+    def doc_key(self) -> str:
+        return self.site.key
+
+
+Document = Annotated[
+    Union[OrganizationDocument, PricelistDocument, SiteDocument], Field(discriminator="kind")
+]