Add helper to regenerate AttributeDefinitions in GDTF, update docs

Author: vanous

AttributeDefinitions.xml

@@ -160,6 +160,23 @@ uv run pytest
 uv run pytest --mypy -m mypy pygdtf/*py
 ```
 
+## Updating Attribute Definitions
+
+The canonical AttributeDefinitions XML lives at the repo root:
+`AttributeDefinitions.xml`. When the GDTF spec updates that file, regenerate
+the baked Python data module used for zero-IO startup:
+
+```bash
+python3 - <<'PY'
+from pygdtf.utils import attr_loader
+attr_loader.generate_attribute_definitions_module()
+PY
+```
+
+This writes `pygdtf/utils/attribute_definitions_data.py`, which is imported at
+runtime instead of reading the XML. Commit the regenerated module along with
+the updated XML.
+
 ## Citation
 
 If you use this library in your research, publication, or software project,

README.md

@@ -22,6 +22,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+import copy
 import datetime
 import zipfile
 import sys
@@ -40,7 +41,7 @@
 from .utils import *
 from .value import *  # type: ignore
 
-__version__ = "1.4.0-dev0"
+__version__ = "1.4.0-dev1"
 
 # Standard predefined colour spaces: R, G, B, W-P
 COLOR_SPACE_SRGB = ColorSpaceDefinition(
@@ -927,6 +928,8 @@ def __init__(
         self.luminous_intensity = luminous_intensity
         self.transmission = transmission
         self.interpolation_to = interpolation_to
+        # Tracks which optional/defaulted attributes were explicitly set so we
+        # can re-emit them during serialization without bloating everything else.
         self._attr_keys: set = set()
         super().__init__(*args, **kwargs)
 
@@ -1881,6 +1884,8 @@ def __init__(
             self.sub_channel_sets = sub_channel_sets
         else:
             self.sub_channel_sets = []
+        # Tracks which optional/defaulted attributes were explicitly set so we
+        # can re-emit them during serialization without bloating everything else.
         self._attr_keys: set = set()
         super().__init__(*args, **kwargs)
 

pygdtf/__init__.py

@@ -27,6 +27,8 @@
 from typing import Any, Dict, List, Optional
 
 import pygdtf
+from .attr_loader import generate_attribute_definitions_module
+from .attribute_regenerator import regenerate_attribute_definitions
 
 
 def _get_channels_by_geometry(

pygdtf/utils/__init__.py

@@ -0,0 +1,159 @@
+import json
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from xml.etree import ElementTree
+
+
+def _annex_attr_path() -> Path:
+    """Return path to structured Annex attribute XML."""
+    return Path(__file__).resolve().parents[2] / "AttributeDefinitions.xml"
+
+
+def _parse_attribute_definitions_xml(xml_path: Path) -> Dict[str, Any]:
+    root = ElementTree.parse(xml_path).getroot()
+
+    activation_group_nodes = root.find("ActivationGroups")
+    activation_groups = [
+        ag.attrib.get("Name")
+        for ag in (
+            activation_group_nodes.findall("ActivationGroup")
+            if activation_group_nodes is not None
+            else []
+        )
+        if ag.attrib.get("Name")
+    ]
+
+    feature_group_nodes = root.find("FeatureGroups")
+    feature_groups = []
+    if feature_group_nodes is not None:
+        for feature_group in feature_group_nodes.findall("FeatureGroup"):
+            feature_groups.append(
+                {
+                    "name": feature_group.attrib.get("Name"),
+                    "pretty": feature_group.attrib.get("Pretty"),
+                    "features": [
+                        feature.attrib.get("Name")
+                        for feature in feature_group.findall("Feature")
+                        if feature.attrib.get("Name")
+                    ],
+                }
+            )
+
+    attribute_nodes = root.find("Attributes")
+    attributes = []
+    if attribute_nodes is not None:
+        for attr in attribute_nodes.findall("Attribute"):
+            attributes.append(
+                {
+                    "name": attr.attrib.get("Name"),
+                    "pretty": attr.attrib.get("Pretty"),
+                    "activation_group": attr.attrib.get("ActivationGroup"),
+                    "feature": attr.attrib.get("Feature"),
+                    "main_attribute": attr.attrib.get("MainAttribute"),
+                    "physical_unit": attr.attrib.get("PhysicalUnit"),
+                    "color": attr.attrib.get("Color"),
+                    "subphysical_units": [
+                        {
+                            "Type": spu.attrib.get("Type"),
+                            "PhysicalUnit": spu.attrib.get("PhysicalUnit"),
+                            "PhysicalFrom": spu.attrib.get("PhysicalFrom"),
+                            "PhysicalTo": spu.attrib.get("PhysicalTo"),
+                        }
+                        for spu in attr.findall("SubPhysicalUnit")
+                    ],
+                }
+            )
+
+    return {
+        "activation_groups": activation_groups,
+        "feature_groups": feature_groups,
+        "attributes": attributes,
+    }
+
+
+def _build_templates_from_data(data: Dict[str, Any]) -> Dict[str, Any]:
+    activation_groups = data.get("activation_groups", [])
+    feature_groups = data.get("feature_groups", [])
+
+    attributes_exact: Dict[str, Dict[str, Any]] = {}
+    attributes_wildcard: List[Dict[str, Any]] = []
+
+    for attr in data.get("attributes", []):
+        template = {
+            "name": attr.get("name"),
+            "pretty": attr.get("pretty"),
+            "activation_group": attr.get("activation_group"),
+            "feature": attr.get("feature"),
+            "main_attribute": attr.get("main_attribute"),
+            "physical_unit": attr.get("physical_unit"),
+            "color": attr.get("color"),
+            "subphysical_units": attr.get("subphysical_units", []),
+        }
+        name = template["name"]
+        if not name:
+            continue
+        if "(n)" in name or "(m)" in name:
+            pattern = re.escape(name)
+            pattern = pattern.replace("\\(n\\)", "(?P<n>\\d+)")
+            pattern = pattern.replace("\\(m\\)", "(?P<m>\\d+)")
+            attributes_wildcard.append(
+                {
+                    **template,
+                    "pattern": re.compile(f"^{pattern}$"),
+                }
+            )
+        else:
+            attributes_exact[name] = template
+
+    return {
+        "activation_groups": activation_groups,
+        "feature_groups": feature_groups,
+        "attributes": {
+            "exact": attributes_exact,
+            "wildcard": attributes_wildcard,
+        },
+    }
+
+
+@lru_cache(maxsize=1)
+def _load_annex_attribute_templates():
+    """Load Annex attribute definitions from generated module or XML."""
+    try:
+        from . import attribute_definitions_data as _attr_data_module
+
+        raw_data = getattr(_attr_data_module, "ANNEX_ATTRIBUTE_DEFINITIONS", None)
+    except Exception:
+        raw_data = None
+
+    if raw_data is None:
+        raw_data = _parse_attribute_definitions_xml(_annex_attr_path())
+
+    return _build_templates_from_data(raw_data)
+
+
+def generate_attribute_definitions_module(
+    xml_path: Optional[Path] = None, output_path: Optional[Path] = None
+) -> Path:
+    """
+    Generate a Python module with AttributeDefinitions data for zero-IO startup.
+
+    The generated module exports ANNEX_ATTRIBUTE_DEFINITIONS matching the XML content.
+    """
+    source = Path(xml_path) if xml_path is not None else _annex_attr_path()
+    target = (
+        Path(output_path)
+        if output_path is not None
+        else Path(__file__).resolve().parent / "attribute_definitions_data.py"
+    )
+
+    data = _parse_attribute_definitions_xml(source)
+    # Use repr so generated file is valid Python (no JSON null/true/false).
+    content = (
+        "# Auto-generated from AttributeDefinitions XML; do not edit by hand.\n"
+        f"# Source: {source.name}\n"
+        "ANNEX_ATTRIBUTE_DEFINITIONS = " + repr(data) + "\n"
+    )
+    target.write_text(content, encoding="utf-8")
+    return target