frequenz-gridpool 0.7.0__tar.gz → 0.7.1__tar.gz

{frequenz_gridpool-0.7.0/src/frequenz_gridpool.egg-info → frequenz_gridpool-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-gridpool
-Version: 0.7.0
+Version: 0.7.1
 Summary: High-level interface to grid pools for the Frequenz platform.
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License-Expression: MIT
@@ -150,7 +150,7 @@ The following platforms are officially supported (tested):
 
 ## CLI
 
-This package ships the `gridpool-cli` command with three subcommands.
+This package ships the `gridpool-cli` command with five subcommands.
 
 ### Setup
 
@@ -162,6 +162,9 @@ export ASSETS_API_AUTH_KEY="..."
 export ASSETS_API_SIGN_SECRET="..."
 ```
 
+`FREQUENZ_API_KEY` and `FREQUENZ_API_SECRET` are accepted as fallbacks for
+`ASSETS_API_AUTH_KEY` and `ASSETS_API_SIGN_SECRET`.
+
 ### Print component formulas
 
 ```bash
@@ -246,6 +249,28 @@ gridpool-cli generate-config <microgrid_id> \
     --prefer-meters-in-component-formulas > microgrid.toml
 ```
 
+### Validate config files
+
+Check config files offline, without contacting the Assets API, and exit
+non-zero on the first error, to gate config-repo CI:
+
+```bash
+gridpool-cli validate microgrid.toml [more.toml ...]
+```
+
+Each file is validated on its own first, so every record names its own key and
+required fields; the files are then validated merged, for the cross-record
+checks.
+
+### Look up a gridpool's enterprise
+
+Print the enterprise ID that owns a gridpool, read from the config files
+(merged as one stack); exits non-zero if the gridpool is not declared:
+
+```bash
+gridpool-cli find-enterprise <gridpool_id> config.toml [more.toml ...]
+```
+
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/README.md

@@ -75,7 +75,7 @@ The following platforms are officially supported (tested):
 
 ## CLI
 
-This package ships the `gridpool-cli` command with three subcommands.
+This package ships the `gridpool-cli` command with five subcommands.
 
 ### Setup
 
@@ -87,6 +87,9 @@ export ASSETS_API_AUTH_KEY="..."
 export ASSETS_API_SIGN_SECRET="..."
 ```
 
+`FREQUENZ_API_KEY` and `FREQUENZ_API_SECRET` are accepted as fallbacks for
+`ASSETS_API_AUTH_KEY` and `ASSETS_API_SIGN_SECRET`.
+
 ### Print component formulas
 
 ```bash
@@ -171,6 +174,28 @@ gridpool-cli generate-config <microgrid_id> \
     --prefer-meters-in-component-formulas > microgrid.toml
 ```
 
+### Validate config files
+
+Check config files offline, without contacting the Assets API, and exit
+non-zero on the first error, to gate config-repo CI:
+
+```bash
+gridpool-cli validate microgrid.toml [more.toml ...]
+```
+
+Each file is validated on its own first, so every record names its own key and
+required fields; the files are then validated merged, for the cross-record
+checks.
+
+### Look up a gridpool's enterprise
+
+Print the enterprise ID that owns a gridpool, read from the config files
+(merged as one stack); exits non-zero if the gridpool is not declared:
+
+```bash
+gridpool-cli find-enterprise <gridpool_id> config.toml [more.toml ...]
+```
+
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please

frequenz_gridpool-0.7.1/RELEASE_NOTES.md

@@ -0,0 +1,42 @@
+# Frequenz Gridpool Library Release Notes
+
+## Summary
+
+This release rounds out `gridpool-cli` for the `assets` config layout and adds
+gridpool enterprise ownership to the config model. The CLI can now generate,
+validate, patch, and query merged config files.
+
+## Upgrading
+
+- `generate-config` now writes the `assets.microgrids` layout and stamps
+  `assets.version`, instead of the legacy layout. Regenerate configs to get the
+  current format; generated files then load back without a migration.
+
+- `generate-config --inplace` refuses legacy-layout files (top-level or
+  `meta`-nested), which it would duplicate rather than edit. Rebuild those from
+  scratch.
+
+## New Features
+
+- `gridpool-cli validate <files>` checks config files offline and exits
+  non-zero on the first error, to gate config-repo CI. Each file must be valid
+  on its own, so a record names its own key and required fields; the files are
+  then checked merged, for the cross-record checks.
+
+- `gridpool-cli` accepts `FREQUENZ_API_KEY` and `FREQUENZ_API_SECRET` as a
+  fallback pair for `ASSETS_API_AUTH_KEY` and `ASSETS_API_SIGN_SECRET`.
+
+- Gridpools are described under `assets.gridpools`, each entry naming the
+  enterprise that owns the gridpool. `AssetsConfig.find_enterprise(gridpool_id)`
+  returns the configured owner.
+  `gridpool-cli find-enterprise <gridpool_id> <files>` prints it from the config.
+  `AssetsConfig.check` enforces the one-enterprise-per-gridpool invariant: a
+  gridpool's microgrids may not disagree on it, and a declared enterprise must
+  match the inferred one.
+
+- A config derived from the Assets API now carries each microgrid's
+  `enterprise_id`.
+
+- `generate-config --inplace` refreshes managed values while preserving
+  formatting; `--fill-missing` only adds absent values. Generated patches are
+  validated before writing.

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/src/frequenz/gridpool/cli/__main__.py

@@ -5,11 +5,13 @@
 
 import os
 import tempfile
+import tomllib
 from pathlib import Path
 
 import asyncclick as click
 from frequenz.client.assets import AssetsApiClient
 from frequenz.client.common.microgrid import MicrogridId
+from marshmallow import ValidationError
 
 from frequenz.gridpool import ComponentGraphConfig, ComponentGraphGenerator
 from frequenz.gridpool.cli._dump_config import dump_map
@@ -17,12 +19,37 @@ from frequenz.gridpool.cli._patch_config import patch_file
 from frequenz.gridpool.cli._render_graph import ComponentGraphRenderer, RenderOptions
 from frequenz.gridpool.config import AssetsConfig, load_configs
 
+_LOAD_ERRORS = (ValueError, TypeError, tomllib.TOMLDecodeError, ValidationError)
+"""Exceptions raised when a config file fails to load or validate."""
+
 
 @click.group()
 async def cli() -> None:
     """CLI tool for gridpool functionality."""
 
 
+def _assets_credentials() -> tuple[str, str, str]:
+    """Resolve Assets API URL, auth key and sign secret from the environment.
+
+    `FREQUENZ_API_KEY` and `FREQUENZ_API_SECRET` are accepted as a fallback pair
+    for `ASSETS_API_AUTH_KEY` and `ASSETS_API_SIGN_SECRET`. The key and secret
+    are taken as a whole from one source, never mixed across the two.
+    """
+    url = os.environ.get("ASSETS_API_URL")
+    key = os.environ.get("ASSETS_API_AUTH_KEY")
+    secret = os.environ.get("ASSETS_API_SIGN_SECRET")
+    if not key and not secret:
+        key = os.environ.get("FREQUENZ_API_KEY")
+        secret = os.environ.get("FREQUENZ_API_SECRET")
+    if not url or not key or not secret:
+        raise click.ClickException(
+            "ASSETS_API_URL and auth credentials must be set: "
+            "ASSETS_API_AUTH_KEY (or FREQUENZ_API_KEY) and "
+            "ASSETS_API_SIGN_SECRET (or FREQUENZ_API_SECRET)."
+        )
+    return url, key, secret
+
+
 def _graph_config(prefer_meters: bool) -> ComponentGraphConfig | None:
     """Build the graph config for `--prefer-meters-in-component-formulas`.
 
@@ -55,13 +82,7 @@ async def print_formulas(
     prefer_meters_in_component_formulas: bool,
 ) -> None:
     """Fetch and print component graph formulas for a microgrid."""
-    url = os.environ.get("ASSETS_API_URL")
-    key = os.environ.get("ASSETS_API_AUTH_KEY")
-    secret = os.environ.get("ASSETS_API_SIGN_SECRET")
-    if not url or not key or not secret:
-        raise click.ClickException(
-            "ASSETS_API_URL, ASSETS_API_AUTH_KEY, ASSETS_API_SIGN_SECRET must be set."
-        )
+    url, key, secret = _assets_credentials()
 
     async with AssetsApiClient(
         url,
@@ -90,6 +111,70 @@ async def print_formulas(
             )
 
 
+@cli.command()
+@click.argument(
+    "config_files",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+async def validate(config_files: tuple[Path, ...]) -> None:
+    """Validate each config file on its own, then the merged stack.
+
+    Each file must stand alone: every record names its own key and required
+    fields. The merged stack then adds the cross-record checks. Exits non-zero
+    on the first error, to gate CI.
+    """
+    for config_file in config_files:
+        try:
+            AssetsConfig.load_from_files([config_file])
+        except _LOAD_ERRORS as exc:
+            raise click.ClickException(f"{config_file}: {exc}") from exc
+
+    try:
+        config = AssetsConfig.load_from_files(list(config_files))
+    except _LOAD_ERRORS as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    click.echo(
+        f"OK: {len(config_files)} file(s), {len(config.microgrids)} microgrid(s), "
+        f"{len(config.relations)} relation(s), "
+        f"{len(config.market_locations)} market location(s).",
+        err=True,
+    )
+
+
+@cli.command("find-enterprise")
+@click.argument("gridpool_id", type=int)
+@click.argument(
+    "config_files",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+async def find_enterprise(gridpool_id: int, config_files: tuple[Path, ...]) -> None:
+    """Print the enterprise ID owning GRIDPOOL_ID, read from the config files.
+
+    The files are read as one merged stack. The owner is taken from the
+    `gridpools` entry without validating the full document. Exits non-zero if
+    the gridpool is not configured.
+    """
+    try:
+        # The declared `gridpools` entry is the source of truth for ownership,
+        # so read it even from a document whole-document validation would reject.
+        config = AssetsConfig.load_from_files(list(config_files), check=False)
+        enterprise_id = config.find_enterprise(gridpool_id)
+    except _LOAD_ERRORS as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if enterprise_id is None:
+        raise click.ClickException(
+            f"Could not determine the enterprise for gridpool {gridpool_id} "
+            "from the given config(s)."
+        )
+    click.echo(enterprise_id)
+
+
 @cli.command("render-graph")
 @click.argument("microgrid_id", type=int)
 @click.option(
@@ -107,13 +192,7 @@ async def print_formulas(
 )
 async def render_graph(microgrid_id: int, output: str, show: bool) -> None:
     """Render and save a component graph visualization for a microgrid."""
-    url = os.environ.get("ASSETS_API_URL")
-    key = os.environ.get("ASSETS_API_AUTH_KEY")
-    secret = os.environ.get("ASSETS_API_SIGN_SECRET")
-    if not url or not key or not secret:
-        raise click.ClickException(
-            "ASSETS_API_URL, ASSETS_API_AUTH_KEY, ASSETS_API_SIGN_SECRET must be set."
-        )
+    url, key, secret = _assets_credentials()
 
     try:
         async with AssetsApiClient(
@@ -151,9 +230,16 @@ async def render_graph(microgrid_id: int, output: str, show: bool) -> None:
     "--inplace",
     is_flag=True,
     default=False,
-    help="Patch --default in place instead of printing to stdout. Preserves "
-    "existing comments, ordering and formatting in that file; only fills in "
-    "values it is missing. Requires --default.",
+    help="Patch --default in place instead of printing to stdout, refreshing "
+    "the managed values while keeping its comments, ordering and formatting. "
+    "Requires --default.",
+)
+@click.option(
+    "--fill-missing",
+    is_flag=True,
+    default=False,
+    help="With --inplace, only add values --default is missing, leaving the "
+    "values already in it untouched.",
 )
 @click.option(
     "--prefer-meters-in-component-formulas",
@@ -162,11 +248,13 @@ async def render_graph(microgrid_id: int, output: str, show: bool) -> None:
     help="Read the meter before the component in the per-category formulas. "
     "This is the order used before component graph v0.5.0.",
 )
-async def generate_config(
+async def generate_config(  # pylint: disable=too-many-locals
     microgrid_ids: tuple[int, ...],
+    *,
     default_file: Path | None,
     override_file: Path | None,
     inplace: bool,
+    fill_missing: bool,
     prefer_meters_in_component_formulas: bool,
 ) -> None:
     """Generate microgrid config from the Assets API as TOML.
@@ -184,21 +272,17 @@ async def generate_config(
     component graph v0.5.0.
 
     With `--inplace`, `--default` is patched directly instead: candidate values
-    come from the Assets API (with `--override` layered on top), and only
-    leaves `--default` is missing are added, preserving its existing comments,
-    field order and formatting. If no microgrid IDs are given, every microgrid
-    already in `--default` is processed.
+    come from the Assets API (with `--override` layered on top) and refresh the
+    managed values, keeping the file's comments, field order and formatting.
+    With `--fill-missing`, only values `--default` lacks are added. If no
+    microgrid IDs are given, every microgrid already in `--default` is processed.
     """
     if inplace and default_file is None:
         raise click.ClickException("--inplace requires --default.")
+    if fill_missing and not inplace:
+        raise click.ClickException("--fill-missing requires --inplace.")
 
-    url = os.environ.get("ASSETS_API_URL")
-    key = os.environ.get("ASSETS_API_AUTH_KEY")
-    secret = os.environ.get("ASSETS_API_SIGN_SECRET")
-    if not url or not key or not secret:
-        raise click.ClickException(
-            "ASSETS_API_URL, ASSETS_API_AUTH_KEY, ASSETS_API_SIGN_SECRET must be set."
-        )
+    url, key, secret = _assets_credentials()
 
     ids = list(dict.fromkeys(microgrid_ids)) or None
     if inplace and ids is None:
@@ -236,13 +320,25 @@ async def generate_config(
 
     if inplace:
         assert default_file is not None
-        patched = patch_file(default_file, configs)
+        try:
+            patched = patch_file(default_file, configs, fill_missing=fill_missing)
+        except ValueError as exc:
+            raise click.ClickException(str(exc)) from exc
         fd, tmp_name = tempfile.mkstemp(
             dir=default_file.parent, prefix=f".{default_file.name}."
         )
         try:
             with os.fdopen(fd, "w") as tmp_file:
                 tmp_file.write(patched)
+            # Guard against a patch that corrupts the file (e.g. bad splicing)
+            # before it overwrites the user's config.
+            try:
+                AssetsConfig.load_from_files(Path(tmp_name))
+            except _LOAD_ERRORS as exc:
+                raise click.ClickException(
+                    f"Refusing to write {default_file}: the patched result is "
+                    f"invalid: {exc}"
+                ) from exc
             os.replace(tmp_name, default_file)
         except BaseException:
             os.remove(tmp_name)

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/src/frequenz/gridpool/cli/_dump_config.py

@@ -5,9 +5,11 @@
 
 Renders a `{microgrid_id: MicrogridConfig}` mapping as dotted-key TOML, e.g.:
 
-    115.microgrid_id = 115
-    115.name = "Demo Grid"
-    115.latitude = 52.52
+    assets.version = 1
+
+    assets.microgrids.115.microgrid_id = 115
+    assets.microgrids.115.name = "Demo Grid"
+    assets.microgrids.115.latitude = 52.52
 
 This is the inverse of `AssetsConfig.load_from_files`. Value rendering (quoting,
 escaping, key-quoting, list/number/datetime formatting) is delegated to
@@ -21,6 +23,9 @@ import tomlkit
 from tomlkit.items import Integer, Trivia
 
 from frequenz.gridpool.config import MicrogridConfig
+from frequenz.gridpool.config._migrations import _CURRENT_VERSION
+
+_MICROGRID_PREFIX = ["assets", "microgrids"]
 
 
 def _is_empty(value: Any) -> bool:
@@ -83,14 +88,14 @@ def dump_map(configs: dict[int, MicrogridConfig]) -> str:
     """
     schema = MicrogridConfig.Schema()
     doc = tomlkit.document()
+    doc.append(tomlkit.key(["assets", "version"]), _CURRENT_VERSION)
     for mid in sorted(configs):
         dumped = schema.dump(configs[mid])
         assert isinstance(dumped, dict)
-        leaves = _iter_leaves([str(mid)], dumped)
+        leaves = _iter_leaves([*_MICROGRID_PREFIX, str(mid)], dumped)
         if not leaves:
             continue
-        if doc.body:
-            doc.add(tomlkit.nl())
+        doc.add(tomlkit.nl())
         for path, value in leaves:
             doc.append(tomlkit.key(path), _format_value(value))
     return tomlkit.dumps(doc)

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/src/frequenz/gridpool/cli/_patch_config.py

@@ -4,8 +4,9 @@
 """Patch existing dotted-key TOML files with new microgrid config values.
 
 Unlike `dump_map`, which rebuilds a TOML document from scratch, this module
-only adds missing leaves and missing microgrid entries. Values already on
-disk always win, so comments, field order and number formatting survive.
+edits the document in place, so its comments, field order and number formatting
+survive. By default it refreshes the managed leaves, overwriting them; with
+`fill_missing` it only adds the leaves the document lacks.
 """
 
 from collections.abc import Mapping
@@ -17,33 +18,42 @@ from tomlkit import TOMLDocument
 
 from frequenz.gridpool.config import MicrogridConfig
 
-from ._dump_config import _format_value, _iter_leaves
+from ._dump_config import _MICROGRID_PREFIX, _format_value, _iter_leaves
 
 
-def patch_file(path: Path, configs: dict[int, MicrogridConfig]) -> str:
-    """Patch the TOML file at `path` with any leaves missing from `configs`.
+def patch_file(
+    path: Path, configs: dict[int, MicrogridConfig], *, fill_missing: bool = False
+) -> str:
+    """Patch the TOML file at `path` with the values in `configs`.
 
     Args:
         path: Path to the existing TOML file to patch.
         configs: Mapping from microgrid ID to `MicrogridConfig`.
+        fill_missing: Only add leaves the file lacks, leaving existing values
+            untouched; by default the managed leaves are overwritten.
 
     Returns:
         The patched TOML text; the caller is responsible for writing it back.
     """
-    return patch_text(path.read_text(), configs)
+    return patch_text(path.read_text(), configs, fill_missing=fill_missing)
 
 
-def patch_text(original: str, configs: dict[int, MicrogridConfig]) -> str:
-    """Patch dotted-key TOML text with any leaves missing from `configs`.
+def patch_text(
+    original: str, configs: dict[int, MicrogridConfig], *, fill_missing: bool = False
+) -> str:
+    """Patch dotted-key TOML text with the values in `configs`.
 
     Args:
         original: The existing TOML text to patch.
         configs: Mapping from microgrid ID to `MicrogridConfig`.
+        fill_missing: Only add leaves the text lacks, leaving existing values
+            untouched; by default the managed leaves are overwritten.
 
     Returns:
         The patched TOML text.
     """
     doc = tomlkit.parse(original)
+    _reject_legacy_layout(doc)
     schema = MicrogridConfig.Schema()
 
     # Leaves needing a whole new sub-table can't be inserted via item assignment
@@ -59,12 +69,12 @@ def patch_text(original: str, configs: dict[int, MicrogridConfig]) -> str:
         if not leaves:
             continue
 
-        if mid not in doc:
+        if not _leaf_exists(doc, mid, []):
             _append_new_entry(doc, mid, leaves)
             continue
 
         for path, value in leaves:
-            if _leaf_exists(doc, mid, path):
+            if fill_missing and _leaf_exists(doc, mid, path):
                 continue
             if not _insert_leaf(doc, mid, path, value):
                 orphans.setdefault(mid, []).append((path, value))
@@ -75,10 +85,44 @@ def patch_text(original: str, configs: dict[int, MicrogridConfig]) -> str:
     return text
 
 
+def _reject_legacy_layout(doc: TOMLDocument) -> None:
+    """Refuse a document that is not in the current `assets.microgrids` layout.
+
+    Patching navigates by `assets.microgrids.<id>`, so a top-level or
+    `meta`-nested entry would be duplicated rather than edited. Such a file
+    must be rebuilt with `generate-config` (without `--inplace`) first.
+
+    Args:
+        doc: The parsed document to check.
+
+    Raises:
+        ValueError: If the document uses a deprecated layout.
+    """
+    hint = "rebuild it with generate-config (without --inplace) first"
+    if stray := sorted(k for k in doc if k != "assets"):
+        raise ValueError(
+            f"Cannot patch in place: deprecated top-level keys {stray}; {hint}."
+        )
+    assets = doc.get("assets", {})
+    microgrids = assets.get("microgrids", {}) if isinstance(assets, Mapping) else {}
+    if not isinstance(microgrids, Mapping):
+        microgrids = {}
+    metas = sorted(
+        mid
+        for mid, entry in microgrids.items()
+        if isinstance(entry, Mapping) and "meta" in entry
+    )
+    if metas:
+        raise ValueError(
+            f"Cannot patch in place: microgrids {metas} nest fields under the "
+            f"deprecated `meta` table; {hint}."
+        )
+
+
 def _leaf_exists(doc: TOMLDocument, mid: str, path: list[str]) -> bool:
-    """Whether the dotted key `mid.path...` already has a value in `doc`."""
+    """Whether the dotted key `assets.microgrids.mid.path...` has a value in `doc`."""
     node: Any = doc
-    for key in (mid, *path):
+    for key in (*_MICROGRID_PREFIX, mid, *path):
         if not isinstance(node, Mapping) or key not in node:
             return False
         node = node[key]
@@ -100,14 +144,14 @@ def _insert_leaf(doc: TOMLDocument, mid: str, path: list[str], value: Any) -> bo
     """
     node: Any = doc
     matched = 0
-    for key in (mid, *path[:-1]):
+    full_path = [*_MICROGRID_PREFIX, mid, *path]
+    for key in full_path[:-1]:
         nxt = node[key] if isinstance(node, Mapping) and key in node else None
         if not isinstance(nxt, Mapping):
             break
         node = nxt
         matched += 1
 
-    full_path = [mid, *path]
     if matched != len(full_path) - 1:
         return False
     node[full_path[-1]] = _format_value(value)
@@ -128,14 +172,14 @@ def _append_new_entry(
     if doc.body:
         doc.add(tomlkit.nl())
     for path, value in leaves:
-        doc.append(tomlkit.key([mid, *path]), _format_value(value))
+        doc.append(tomlkit.key([*_MICROGRID_PREFIX, mid, *path]), _format_value(value))
 
 
 def _render_lines(mid: str, leaves: list[tuple[list[str], Any]]) -> list[str]:
-    """Render `(path, value)` leaves as standalone `mid.path = value` lines."""
+    """Render leaves as standalone `assets.microgrids.mid.path = value` lines."""
     tmp = tomlkit.document()
     for path, value in leaves:
-        tmp.append(tomlkit.key([mid, *path]), _format_value(value))
+        tmp.append(tomlkit.key([*_MICROGRID_PREFIX, mid, *path]), _format_value(value))
     return tomlkit.dumps(tmp).splitlines(keepends=True)
 
 
@@ -159,8 +203,8 @@ def _splice_orphans(text: str, orphans: dict[str, list[tuple[list[str], Any]]])
 
 
 def _last_line_index_for_mid(lines: list[str], mid: str) -> int:
-    """Index of the last line belonging to `mid` (its key starts with `mid.`)."""
-    prefix = f"{mid}."
+    """Index of the last line belonging to `mid` (its key starts with the prefix)."""
+    prefix = f"{'.'.join(_MICROGRID_PREFIX)}.{mid}."
     for idx in range(len(lines) - 1, -1, -1):
         if lines[idx].lstrip().startswith(prefix):
             return idx

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/src/frequenz/gridpool/config/__init__.py

@@ -6,6 +6,7 @@
 from frequenz.microgrid_component_graph import ComponentGraphConfig, FormulaOverrides
 
 from ._assets import AssetsConfig
+from ._gridpool import GridpoolConfig
 from ._load import load_configs
 from ._microgrid import (
     BatteryConfig,
@@ -32,6 +33,7 @@ __all__ = [
     "ComponentTypeConfig",
     "DeliveryAreaConfig",
     "FormulaOverrides",
+    "GridpoolConfig",
     "MarketLocationConfig",
     "MicrogridConfig",
     "PVConfig",

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/src/frequenz/gridpool/config/_assets.py

@@ -15,6 +15,7 @@ from frequenz.client.assets import MarketParticipationType
 from marshmallow import Schema
 from marshmallow_dataclass import dataclass
 
+from ._gridpool import GridpoolConfig
 from ._microgrid import MicrogridConfig
 from ._migrations import _CURRENT_VERSION, migrate
 from ._topology import DeliveryAreaConfig, MarketLocationConfig, RelationConfig
@@ -89,6 +90,9 @@ class AssetsConfig:
     microgrids: dict[int, MicrogridConfig] = field(default_factory=dict)
     """Microgrids, keyed by microgrid ID."""
 
+    gridpools: dict[int, GridpoolConfig] = field(default_factory=dict)
+    """Gridpools, keyed by gridpool ID."""
+
     market_locations: dict[str, MarketLocationConfig] = field(default_factory=dict)
     """Market locations, keyed by their identifier."""
 
@@ -123,6 +127,11 @@ class AssetsConfig:
                 raise ValueError(
                     f"Microgrid ID mismatch: key {mid} != {cfg.microgrid_id}"
                 )
+        for gpid, gridpool in self.gridpools.items():
+            if int(gridpool.gridpool_id) != gpid:
+                raise ValueError(
+                    f"Gridpool ID mismatch: key {gpid} != {gridpool.gridpool_id}"
+                )
 
     def check(self) -> None:
         """Check the document as a whole, once every layer has been merged.
@@ -131,8 +140,9 @@ class AssetsConfig:
             ValueError: If an entry's identifier disagrees with the key it is
                 filed under, a relation names fewer than two sides, its key
                 disagrees with its fields, a gridpool relation names no delivery
-                area, one market location is placed in two of them, or a legacy
-                microgrid gridpool ID disagrees with its relations.
+                area, one market location is placed in two of them, a legacy
+                microgrid gridpool ID disagrees with its relations, or a
+                gridpool's declared and inferred enterprise disagree.
         """
         for key, location in self.market_locations.items():
             if location.id is None:
@@ -143,6 +153,7 @@ class AssetsConfig:
                 )
         self._check_relations()
         self._check_legacy_gridpool_ids()
+        self._check_gridpool_enterprises()
 
     def _check_relations(self) -> None:
         """Check the relations are complete, well-keyed and area-consistent.
@@ -213,6 +224,61 @@ class AssetsConfig:
                     f"{sorted(relation_gids)}; remove gid when several apply"
                 )
 
+    def _derive_enterprise(self, gridpool_id: int) -> int | None:
+        """Infer a gridpool's enterprise from the microgrids its relations name.
+
+        Args:
+            gridpool_id: The gridpool whose enterprise to infer.
+
+        Returns:
+            The inferred enterprise ID, or `None` if none can be inferred.
+
+        Raises:
+            ValueError: If the related microgrids disagree on the enterprise.
+        """
+        enterprises: set[int] = set()
+        for mid in self.find_microgrids(gridpool_id=gridpool_id):
+            microgrid = self.microgrids.get(mid)
+            if microgrid is not None and microgrid.enterprise_id is not None:
+                enterprises.add(microgrid.enterprise_id)
+        if not enterprises:
+            return None
+        if len(enterprises) > 1:
+            raise ValueError(
+                f"Gridpool {gridpool_id}: its microgrids disagree on the owning "
+                f"enterprise: {sorted(enterprises)}"
+            )
+        return enterprises.pop()
+
+    def _check_gridpool_enterprises(self) -> None:
+        """Check declared and inferable gridpool enterprises agree.
+
+        A gridpool owns one enterprise, so its microgrids must not disagree on
+        it, and a declared `gridpools` entry must match what they imply.
+
+        Raises:
+            ValueError: If a gridpool's microgrids disagree on the enterprise,
+                or a declared enterprise differs from the inferred one.
+        """
+        gridpool_ids = set(self.gridpools) | {
+            relation.gridpool_id
+            for relation in self.relations.values()
+            if relation.gridpool_id is not None
+        }
+        for gpid in gridpool_ids:
+            inferred = self._derive_enterprise(gpid)
+            declared = self.gridpools.get(gpid)
+            if (
+                declared is not None
+                and inferred is not None
+                and declared.enterprise_id != inferred
+            ):
+                raise ValueError(
+                    f"Gridpool {gpid}: declared enterprise "
+                    f"{declared.enterprise_id} disagrees with its microgrids' "
+                    f"enterprise {inferred}"
+                )
+
     def find_relations(
         self,
         *,
@@ -350,6 +416,18 @@ class AssetsConfig:
             )
         )
 
+    def find_enterprise(self, gridpool_id: int) -> int | None:
+        """Find the configured enterprise owning `gridpool_id`.
+
+        Args:
+            gridpool_id: The gridpool to look up.
+
+        Returns:
+            The owning enterprise ID, or `None` when the gridpool is not configured.
+        """
+        gridpool = self.gridpools.get(gridpool_id)
+        return gridpool.enterprise_id if gridpool is not None else None
+
     @classmethod
     def _warn_unknown_entities(cls, assets: dict[str, Any], source: Path) -> None:
         """Warn about entity tables that this version drops on load."""

frequenz_gridpool-0.7.1/src/frequenz/gridpool/config/_gridpool.py

@@ -0,0 +1,17 @@
+# License: MIT
+# Copyright © 2026 Frequenz Energy-as-a-Service GmbH
+
+"""Data model for a gridpool."""
+
+from marshmallow_dataclass import dataclass
+
+
+@dataclass
+class GridpoolConfig:
+    """Configuration of a gridpool."""
+
+    gridpool_id: int
+    """ID of the gridpool."""
+
+    enterprise_id: int
+    """Enterprise that owns the gridpool."""

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/src/frequenz/gridpool/config/_load.py

@@ -219,6 +219,9 @@ async def _build_config_from_metadata(
     location = mgrid.location if mgrid.location else None
     return MicrogridConfig(
         microgrid_id=microgrid_id,
+        # The Assets API always sets an EnterpriseId; an unassigned enterprise
+        # comes back as the proto default 0, which we treat as absent.
+        enterprise_id=int(mgrid.enterprise_id) or None,
         latitude=location.latitude if location else None,
         longitude=location.longitude if location else None,
     )

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1/src/frequenz_gridpool.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-gridpool
-Version: 0.7.0
+Version: 0.7.1
 Summary: High-level interface to grid pools for the Frequenz platform.
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License-Expression: MIT
@@ -150,7 +150,7 @@ The following platforms are officially supported (tested):
 
 ## CLI
 
-This package ships the `gridpool-cli` command with three subcommands.
+This package ships the `gridpool-cli` command with five subcommands.
 
 ### Setup
 
@@ -162,6 +162,9 @@ export ASSETS_API_AUTH_KEY="..."
 export ASSETS_API_SIGN_SECRET="..."
 ```
 
+`FREQUENZ_API_KEY` and `FREQUENZ_API_SECRET` are accepted as fallbacks for
+`ASSETS_API_AUTH_KEY` and `ASSETS_API_SIGN_SECRET`.
+
 ### Print component formulas
 
 ```bash
@@ -246,6 +249,28 @@ gridpool-cli generate-config <microgrid_id> \
     --prefer-meters-in-component-formulas > microgrid.toml
 ```
 
+### Validate config files
+
+Check config files offline, without contacting the Assets API, and exit
+non-zero on the first error, to gate config-repo CI:
+
+```bash
+gridpool-cli validate microgrid.toml [more.toml ...]
+```
+
+Each file is validated on its own first, so every record names its own key and
+required fields; the files are then validated merged, for the cross-record
+checks.
+
+### Look up a gridpool's enterprise
+
+Print the enterprise ID that owns a gridpool, read from the config files
+(merged as one stack); exits non-zero if the gridpool is not declared:
+
+```bash
+gridpool-cli find-enterprise <gridpool_id> config.toml [more.toml ...]
+```
+
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/src/frequenz_gridpool.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/frequenz/gridpool/cli/_patch_config.py
 src/frequenz/gridpool/cli/_render_graph.py
 src/frequenz/gridpool/config/__init__.py
 src/frequenz/gridpool/config/_assets.py
+src/frequenz/gridpool/config/_gridpool.py
 src/frequenz/gridpool/config/_load.py
 src/frequenz/gridpool/config/_microgrid.py
 src/frequenz/gridpool/config/_migrations.py

{frequenz_gridpool-0.7.0 → frequenz_gridpool-0.7.1}/src/frequenz_gridpool.egg-info/scm_file_list.json

@@ -45,6 +45,7 @@
     "src/frequenz/gridpool/cli/_render_graph.py",
     "src/frequenz/gridpool/config/__init__.py",
     "src/frequenz/gridpool/config/_assets.py",
+    "src/frequenz/gridpool/config/_gridpool.py",
     "src/frequenz/gridpool/config/_load.py",
     "src/frequenz/gridpool/config/_microgrid.py",
     "src/frequenz/gridpool/config/_migrations.py",

frequenz_gridpool-0.7.1/src/frequenz_gridpool.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.7.1",
+  "distance": 0,
+  "node": "gb1e6ec5ad7f5fe27fd1db03ffd398de766bc012c",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-31"
+}

frequenz_gridpool-0.7.0/RELEASE_NOTES.md

@@ -1,119 +0,0 @@
-# Frequenz Gridpool Library Release Notes
-
-## Summary
-
-<!-- Here goes a general summary of what this release is about -->
-
-## Upgrading
-
-- `MicrogridConfig.load_from_file` is replaced by `AssetsConfig.load_from_files`,
-  which loads one or more files, merged into one document, and returns the whole
-  document rather than just its microgrids:
-
-  ```python
-  configs = AssetsConfig.load_from_files(path).microgrids
-  ```
-
-  `load_configs` now returns the whole `AssetsConfig` rather than just its
-  microgrids, so the file layers' `relations` and `market_locations` survive the
-  merge; replace `load_configs(...)` with `load_configs(...).microgrids` where
-  only the microgrid map is needed. `load_from_files` layers files field by field
-  instead of replacing a complete microgrid entry; fields omitted by a later file
-  retain the value from the earlier layer and cannot be removed by omission.
-
-- `Metadata` is removed; its fields (`microgrid_id`, `name`, `gid`, coordinates,
-  times) now sit directly on `MicrogridConfig`:
-
-  ```python
-  MicrogridConfig(microgrid_id=1, name="Grid")  # was meta=Metadata(...)
-  ```
-
-  In TOML they move up one level, `assets.microgrids.1.name` rather than
-  `assets.microgrids.1.meta.name`. A file still nesting a microgrid's fields
-  under `meta` loads, lifted with a deprecation warning.
-
-- A microgrid's `delivery_area` is removed. Move its value to a relation's
-  `delivery_area.code`, and set `delivery_area.code_type` when the code is not
-  EIC. When relations are present, the legacy `gid` must be their sole
-  gridpool ID; remove it for a microgrid that participates in several gridpools.
-
-- `load_configs_from_files` is removed. Use `AssetsConfig.load_from_files`,
-  which returns the whole document rather than just its microgrids: replace
-  `load_configs_from_files(files)` with
-  `AssetsConfig.load_from_files(files).microgrids`, or use the returned
-  `AssetsConfig` directly to keep relations and market locations.
-
-- `load_configs_from_api` is now private. For an API-only load call
-  `load_configs(assets_client=..., microgrid_ids=...)` and read its `.microgrids`.
-
-- `merge_config_maps` and `merge_microgrid_configs` are removed. Layering is now
-  done on the raw tables before loading, inside `load_configs` and
-  `AssetsConfig.load_from_files`; pass all the layers to one of those instead of
-  merging loaded objects.
-
-- Relation validity bounds and `at` query instants must include a UTC offset.
-
-- The implementation modules `config.load` and `config.microgrid` are now
-  private. Import their public names from `frequenz.gridpool.config` instead.
-
-- Microgrids are now keyed by `int` microgrid ID, not `str`. This covers
-  `AssetsConfig.microgrids`, including documents returned by `load_configs`.
-  Index the mapping by integer ID:
-
-  ```python
-  configs[1]  # was configs["1"]
-  ```
-
-- The `AC_ACTIVE_POWER` deprecation warning is dropped. Use `AC_POWER_ACTIVE`
-  as the formula metric key; the old name is no longer flagged on load.
-
-
-## New Features
-
-- `AssetsConfig` gives the `assets` namespace a type, so the entities still to
-  come are added as fields rather than as more dict lookups. Microgrid IDs are
-  checked during construction. `AssetsConfig.check()` performs the topology-wide
-  checks after all layers have been merged; the file loaders call it unless
-  `AssetsConfig.load_from_files` is passed `check=False`.
-
-  File loaders ignore unknown entity tables with a warning, so a reader keeps
-  working against files that already carry newer entities.
-
-  The `assets` table may carry a `version`; on load a document is run through a
-  migration pipeline that brings older layouts up to the current format, so
-  legacy files keep working. The version tracks the assets format alone, not
-  the whole document.
-
-- Market topology is described under `assets.relations`, based on the Assets
-  API `MarketTopologyRelation`: each record links at least two of a gridpool, a
-  microgrid and a market location, filed under a
-  `G<gridpool_id>M<microgrid_id>L<market_location_id>` key derived from its own
-  sides. A relation naming a gridpool sits in a `delivery_area` that rides on
-  the relation, so a gridpool-to-microgrid relation with no market location still
-  carries one. A relation's validity lives in `validity`, each entry a half-open
-  `[start, end)` datetime period it applies over. Use-case-specific periods
-  qualify a relation; separate relations let one microgrid participate in
-  several gridpools. The config extends the API with plain periods for relations
-  that do not distinguish use cases. A gridpool-free microgrid-to-market-location
-  relation may also carry a delivery area for a direct mapping. Market locations
-  live under `assets.market_locations` as self-describing entries carrying their
-  own identifier, how to read it (`MALO_ID` by default), and the Assets API market
-  area (`EU_DE` by default). A relation's `delivery_area` is a `code` plus a
-  `code_type` that defaults to EIC, so an EIC area is just
-  `delivery_area.code = "..."`; EIC codes are check-character-validated. Raw
-  market-location IDs must be unique within a document, including across market
-  areas.
-
-  `AssetsConfig` answers the common lookups with `find_relations` and the
-  projections `find_delivery_areas`, `find_market_locations` and
-  `find_microgrids`, each filtered by the other sides and an instant.
-
-  Time-varying enterprise ownership is outside this change;
-  `MicrogridConfig.enterprise_id` remains as a scalar field.
-
-## Bug Fixes
-
-- Layering config files no longer resets a field a later file leaves unset back
-  to its default. The raw tables are merged before they are loaded.
-
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

frequenz_gridpool-0.7.0/src/frequenz_gridpool.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.7.0",
-  "distance": 0,
-  "node": "g6029140c644abcdc4a9fd0a3b2080bec673339c1",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-27"
-}