tts-dictionary-interface 0.2.3__tar.gz → 0.3.0__tar.gz

tts_dictionary_interface-0.3.0/.github/workflows/run_tests_on_pr.yml

@@ -0,0 +1,14 @@
+name: PR Multi-Version Tests
+
+on:
+  pull_request:
+    branches: [ main ]
+    types: [opened, synchronize, reopened]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  call-shared-tests:
+    uses: NASA-JPL-Teamtools-Studio/tts_ci_cd/.github/workflows/run_tests_on_pr.yml@main

{tts_dictionary_interface-0.2.3 → tts_dictionary_interface-0.3.0}/.gitignore

@@ -186,3 +186,6 @@ Thumbs.db
 
 #nfs temp files
 .nfs*
+
+#other
+tmp_dict_examples/

{tts_dictionary_interface-0.2.3 → tts_dictionary_interface-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tts-dictionary-interface
-Version: 0.2.3
+Version: 0.3.0
 Summary: Core code for developing Python AMPCS dictionary interfaces.
 Author: muszynsk
 Author-email: muszynsk <matt.muszynski@jpl.nasa.gov>
@@ -13,6 +13,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: lxml
 Requires-Dist: pytest
 Requires-Dist: tomli
+Requires-Dist: pyyaml
 Requires-Dist: tts-utilities<=1.0.0,>=0.2.2
 Dynamic: author
 Dynamic: requires-python

tts_dictionary_interface-0.3.0/docs/agents/README.md

@@ -0,0 +1,13 @@
+# Agent skills
+
+Canonical engineering-skill conventions and the cross-repo dependency map live in
+`tts_core/teamtools_documentation/docs/agents/`. This repo holds only the
+per-repo instance data a skill needs locally.
+
+- **Issue tracker:** GitHub Issues at `github.com/NASA-JPL-Teamtools-Studio/tts_dictionary_interface`
+  (host `github.com`, `-R NASA-JPL-Teamtools-Studio/tts_dictionary_interface`).
+  *If a skill needs more, see `teamtools_documentation/docs/agents/issue-tracker-github-ghe.md`.*
+- **Adapts:** `unknown`
+- **Triage labels:** default vocabulary (see `teamtools_documentation/docs/agents/triage-labels.md`)
+- **Domain context:** repo-specific domain language is in this repo's `CONTEXT.md`.
+- **Ownership:** public

tts_dictionary_interface-0.3.0/docs/semantic_dictionary_cache_spec.md

@@ -0,0 +1,47 @@
+# Implementation Spec: SemanticDictionary Node Caching
+## Overview
+This specification outlines the implementation of a caching mechanism for `SemanticDictionary` to resolve performance issues caused by repeated XML parsing and XPath lookups.
+## Design Decisions
+### 1. Cache Scope and Lifecycle
+- **Scope**: Session-scoped. Each `SemanticDictionary` instance will maintain its own private cache.
+- **Lifecycle**: The cache is created upon instantiation and lives for the duration of the object.
+### 2. Cache Mechanism
+- **Type**: A Python dictionary used as an LRU (Least Recently Used) cache.
+- **Capacity**: Bounded to 100 entries to prevent unbounded memory growth.
+- **Concurrency**: Non-thread-safe (to minimize overhead, per developer requirement).
+### 3. Keying Strategy
+To avoid collisions between different lookup methods, the cache will use a composite key: `(lookup_type, lookup_value)`.
+| Method | `lookup_type` | `lookup_value` |
+|---|---|---|
+| `__getitem__` | `'getitem'` | The item ID (e.g., command stem) |
+| `__contains__` | `'getitem'` | The key being checked |
+| `__getattr__` | `'getattr'` | The attribute name |
+| `__iter__` | `'getitem'` | The item ID (from `ITEM_HUMAN_UNIQUE_IDS`) |
+### 4. Detailed Implementation Plan
+#### A. Initialization
+Add `self._cache = collections.OrderedDict()` to `SemanticDictionary.__init__`.
+#### B. `__getitem__` and `__contains__`
+- Check `self._cache.get(('getitem', item))`.
+- If present, return/confirm.
+- If absent:
+    - Perform the existing XPath logic.
+    - If a result is found, wrap it in the appropriate `ITEM_CLASS`.
+    - Add to `self._cache` with key `('getitem', item)`.
+    - Maintain LRU order by moving the key to the end if it exists, or removing the oldest if size > 100.
+#### C. `__getattr__`
+- Check `self._cache.get(('getattr', attr))`.
+- If present, return.
+- If absent:
+    - Perform existing logic.
+    - Store result in `self._cache` with key `('getattr', attr)`.
+    - Maintain LRU order.
+#### D. `__iter__` and `__len__`
+- `__iter__` will implement "lazy population":
+    - Iterate through `ITEM_XPATHS` and `ITEM_HUMAN_UNIQUE_IDS`.
+    - For each item, perform the wrap and store in `self._cache` using `('getitem', identifier)`.
+- `__len__` will return the count of items in the `'getitem'` cache after the first iteration has completed, or a cached count.
+#### E. Invalidation
+- No explicit `refresh()` method will be implemented at this time, as per developer request.
+## Verification Plan
+1. **Profiling**: Run `profile_test.py` to confirm the speedup factor (expected >10x for subsequent accesses).
+2. **Correctness**: Ensure `__getitem__`, `__getattr__`, `__contains__`, and `__iter__` all return correct, consistent data.

{tts_dictionary_interface-0.2.3 → tts_dictionary_interface-0.3.0}/pyproject.toml

@@ -15,6 +15,7 @@ dependencies = [
   "lxml",
   "pytest", 
   "tomli",
+  "pyyaml",
   "tts-utilities>=0.2.2,<=1.0.0"
 ]
 dynamic = ["version"]

tts_dictionary_interface-0.3.0/src/tts_dictionary_interface/ait/__init__.py

@@ -0,0 +1,3 @@
+from tts_dictionary_interface.ait.loader import AitYamlDictionary, load_yaml
+
+__all__ = ['load_yaml', 'AitYamlDictionary']

tts_dictionary_interface-0.3.0/src/tts_dictionary_interface/ait/loader.py

@@ -0,0 +1,100 @@
+"""
+PyYAML loading support for AIT-core-style dictionaries (`!Packet`/`!Field`/
+`!Command`/`!Argument`/`!EVR`, and similar mission-specific tags such as
+`!Fixed`).
+
+Two responsibilities, per design decisions made while grilling issue #21:
+
+1. Every AIT-core tag is treated as a no-op: a tagged mapping/sequence/
+   scalar loads as a plain dict/list/str, ignoring AIT-core's own Python
+   tag semantics entirely. This keeps the engine free of any dependency
+   on the `ait-core` package.
+
+2. `!include <relative-path>` is a real, resolved directive: the
+   referenced file is loaded (relative to the *including* file's own
+   directory, never a shared root or the process's cwd) and spliced in
+   as if its contents had been written inline. This mirrors the real
+   oco3mos dictionaries, where each FSW-version directory's `tlm.yaml` is
+   just a manifest of `!include` pointers at its own sibling files.
+   Includes may nest to any depth -- resolution is always relative to
+   whichever file directly contains the `!include`.
+"""
+import os
+
+import yaml
+
+from tts_dictionary_interface.tree import TreeSemanticDictionary, _flatten
+
+
+class IncludeLoader(yaml.SafeLoader):
+    """
+    A yaml.SafeLoader that resolves `!include` relative to the directory
+    of the file currently being loaded, and treats every other custom
+    tag as a no-op (plain dict/list/scalar).
+    """
+
+    def __init__(self, stream):
+        stream_name = getattr(stream, 'name', None)
+        self._root_dir = os.path.dirname(stream_name) if stream_name else '.'
+        super().__init__(stream)
+
+
+def _construct_include(loader, node):
+    relative_path = loader.construct_scalar(node)
+    path = os.path.join(loader._root_dir, relative_path)
+    with open(path, 'r') as f:
+        return yaml.load(f, IncludeLoader)
+
+
+def _construct_ignore_tag(loader, node):
+    """
+    Load any tagged node as if it were untagged, per its underlying YAML
+    kind (mapping/sequence/scalar) -- ignores the tag itself.
+    """
+    if isinstance(node, yaml.MappingNode):
+        return loader.construct_mapping(node, deep=True)
+    if isinstance(node, yaml.SequenceNode):
+        return loader.construct_sequence(node, deep=True)
+    return loader.construct_scalar(node)
+
+
+IncludeLoader.add_constructor('!include', _construct_include)
+# `None` registers a fallback constructor for any tag with no exact or
+# multi-constructor match -- i.e. every AIT-core tag except `!include`.
+IncludeLoader.add_constructor(None, _construct_ignore_tag)
+
+
+def load_yaml(path):
+    """
+    Load an AIT-core-style YAML dictionary file, resolving any `!include`
+    directives (recursively, relative to each including file's own
+    directory) and ignoring all other custom tags.
+    """
+    with open(path, 'r') as f:
+        return yaml.load(f, IncludeLoader)
+
+
+class AitYamlDictionary(TreeSemanticDictionary):
+    """
+    A `TreeSemanticDictionary` sourced from an AIT-flavored YAML file:
+    resolves `!include` directives via `load_yaml` and flattens the
+    result into a single flat list, so a document assembled from nested
+    includes (like the real oco3mos `tlm.yaml` manifests) behaves like
+    one flat list of items regardless of how many files it's split
+    across.
+
+    Concrete subclasses set `DICTIONARY_FILENAME` (e.g. 'cmd.yaml') so
+    that `source=<a directory>` or `source=<a version string>` (resolved
+    against `DICTIONARY_MODULE`) both know which file to load.
+    """
+
+    @classmethod
+    def _load_file(cls, path):
+        if os.path.isdir(path):
+            if not cls.DICTIONARY_FILENAME:
+                raise ValueError(
+                    f"{cls.__name__} must define DICTIONARY_FILENAME to load from a directory."
+                )
+            path = os.path.join(path, cls.DICTIONARY_FILENAME)
+        loaded = load_yaml(path)
+        return _flatten(loaded) if isinstance(loaded, list) else loaded

tts_dictionary_interface-0.3.0/src/tts_dictionary_interface/base.py

@@ -0,0 +1,235 @@
+import inspect
+import os
+from lxml import etree
+
+try:
+    from importlib.resources import files, as_file
+except ImportError:
+    from importlib_resources import files, as_file
+
+from tts_utilities.logger import create_logger
+logger = create_logger('semantic_dictionary')
+
+class DictionaryAttributeError(AttributeError):
+    """
+    Raised when a single-valued attribute configured in ATTR_PATHS resolves
+    to zero elements against the underlying dictionary.
+    """
+    pass
+
+def _accepts_document_arg(func):
+    """
+    Whether `func` is written to accept a second positional argument -- the 
+    constructed item itself, which exposes `.document`.
+    """
+    try:
+        signature = inspect.signature(func)
+    except (TypeError, ValueError):
+        return False
+
+    parameters = list(signature.parameters.values())
+    if any(p.kind == inspect.Parameter.VAR_POSITIONAL for p in parameters):
+        return True
+
+    positional = [
+        p for p in parameters
+        if p.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    return len(positional) >= 2
+
+class BaseSemanticDictionary:
+    """
+    A generic base for reading structured dictionaries (XML, YAML, JSON)
+    using a declarative mapping of paths to attributes and items.
+    """
+    ITEM_PATHS = []
+    ITEM_HUMAN_UNIQUE_IDS = []
+    ITEM_CLASSES = []
+    ATTR_PATHS = {}
+
+    DICTIONARY_MODULE = None
+    DICTIONARY_FILENAME = None
+
+    def __init__(self, source=None, document=None):
+        """
+        Args:
+            source: Version string, file path, or pre-parsed node.
+            document: Root node of the parent document (for cross-document resolution).
+        """
+        if source is None:
+            raise ValueError(f"Must specify a source for {self.__class__.__name__}")
+        
+        # Load the root node
+        self.node = self._load_source(source)
+        # The document is the root node. If we are an item of another dictionary, 
+        # we are passed the root of that dictionary.
+        self.document = document if document is not None else self.node
+
+    def _load_source(self, source):
+        """Load the source into self.node. Implemented by subclasses."""
+        raise NotImplementedError()
+
+    def select(self, path, filters=None):
+        """
+        Return a list of nodes matching the path and optional filters.
+        filters: {attr_name: value}
+        """
+        raise NotImplementedError()
+
+    def resolve_attr_value(self, value, attr_class, item_instance):
+        """
+        Convert a raw node/value into the final attribute value.
+        """
+        if attr_class is None:
+            return value
+        if _accepts_document_arg(attr_class):
+            return attr_class(value, item_instance)
+        return attr_class(value)
+
+    def _effective_item_paths(self):
+        """Return ITEM_PATHS if non-empty, else fall back to legacy ITEM_XPATHS."""
+        return getattr(type(self), 'ITEM_PATHS', None) or getattr(type(self), 'ITEM_XPATHS', [])
+
+    def __getitem__(self, item):
+        elements = []
+        item_paths = self._effective_item_paths()
+        item_ids = getattr(type(self), 'ITEM_HUMAN_UNIQUE_IDS', [])
+        item_classes = getattr(type(self), 'ITEM_CLASSES', [])
+        
+        for path, id_spec, itemclass in zip(item_paths, item_ids, item_classes):
+            identifiers = [id_.strip() for id_ in id_spec.split('|')]
+            for id_attr in identifiers:
+                matches = self.select(path, {id_attr: item})
+                elements.extend([itemclass(node, document=self.document) for node in matches])
+
+        # Deduplicate by node identity
+        unique_elements = []
+        seen_nodes = set()
+        for e in elements:
+            # We assume the wrapped item has a .node attribute or is the node itself
+            node = getattr(e, 'node', e)
+            if id(node) not in seen_nodes:
+                unique_elements.append(e)
+                seen_nodes.add(id(node))
+
+        if not unique_elements:
+            raise KeyError(f'No elements found with value "{item}"')
+        if len(unique_elements) > 1:
+            raise KeyError(f'More than one element found with value "{item}"')
+        
+        return unique_elements[0]
+
+    def __getattr__(self, attr):
+        # Try ATTR_PATHS (new 3-tuple: path, attr_class, return_list) first,
+        # then fall back to legacy ATTR_XPATHS (4-tuple: xpath, is_text, attr_class, return_list).
+        attr_paths = getattr(type(self), 'ATTR_PATHS', None)
+        if attr_paths and attr in attr_paths:
+            config = attr_paths[attr]
+            path = config[0]
+            attr_class = config[1] if len(config) > 1 else None
+            return_list = config[2] if len(config) > 2 else False
+            is_text = False
+        else:
+            attr_xpaths = getattr(type(self), 'ATTR_XPATHS', None)
+            if not attr_xpaths or attr not in attr_xpaths:
+                # Fall back to root XML attribute (returns None if not present,
+                # matching the legacy SemanticDictionary behavior)
+                if hasattr(self.node, 'get'):
+                    return self.node.get(attr)
+                raise AttributeError(f"'{self.__class__.__name__}' has no attribute '{attr}'")
+            config = attr_xpaths[attr]
+            path = config[0]
+            is_text = config[1] if len(config) > 1 else False
+            attr_class = config[2] if len(config) > 2 else None
+            return_list = config[3] if len(config) > 3 else False
+
+        matches = self.select(path)
+        
+        def resolve(m):
+            if is_text and hasattr(m, 'text'):
+                m = m.text
+            return self.resolve_attr_value(m, attr_class, self)
+
+        if not matches:
+            if return_list:
+                return []
+            raise DictionaryAttributeError(f"Attribute '{attr}' (path '{path}') matched zero elements")
+
+        if return_list:
+            return [resolve(m) for m in matches]
+        return resolve(matches[0])
+
+    def __iter__(self):
+        elements = []
+        # Use type(self) to avoid triggering __getattr__
+        item_paths = self._effective_item_paths()
+        item_classes = getattr(type(self), 'ITEM_CLASSES', [])
+        for path, itemclass in zip(item_paths, item_classes):
+            matches = self.select(path)
+            elements.extend([itemclass(node, document=self.document) for node in matches])
+        for e in elements:
+            yield e
+
+    def __len__(self):
+        return sum(1 for _ in self)
+
+    def __contains__(self, key):
+        item_paths = self._effective_item_paths()
+        for path, id_spec in zip(item_paths, self.ITEM_HUMAN_UNIQUE_IDS):
+            identifiers = [id_.strip() for id_ in id_spec.split('|')]
+            for id_attr in identifiers:
+                if self.select(path, {id_attr: key}):
+                    return True
+        return False
+
+class XMLSemanticDictionary(BaseSemanticDictionary):
+    """
+    XML implementation of the Semantic Interface.
+    """
+    @property
+    def etree(self):
+        return self.node
+
+    def xpath(self, xpath):
+        """
+        Run a raw XPath query against the root element of the dictionary.
+        A passthrough to ``self.node.xpath()``.
+        """
+        return self.node.xpath(xpath)
+
+    def _load_source(self, source):
+        if not isinstance(source, (str, os.PathLike)):
+            return source.getroot() if hasattr(source, 'getroot') else source
+        
+        source_str = str(source)
+        if not source_str.lower().endswith('.xml'):
+            if not self.DICTIONARY_MODULE or not self.DICTIONARY_FILENAME:
+                raise ValueError("XMLSemanticDictionary requires DICTIONARY_MODULE/FILENAME for versioned loading")
+            package_target = f"{self.DICTIONARY_MODULE}.{source_str}"
+            try:
+                traversable_path = files(package_target).joinpath(self.DICTIONARY_FILENAME)
+                with as_file(traversable_path) as xml_path:
+                    return etree.parse(str(xml_path)).getroot()
+            except Exception as e:
+                raise FileNotFoundError(f"Failed to resolve {source_str}: {e}")
+        
+        return etree.parse(source_str).getroot()
+
+    def select(self, path, filters=None):
+        if filters:
+            # Build XPath predicate: [ @attr1="val1" or @attr2="val2" ]
+            preds = []
+            for attr, val in filters.items():
+                if attr == 'text()':
+                    preds.append(f'text()="{val}"')
+                else:
+                    preds.append(f'@{attr}="{val}"')
+            
+            xpath = f"{path}[{' or '.join(preds)}]"
+        else:
+            xpath = path
+            
+        return self.node.xpath(xpath)
+
+# Alias for backward compatibility
+SemanticDictionary = XMLSemanticDictionary

tts_dictionary_interface-0.3.0/src/tts_dictionary_interface/contracts.py

@@ -0,0 +1,216 @@
+"""
+Shared, format-agnostic attribute contracts for Command/Argument/Channel/EVR
+objects, satisfied via multiple inheritance by any dictionary engine's
+concrete classes (XML/AMPCS, JSON/F-Prime, YAML/AIT, ...).
+
+Why this exists: without a shared contract, each engine's Command/Channel/EVR
+classes could drift into incompatible shapes with nothing to stop it.
+
+How "required but not yet implemented" works:
+
+    A contract-required attribute that a concrete class doesn't actually
+    implement must raise NotImplementedError -- but only when that specific
+    attribute is accessed, never at class definition or instantiation time.
+
+    For engines that implement attributes as *real* properties (e.g. a
+    hand-written JSON engine), this falls out for free: Python's normal
+    attribute lookup finds the concrete class's own property in its __dict__
+    before it ever consults a mixin base class, so the contract's
+    placeholder is simply never reached.
+
+    For engines that resolve attributes *dynamically* (e.g. AMPCS's
+    SemanticDictionary.__getattr__, which resolves attributes from
+    ATTR_XPATHS at access time rather than declaring them as properties),
+    there's nothing in the class's __dict__ to shadow the contract's
+    placeholder property -- so the placeholder would normally win and raise
+    immediately, without ever giving the dynamic resolver a chance. To avoid
+    that, every contract placeholder explicitly defers to the instance's own
+    __getattr__ (if it defines one) before concluding the attribute isn't
+    implemented at all.
+"""
+
+_UNSET = object()
+
+
+def _resolve_required(instance, name):
+    """
+    Resolve a contract-required attribute.
+
+    1. If the concrete class exposes a declarative attribute-config dict
+       (e.g. AMPCS's SemanticDictionary subclasses' ATTR_XPATHS, or the
+       dict/list-tree analog ATTR_PATHS used by YAML/AIT-flavored
+       engines) and the attribute isn't a key in ANY of them, the
+       attribute is definitely not implemented -- raise NotImplementedError
+       without even trying, since the dynamic __getattr__ would otherwise
+       silently fall back to a raw attribute lookup and return None
+       instead of signaling "unimplemented".
+    2. Otherwise, if the concrete class defines a real __getattr__, try it
+       explicitly.
+    3. If that raises AttributeError (including DictionaryAttributeError)
+       -- or there's no __getattr__ to try at all -- the attribute is not
+       implemented; raise NotImplementedError.
+    """
+    attr_paths = getattr(type(instance), 'ATTR_PATHS', None) or {}
+    attr_xpaths = getattr(type(instance), 'ATTR_XPATHS', None) or {}
+    if attr_paths or attr_xpaths:
+        if name not in attr_paths and name not in attr_xpaths:
+            raise NotImplementedError(
+                f"{type(instance).__name__} does not implement required "
+                f"contract attribute '{name}'"
+            )
+
+    dynamic_getattr = getattr(type(instance), '__getattr__', None)
+    if dynamic_getattr is not None:
+        try:
+            return dynamic_getattr(instance, name)
+        except AttributeError as e:
+            raise NotImplementedError(
+                f"{type(instance).__name__} does not implement required "
+                f"contract attribute '{name}'"
+            ) from e
+    raise NotImplementedError(
+        f"{type(instance).__name__} does not implement required contract "
+        f"attribute '{name}'"
+    )
+
+
+def _resolve_optional(instance, name):
+    """
+    Resolve a contract-optional attribute.
+
+    Optional attributes represent concepts that some formats simply don't
+    have (e.g. F-Prime has no per-channel packet ID). Unlike required
+    attributes, an unimplemented optional attribute is not an error -- it
+    just resolves to None.
+    """
+    dynamic_getattr = getattr(type(instance), '__getattr__', None)
+    if dynamic_getattr is None:
+        return None
+    try:
+        return dynamic_getattr(instance, name)
+    except AttributeError:
+        return None
+
+
+class ArgumentContract:
+    """
+    Contract for a single Command argument.
+
+    Required: name, length.
+    Optional: units, min, max -- some argument types (enumerated, string,
+    repeat-block arguments) have no native concept of engineering units or
+    numeric range; those resolve to None rather than raising.
+    """
+
+    @property
+    def name(self):
+        return _resolve_required(self, 'name')
+
+    @property
+    def length(self):
+        return _resolve_required(self, 'length')
+
+    @property
+    def units(self):
+        return _resolve_optional(self, 'units')
+
+    @property
+    def min(self):
+        return _resolve_optional(self, 'min')
+
+    @property
+    def max(self):
+        return _resolve_optional(self, 'max')
+
+
+class CommandContract:
+    """
+    Contract for a single Command definition.
+
+    Required: stem (also usable as the dictionary's __getitem__ key),
+    opcode, opscat, args (an iterable of ArgumentContract-satisfying
+    objects).
+    """
+
+    @property
+    def stem(self):
+        return _resolve_required(self, 'stem')
+
+    @property
+    def opcode(self):
+        return _resolve_required(self, 'opcode')
+
+    @property
+    def opscat(self):
+        return _resolve_required(self, 'opscat')
+
+    @property
+    def args(self):
+        return _resolve_required(self, 'args')
+
+
+class ChannelContract:
+    """
+    Contract for a single Channel (telemetry point) definition.
+
+    Required: channel_id and/or channel_name (either usable as the
+    dictionary's __getitem__ key), opscat, type.
+    Optional: module, measurement_id -- not every format has a distinct
+    module concept separate from opscat (F-Prime, AIT), or a per-channel
+    packet/measurement ID (F-Prime); those resolve to None rather than
+    raising.
+    """
+
+    @property
+    def channel_id(self):
+        return _resolve_required(self, 'channel_id')
+
+    @property
+    def channel_name(self):
+        return _resolve_required(self, 'channel_name')
+
+    @property
+    def opscat(self):
+        return _resolve_required(self, 'opscat')
+
+    @property
+    def type(self):
+        return _resolve_required(self, 'type')
+
+    @property
+    def module(self):
+        return _resolve_optional(self, 'module')
+
+    @property
+    def measurement_id(self):
+        return _resolve_optional(self, 'measurement_id')
+
+
+class EvrContract:
+    """
+    Contract for a single EVR (event record) definition.
+
+    Required: name, message, severity.
+
+    severity is required at the contract level even though some formats
+    (AIT) have no native severity concept at all -- severity is too
+    important a concept on missions that do use it to quietly downgrade
+    contract-wide. Formats without it are expected to explicitly implement
+    `severity` returning None and document that as a known limitation,
+    rather than being contractually exempted from having it.
+
+    message returns the raw, unformatted template string for every format
+    -- no parameter substitution against live telemetry values.
+    """
+
+    @property
+    def name(self):
+        return _resolve_required(self, 'name')
+
+    @property
+    def message(self):
+        return _resolve_required(self, 'message')
+
+    @property
+    def severity(self):
+        return _resolve_required(self, 'severity')

tts_dictionary_interface-0.3.0/src/tts_dictionary_interface/test/fixtures/ait_yaml/demosat_includes/ccsds_header.yaml

@@ -0,0 +1,8 @@
+- !Packet
+  name: CCSDS_HEADER
+  fields:
+    - !Field
+      name: apid
+      bytes: [0, 1]
+      type: MSB_U16
+      mask: 0x07FF