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

{tts_dictionary_interface-0.3.0/src/tts_dictionary_interface.egg-info → tts_dictionary_interface-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tts-dictionary-interface
-Version: 0.3.0
+Version: 0.4.0
 Summary: Core code for developing Python AMPCS dictionary interfaces.
 Author: muszynsk
 Author-email: muszynsk <matt.muszynski@jpl.nasa.gov>

tts_dictionary_interface-0.4.0/docs/agents/check_docstring_coverage.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+AST-based docstring coverage check for tts_dictionary_interface.
+
+Prints coverage percentage and exits 0 iff >=80% and no previously-missing
+symbols remain undocumented.
+"""
+import argparse
+import ast
+import sys
+from pathlib import Path
+
+SKIP_DIRS = {"test", "build", ".venv", "__pycache__"}
+SKIP_FILES = {"sandbox.py", "conftest.py"}
+
+PREVIOUSLY_MISSING = {
+    "tts_dictionary_interface.base.SemanticDictionary.resolve_value",
+    "tts_dictionary_interface.tree.TreeSemanticDictionary.resolve",
+    "tts_dictionary_interface.contracts.ArgumentContract.name",
+    "tts_dictionary_interface.contracts.ArgumentContract.length",
+    "tts_dictionary_interface.contracts.ArgumentContract.units",
+    "tts_dictionary_interface.contracts.ArgumentContract.min",
+    "tts_dictionary_interface.contracts.ArgumentContract.max",
+    "tts_dictionary_interface.contracts.CommandContract.stem",
+    "tts_dictionary_interface.contracts.CommandContract.opcode",
+    "tts_dictionary_interface.contracts.CommandContract.opscat",
+    "tts_dictionary_interface.contracts.CommandContract.args",
+    "tts_dictionary_interface.contracts.ChannelContract.measurement_id",
+    "tts_dictionary_interface.contracts.ChannelContract.channel_id",
+    "tts_dictionary_interface.contracts.ChannelContract.channel_name",
+    "tts_dictionary_interface.contracts.ChannelContract.type",
+    "tts_dictionary_interface.contracts.ChannelContract.module",
+    "tts_dictionary_interface.contracts.EvrContract.message",
+    "tts_dictionary_interface.contracts.EvrContract.severity",
+}
+
+def is_public(name):
+    # Public if not private (single leading underscore). Dunder names are public.
+    return not (name.startswith("_") and not name.startswith("__"))
+
+def module_name_from_path(py_path, src_root):
+    rel = py_path.relative_to(src_root)
+    parts = list(rel.with_suffix("").parts)
+    # strip leading src if present
+    if parts[0] == "src":
+        parts = parts[1:]
+    return ".".join(parts)
+
+def collect_symbols(src_root):
+    symbols = []  # list of (fqname, node)
+    documented = set()
+    for py_path in src_root.rglob("*.py"):
+        # skip
+        if any(part in SKIP_DIRS for part in py_path.parts):
+            continue
+        if py_path.name in SKIP_FILES:
+            continue
+        # only src/tts_dictionary_interface
+        if "tts_dictionary_interface" not in str(py_path):
+            continue
+        try:
+            source = py_path.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        try:
+            tree = ast.parse(source, filename=str(py_path))
+        except SyntaxError:
+            continue
+        mod_name = module_name_from_path(py_path, src_root.parent if src_root.name == "src" else src_root)
+        # fallback
+        # walk
+        for node in ast.walk(tree):
+            # We need parent context to avoid double counting
+            pass
+    # Simpler: manual walk with stack
+    symbols_info = []
+    for py_path in src_root.rglob("*.py"):
+        if any(part in SKIP_DIRS for part in py_path.parts):
+            continue
+        if py_path.name in SKIP_FILES:
+            continue
+        if "tts_dictionary_interface" not in str(py_path):
+            continue
+        try:
+            source = py_path.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        try:
+            tree = ast.parse(source, filename=str(py_path))
+        except SyntaxError:
+            continue
+        mod_name = module_name_from_path(py_path, src_root.parent if src_root.name == "src" else src_root)
+        # process module level nodes
+        for node in tree.body:
+            if isinstance(node, ast.ClassDef) and is_public(node.name):
+                fq_class = f"{mod_name}.{node.name}"
+                symbols_info.append((fq_class, node))
+                # methods
+                for item in node.body:
+                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and is_public(item.name):
+                        fq = f"{fq_class}.{item.name}"
+                        symbols_info.append((fq, item))
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and is_public(node.name):
+                fq = f"{mod_name}.{node.name}"
+                symbols_info.append((fq, node))
+    total = 0
+    documented_set = set()
+    for fq, node in symbols_info:
+        total += 1
+        if ast.get_docstring(node):
+            documented_set.add(fq)
+    return total, documented_set, symbols_info
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--strict-sentences', action='store_true', help='Enforce summary sentence ends with period')
+    args = parser.parse_args()
+    # repo root is parent of src
+    repo_root = Path(__file__).resolve().parents[2]
+    src_root = repo_root / "src"
+    total, documented_set, symbols_info = collect_symbols(src_root)
+    documented_count = len(documented_set)
+    pct = (documented_count / total * 100) if total else 0.0
+    print(f"Coverage: {documented_count}/{total} = {pct:.1f}%")
+    # list symbols
+    print("\nSymbols:")
+    for fq, node in symbols_info:
+        status = "DOC" if fq in documented_set else "MISSING"
+        print(f"  {status} {fq}")
+    # strict sentence check
+    sentence_failures = []
+    if args.strict_sentences:
+        for fq, node in symbols_info:
+            doc = ast.get_docstring(node)
+            if not doc:
+                continue
+            first_line = doc.strip().splitlines()[0].strip()
+            if not first_line.endswith('.'):
+                sentence_failures.append((fq, first_line))
+    # check previously missing
+    missing_prev = []
+    for sym in PREVIOUSLY_MISSING:
+        # if symbol not found, we consider it not applicable
+        found = any(fq == sym for fq, _ in symbols_info)
+        if not found:
+            continue
+        if sym not in documented_set:
+            missing_prev.append(sym)
+    if pct < 80:
+        print(f"\nFAIL: coverage {pct:.1f}% < 80%", file=sys.stderr)
+        sys.exit(1)
+    if sentence_failures:
+        print("\nFAIL: docstring summary sentences must end with period:", file=sys.stderr)
+        for fq, line in sentence_failures:
+            print(f"  {fq}: {line}", file=sys.stderr)
+        sys.exit(1)
+    if missing_prev:
+        print("\nFAIL: previously missing symbols still undocumented:", file=sys.stderr)
+        for s in missing_prev:
+            print(f"  {s}", file=sys.stderr)
+        sys.exit(1)
+    print("\nPASS")
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

{tts_dictionary_interface-0.3.0 → tts_dictionary_interface-0.4.0}/docs/index.rst

@@ -5,7 +5,7 @@ Welcome to the Teamtools Starter Template documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   foo
+   narrative
 
 Indices and tables
 ==================

tts_dictionary_interface-0.4.0/docs/narrative.rst

@@ -0,0 +1,100 @@
+Semantic Dictionary Interface Narrative
+=======================================
+
+Purpose
+-------
+
+The ``tts_dictionary_interface`` package provides a format-agnostic interoperability layer for spacecraft dictionary data. It defines a small set of contracts and two core engine base classes – ``SemanticDictionary`` for XML/AMPCS dictionaries and ``TreeSemanticDictionary`` for dict/list-tree dictionaries such as AIT YAML – so that downstream Teamtools libraries can assume a common way to look up commands, telemetry channels, and event records.
+
+The package does not implement mission-specific knowledge. Mission teams subclass the base classes and declare ``ITEM_PATHS``, ``ITEM_CLASSES``, ``ITEM_HUMAN_UNIQUE_IDS`` and ``ATTR_PATHS`` to map their dictionary schema onto the shared contracts.
+
+Architecture Overview
+--------------------
+
+ASCII class inheritance diagram::
+
+    SemanticDictionary
+        |
+        +-- MissionXMLDictionary (e.g., DemoSat command dict)
+    
+    TreeSemanticDictionary
+        |
+        +-- AitYamlDictionary
+              |
+              +-- MissionAITDictionary
+
+Contracts
+    ArgumentContract
+    CommandContract
+    ChannelContract
+    EvrContract
+
+Module Guide
+------------
+
+``tts_dictionary_interface.base``
+    ``SemanticDictionary`` – dictionary-like wrapper around lxml trees.
+    ``DictionaryAttributeError`` – raised when a single-valued attribute resolves to zero elements.
+
+``tts_dictionary_interface.tree``
+    ``TreeSemanticDictionary`` – analog of ``SemanticDictionary`` for dict/list trees.
+    ``select`` – path query helper used by ``TreeSemanticDictionary``.
+
+``tts_dictionary_interface.contracts``
+    Format-agnostic contracts for arguments, commands, channels, and EVRs. Concrete classes inherit from these contracts via multiple inheritance.
+
+``tts_dictionary_interface.ait.loader``
+    ``AitYamlDictionary`` – ``TreeSemanticDictionary`` subclass that loads AIT-flavored YAML with ``!include`` resolution.
+    ``IncludeLoader`` – PyYAML loader that resolves ``!include`` relative to the including file and ignores other custom tags.
+    ``load_yaml`` – public helper to load AIT YAML files.
+
+Key Classes
+-----------
+
+``SemanticDictionary``
+    Provides ``__getitem__``, ``__iter__``, ``__len__``, ``__contains__`` and dynamic attribute access via ``ATTR_XPATHS``. Subclasses configure ``ITEM_XPATHS``, ``ITEM_HUMAN_UNIQUE_IDS``, ``ITEM_CLASSES`` and ``ATTR_XPATHS``.
+
+``TreeSemanticDictionary``
+    Same concepts as ``SemanticDictionary`` but for dict/list trees. Uses a small path language ``a/b[k="v"]`` and supports cross-document resolution via the ``.document`` attribute.
+
+``ArgumentContract``, ``CommandContract``, ``ChannelContract``, ``EvrContract``
+    Define the required and optional attributes that mission classes must expose. Required attributes raise ``NotImplementedError`` if missing; optional attributes resolve to ``None``.
+
+Extension Guide
+---------------
+
+To add a mission-specific dictionary interface:
+
+1. Subclass ``SemanticDictionary`` for XML or ``TreeSemanticDictionary`` for YAML/JSON.
+2. Set ``DICTIONARY_MODULE`` and ``DICTIONARY_FILENAME`` for versioned package loading.
+3. Declare ``ITEM_PATHS`` / ``ITEM_XPATHS``, ``ITEM_HUMAN_UNIQUE_IDS``, ``ITEM_CLASSES`` and ``ATTR_PATHS`` / ``ATTR_XPATHS``.
+4. Make item classes inherit from the appropriate contract, e.g.:
+
+   .. code-block:: python
+
+      class CommandItem(SemanticDictionary, CommandContract):
+          pass
+
+See ``demosat_dictionary_interface`` for a concrete example of how a mission plugs in.
+
+Usage Example
+-------------
+
+Load a command dictionary and inspect a command:
+
+.. code-block:: python
+
+   from my_mission_dict import CommandDictionary
+
+   cmd_dict = CommandDictionary('current')
+   cmd = cmd_dict['MY_CMD']
+   print(cmd.stem)          # command stem
+   print(cmd.opcode)        # command opcode
+   print([a.name for a in cmd.args])  # argument names
+
+The same pattern works for ``TreeSemanticDictionary``-based YAML dictionaries via ``AitYamlDictionary``.
+
+Relationships
+-------------
+
+The package uses ``tts_utilities.logger.create_logger`` for consistent logging. No other runtime dependencies are required beyond ``lxml``, ``PyYAML`` and ``importlib_resources`` for Python 3.6 compatibility.

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

@@ -38,4 +38,7 @@ requires = [
   "tts-utilities>=0.2.1,<1.0.0", 
   "setuptools-scm"
   ]
-build-backend = "setuptools.build_meta"
+build-backend = "setuptools.build_meta"
+
+[tool.tts-ctx]
+type = "core"

{tts_dictionary_interface-0.3.0 → tts_dictionary_interface-0.4.0}/src/tts_dictionary_interface/ait/loader.py

@@ -28,12 +28,19 @@ 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).
+    YAML loader that resolves !include relative to the including file.
+
+    It treats every other custom tag as a no-op, loading nodes as plain
+    dict/list/scalar values.
     """
 
     def __init__(self, stream):
+        """
+        Initialize the IncludeLoader with the current file's directory.
+
+        The root directory is used to resolve `!include` paths relative
+        to the including file.
+        """
         stream_name = getattr(stream, 'name', None)
         self._root_dir = os.path.dirname(stream_name) if stream_name else '.'
         super().__init__(stream)
@@ -66,9 +73,10 @@ 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.
+    Load an AIT-core-style YAML dictionary file.
+
+    Includes are resolved recursively relative to each including file's
+    own directory, and all other custom tags are ignored.
     """
     with open(path, 'r') as f:
         return yaml.load(f, IncludeLoader)
@@ -76,16 +84,14 @@ def load_yaml(path):
 
 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.
+    TreeSemanticDictionary for AIT-flavored YAML files.
+
+    It resolves !include directives via load_yaml and flattens the result
+    into a single flat list, so documents assembled from nested includes
+    behave like one flat list of items.
+
+    Concrete subclasses set DICTIONARY_FILENAME so that source arguments
+    resolved against DICTIONARY_MODULE know which file to load.
     """
 
     @classmethod

{tts_dictionary_interface-0.3.0 → tts_dictionary_interface-0.4.0}/src/tts_dictionary_interface/base.py

@@ -1,5 +1,6 @@
 import inspect
 import os
+from collections import OrderedDict
 from lxml import etree
 
 try:
@@ -19,7 +20,7 @@ class DictionaryAttributeError(AttributeError):
 
 def _accepts_document_arg(func):
     """
-    Whether `func` is written to accept a second positional argument -- the 
+    Whether `func` is written to accept a second positional argument -- the
     constructed item itself, which exposes `.document`.
     """
     try:
@@ -49,6 +50,7 @@ class BaseSemanticDictionary:
 
     DICTIONARY_MODULE = None
     DICTIONARY_FILENAME = None
+    CACHE_CAPACITY = 100
 
     def __init__(self, source=None, document=None):
         """
@@ -58,12 +60,83 @@ class BaseSemanticDictionary:
         """
         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, 
+        # 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
+        self._cache = OrderedDict()
+        self._node_cache = OrderedDict()
+        self._item_count = None
+
+    _CACHE_MISS = object()
+
+    def _cache_get(self, key):
+        value = self._cache.get(key, self._CACHE_MISS)
+        if value is not self._CACHE_MISS:
+            self._cache.move_to_end(key)
+        return value
+
+    def _cache_put(self, key, value):
+        self._cache[key] = value
+        self._cache.move_to_end(key)
+        while len(self._cache) > self.CACHE_CAPACITY:
+            self._cache.popitem(last=False)
+        return value
+
+    def _node_cache_get(self, node):
+        key = id(node)
+        value = self._node_cache.get(key, self._CACHE_MISS)
+        if value is not self._CACHE_MISS:
+            self._node_cache.move_to_end(key)
+        return value
+
+    def _node_cache_put(self, node, value):
+        key = id(node)
+        self._node_cache[key] = value
+        self._node_cache.move_to_end(key)
+        while len(self._node_cache) > self.CACHE_CAPACITY:
+            self._node_cache.popitem(last=False)
+        return value
+
+    def _item_cache_key(self, node, id_spec):
+        for identifier in id_spec.split('|'):
+            identifier = identifier.strip()
+            if hasattr(node, 'get'):
+                value = node.get(identifier)
+            elif isinstance(node, dict):
+                value = node.get(identifier)
+            else:
+                value = None
+            if value is not None:
+                return ('getitem', value)
+        return None
+
+    def _wrap_item(self, node, itemclass, id_spec=None, lookup_key=None):
+        if lookup_key is not None:
+            cached = self._cache_get(('getitem', lookup_key))
+            if cached is not self._CACHE_MISS:
+                return cached
+
+        item = self._node_cache_get(node)
+        if item is self._CACHE_MISS:
+            item = itemclass(node, document=self.document)
+            self._node_cache_put(node, item)
+
+        if lookup_key is not None:
+            self._cache_put(('getitem', lookup_key), item)
+        else:
+            key = self._item_cache_key(node, id_spec) if id_spec else None
+            if key is not None:
+                existing = self._cache.get(key, self._CACHE_MISS)
+                if existing is self._CACHE_MISS:
+                    self._cache_put(key, item)
+                elif getattr(existing, 'node', existing) is not getattr(item, 'node', item):
+                    # An identifier shared by multiple nodes is ambiguous and
+                    # must remain discoverable by __getitem__.
+                    self._cache.pop(key, None)
+        return item
 
     def _load_source(self, source):
         """Load the source into self.node. Implemented by subclasses."""
@@ -91,35 +164,44 @@ class BaseSemanticDictionary:
         return getattr(type(self), 'ITEM_PATHS', None) or getattr(type(self), 'ITEM_XPATHS', [])
 
     def __getitem__(self, item):
+        cached = self._cache_get(('getitem', item))
+        if cached is not self._CACHE_MISS:
+            return cached
+
         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])
+                elements.extend([
+                    (node, itemclass, id_spec) 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)
+        for node, itemclass, id_spec in elements:
             if id(node) not in seen_nodes:
-                unique_elements.append(e)
+                unique_elements.append((node, itemclass, id_spec))
                 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]
+
+        node, itemclass, id_spec = unique_elements[0]
+        return self._wrap_item(node, itemclass, id_spec, lookup_key=item)
 
     def __getattr__(self, attr):
+        cached = self._cache_get(('getattr', attr))
+        if cached is not self._CACHE_MISS:
+            return cached
+
         # 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)
@@ -135,7 +217,8 @@ class BaseSemanticDictionary:
                 # 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)
+                    value = self.node.get(attr)
+                    return self._cache_put(('getattr', attr), value)
                 raise AttributeError(f"'{self.__class__.__name__}' has no attribute '{attr}'")
             config = attr_xpaths[attr]
             path = config[0]
@@ -144,7 +227,7 @@ class BaseSemanticDictionary:
             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
@@ -156,29 +239,49 @@ class BaseSemanticDictionary:
             raise DictionaryAttributeError(f"Attribute '{attr}' (path '{path}') matched zero elements")
 
         if return_list:
-            return [resolve(m) for m in matches]
-        return resolve(matches[0])
+            value = [resolve(m) for m in matches]
+        else:
+            value = resolve(matches[0])
+        return self._cache_put(('getattr', attr), value)
 
     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):
+        item_ids = getattr(type(self), 'ITEM_HUMAN_UNIQUE_IDS', [])
+        count = 0
+        for index, (path, itemclass) in enumerate(zip(item_paths, item_classes)):
+            id_spec = item_ids[index] if index < len(item_ids) else None
             matches = self.select(path)
-            elements.extend([itemclass(node, document=self.document) for node in matches])
-        for e in elements:
-            yield e
+            for node in matches:
+                count += 1
+                yield self._wrap_item(node, itemclass, id_spec)
+        self._item_count = count
 
     def __len__(self):
-        return sum(1 for _ in self)
+        if self._item_count is None:
+            for _ in self:
+                pass
+        return self._item_count
 
     def __contains__(self, key):
+        cached = self._cache_get(('getitem', key))
+        if cached is not self._CACHE_MISS:
+            return True
+
         item_paths = self._effective_item_paths()
-        for path, id_spec in zip(item_paths, self.ITEM_HUMAN_UNIQUE_IDS):
+        for path, id_spec, itemclass in zip(
+            item_paths, self.ITEM_HUMAN_UNIQUE_IDS, self.ITEM_CLASSES
+        ):
             identifiers = [id_.strip() for id_ in id_spec.split('|')]
             for id_attr in identifiers:
-                if self.select(path, {id_attr: key}):
+                matches = self.select(path, {id_attr: key})
+                if matches:
+                    if len(matches) == 1:
+                        self._wrap_item(matches[0], itemclass, id_spec, lookup_key=key)
+                    # Preserve the existing boolean semantics for ambiguous
+                    # identifiers; __getitem__ remains responsible for
+                    # rejecting multiple matches.
                     return True
         return False
 
@@ -200,7 +303,7 @@ class XMLSemanticDictionary(BaseSemanticDictionary):
     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:
@@ -212,7 +315,7 @@ class XMLSemanticDictionary(BaseSemanticDictionary):
                     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):
@@ -224,11 +327,11 @@ class XMLSemanticDictionary(BaseSemanticDictionary):
                     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

{tts_dictionary_interface-0.3.0 → tts_dictionary_interface-0.4.0}/src/tts_dictionary_interface/contracts.py

@@ -104,24 +104,41 @@ class ArgumentContract:
 
     @property
     def name(self):
+        """Return the argument name."""
         return _resolve_required(self, 'name')
 
     @property
     def length(self):
+        """Return the argument length."""
         return _resolve_required(self, 'length')
 
     @property
     def units(self):
+        """Return the argument units if defined."""
         return _resolve_optional(self, 'units')
 
     @property
     def min(self):
+        """Return the minimum value if defined."""
         return _resolve_optional(self, 'min')
 
     @property
     def max(self):
+        """Return the maximum value if defined."""
         return _resolve_optional(self, 'max')
 
+    @property
+    def type(self):
+        return _resolve_optional(self, 'type')
+
+    @property
+    def description(self):
+        return _resolve_optional(self, 'description')
+
+    @property
+    def enum(self):
+        return _resolve_optional(self, 'enum')
+
 
 class CommandContract:
     """
@@ -134,18 +151,22 @@ class CommandContract:
 
     @property
     def stem(self):
+        """Return the command stem."""
         return _resolve_required(self, 'stem')
 
     @property
     def opcode(self):
+        """Return the command opcode."""
         return _resolve_required(self, 'opcode')
 
     @property
     def opscat(self):
+        """Return the command opscat."""
         return _resolve_required(self, 'opscat')
 
     @property
     def args(self):
+        """Return the command arguments."""
         return _resolve_required(self, 'args')
 
 
@@ -163,29 +184,140 @@ class ChannelContract:
 
     @property
     def channel_id(self):
+        """Return the channel ID."""
         return _resolve_required(self, 'channel_id')
 
     @property
     def channel_name(self):
+        """Return the channel name."""
         return _resolve_required(self, 'channel_name')
 
     @property
     def opscat(self):
+        """Return the channel opscat."""
         return _resolve_required(self, 'opscat')
 
     @property
     def type(self):
+        """Return the channel type."""
         return _resolve_required(self, 'type')
 
     @property
     def module(self):
+        """Return the channel module if defined."""
         return _resolve_optional(self, 'module')
 
     @property
     def measurement_id(self):
+        """Return the measurement ID if defined."""
         return _resolve_optional(self, 'measurement_id')
 
 
+class ApidContract:
+    """
+    Contract for an application packet identifier definition.
+
+    Required: apid, name, format, title, description, module, opscat.
+    Optional: recorded, downlink_info.
+    """
+
+    @property
+    def apid(self):
+        return _resolve_required(self, 'apid')
+
+    @property
+    def name(self):
+        return _resolve_required(self, 'name')
+
+    @property
+    def format(self):
+        return _resolve_required(self, 'format')
+
+    @property
+    def title(self):
+        return _resolve_required(self, 'title')
+
+    @property
+    def description(self):
+        return _resolve_required(self, 'description')
+
+    @property
+    def module(self):
+        return _resolve_required(self, 'module')
+
+    @property
+    def opscat(self):
+        return _resolve_required(self, 'opscat')
+
+    @property
+    def recorded(self):
+        return _resolve_optional(self, 'recorded')
+
+    @property
+    def downlink_info(self):
+        return _resolve_optional(self, 'downlink_info')
+
+
+class EvrArgumentContract:
+    """
+    Contract for an argument interpolated into an EVR message.
+
+    Required: name.
+    Optional: type, length, enum.
+
+    EVR arguments are deliberately separate from command arguments because
+    their metadata describes message interpolation, not command encoding.
+    """
+
+    @property
+    def name(self):
+        return _resolve_required(self, 'name')
+
+    @property
+    def type(self):
+        return _resolve_optional(self, 'type')
+
+    @property
+    def length(self):
+        return _resolve_optional(self, 'length')
+
+    @property
+    def enum(self):
+        return _resolve_optional(self, 'enum')
+
+
+class EnumTableContract:
+    """
+    Contract for a named enumeration table.
+
+    Required: name, values.
+    """
+
+    @property
+    def name(self):
+        return _resolve_required(self, 'name')
+
+    @property
+    def values(self):
+        return _resolve_required(self, 'values')
+
+
+class EnumValueContract:
+    """
+    Contract for one value in an enumeration table.
+
+    Required: name, value.
+    """
+
+    @property
+    def name(self):
+        return _resolve_required(self, 'name')
+
+    @property
+    def value(self):
+        return _resolve_required(self, 'value')
+
+
 class EvrContract:
     """
     Contract for a single EVR (event record) definition.
@@ -205,12 +337,15 @@ class EvrContract:
 
     @property
     def name(self):
+        """Return the EVR name."""
         return _resolve_required(self, 'name')
 
     @property
     def message(self):
+        """Return the EVR message template."""
         return _resolve_required(self, 'message')
 
     @property
     def severity(self):
+        """Return the EVR severity."""
         return _resolve_required(self, 'severity')

tts_dictionary_interface-0.4.0/src/tts_dictionary_interface/test/test_cache.py

@@ -0,0 +1,166 @@
+from lxml import etree
+
+from tts_dictionary_interface.base import SemanticDictionary
+from tts_dictionary_interface.tree import TreeSemanticDictionary
+
+
+class CachedItem(TreeSemanticDictionary):
+    ATTR_PATHS = {
+        'name': ('.', lambda node: node['name']),
+    }
+
+
+class CachedDocument(TreeSemanticDictionary):
+    ITEM_PATHS = ['.']
+    ITEM_HUMAN_UNIQUE_IDS = ['name']
+    ITEM_CLASSES = [CachedItem]
+
+
+def test_xml_contains_populates_the_same_item_cache():
+    class XMLItem(SemanticDictionary):
+        pass
+
+    class XMLDocument(SemanticDictionary):
+        ITEM_XPATHS = ['.//Item']
+        ITEM_HUMAN_UNIQUE_IDS = ['name']
+        ITEM_CLASSES = [XMLItem]
+
+    document = XMLDocument(etree.fromstring(b'<Root><Item name="one"/></Root>'))
+
+    assert 'one' in document
+    first = document['one']
+    assert document['one'] is first
+
+
+def test_xml_alternate_identifier_reuses_the_wrapped_node():
+    class XMLItem(SemanticDictionary):
+        pass
+
+    class XMLDocument(SemanticDictionary):
+        ITEM_XPATHS = ['.//Item']
+        ITEM_HUMAN_UNIQUE_IDS = ['name|opcode']
+        ITEM_CLASSES = [XMLItem]
+
+    document = XMLDocument(
+        etree.fromstring(b'<Root><Item name="one" opcode="0x1"/></Root>')
+    )
+
+    first = document['one']
+    assert document['0x1'] is first
+
+
+def test_xml_getattr_caches_resolved_values():
+    calls = []
+
+    def count_value(value):
+        calls.append(value)
+        return value
+
+    class XMLDocument(SemanticDictionary):
+        ATTR_XPATHS = {
+            'description': ('.//Description', True, count_value),
+        }
+
+    document = XMLDocument(
+        etree.fromstring(b'<Root><Description>cached</Description></Root>')
+    )
+
+    assert document.description == 'cached'
+    assert document.description == 'cached'
+    assert calls == ['cached']
+
+
+def test_xml_iteration_populates_getitem_cache_and_preserves_document():
+    class XMLItem(SemanticDictionary):
+        pass
+
+    class XMLDocument(SemanticDictionary):
+        ITEM_XPATHS = ['.//Item']
+        ITEM_HUMAN_UNIQUE_IDS = ['name']
+        ITEM_CLASSES = [XMLItem]
+
+    root = etree.fromstring(
+        b'<Root><Item name="one"/><Item name="two"/></Root>'
+    )
+    document = XMLDocument(root)
+
+    items = list(document)
+
+    assert len(document) == 2
+    assert document['one'] is items[0]
+    assert all(item.document is root for item in items)
+
+
+def test_getitem_returns_the_cached_wrapped_item():
+    document = CachedDocument([{'name': 'one'}])
+
+    first = document['one']
+    second = document['one']
+
+    assert second is first
+
+
+def test_contains_populates_the_same_item_cache():
+    document = CachedDocument([{'name': 'one'}])
+
+    assert 'one' in document
+    first = document['one']
+    assert document['one'] is first
+
+
+def test_iteration_reuses_wrapped_items_and_len_is_not_lru_size():
+    document = CachedDocument([{'name': str(i)} for i in range(3)])
+
+    first_iteration = list(document)
+    second_iteration = list(document)
+
+    assert len(document) == 3
+    assert second_iteration == first_iteration
+    assert all(left is right for left, right in zip(first_iteration, second_iteration))
+
+    large_document = CachedDocument([{'name': str(i)} for i in range(101)])
+    list(large_document)
+    assert len(large_document) == 101
+
+
+def test_iteration_wraps_items_as_the_iterator_advances():
+    class CountingDocument(CachedDocument):
+        def __init__(self, source):
+            super().__init__(source)
+            self.selected = 0
+
+        def select(self, path, filters=None):
+            self.selected += 1
+            return super().select(path, filters)
+
+    document = CountingDocument([{'name': str(i)} for i in range(3)])
+    iterator = iter(document)
+
+    assert document.selected == 0
+    next(iterator)
+    assert document.selected == 1
+
+
+def test_lru_eviction_rebuilds_the_oldest_item():
+    document = CachedDocument([{'name': str(i)} for i in range(101)])
+
+    first = document['0']
+    for i in range(1, 101):
+        document[str(i)]
+
+    assert document['0'] is not first
+
+
+def test_getattr_returns_the_cached_value():
+    calls = []
+
+    class CountingItem(TreeSemanticDictionary):
+        ATTR_PATHS = {
+            'value': ('.', lambda node: calls.append(node['value']) or node['value']),
+        }
+
+    item = CountingItem({'value': 'cached'})
+
+    assert item.value == 'cached'
+    assert item.value == 'cached'
+    assert calls == ['cached']

{tts_dictionary_interface-0.3.0 → tts_dictionary_interface-0.4.0}/src/tts_dictionary_interface/test/test_contracts.py

@@ -9,9 +9,13 @@ from lxml import etree
 
 from tts_dictionary_interface.base import SemanticDictionary
 from tts_dictionary_interface.contracts import (
+    ApidContract,
     ChannelContract,
     CommandContract,
     ArgumentContract,
+    EnumTableContract,
+    EnumValueContract,
+    EvrArgumentContract,
     EvrContract,
 )
 
@@ -165,3 +169,122 @@ def test_incomplete_evr_raises_only_for_missing_attrs():
         evr.message
     with pytest.raises(NotImplementedError):
         evr.severity
+
+
+class CompleteApid(ApidContract):
+    @property
+    def apid(self):
+        return 42
+
+    @property
+    def name(self):
+        return 'CORE'
+
+    @property
+    def format(self):
+        return '0x%04X'
+
+    @property
+    def title(self):
+        return 'Core packet'
+
+    @property
+    def description(self):
+        return 'Core application packet'
+
+    @property
+    def module(self):
+        return 'core'
+
+    @property
+    def opscat(self):
+        return 'CORE'
+
+
+def test_apid_contract_required_attributes_and_optional_defaults():
+    apid = CompleteApid()
+    assert isinstance(apid, ApidContract)
+    assert apid.apid == 42
+    assert apid.name == 'CORE'
+    assert apid.format == '0x%04X'
+    assert apid.title == 'Core packet'
+    assert apid.description == 'Core application packet'
+    assert apid.module == 'core'
+    assert apid.opscat == 'CORE'
+    assert apid.recorded is None
+    assert apid.downlink_info is None
+
+
+class IncompleteApid(ApidContract):
+    @property
+    def apid(self):
+        return 42
+
+
+def test_apid_contract_required_attributes_fail_lazily():
+    apid = IncompleteApid()
+    with pytest.raises(NotImplementedError):
+        apid.name
+
+
+class CompleteEvrArgument(EvrArgumentContract):
+    @property
+    def name(self):
+        return 'count'
+
+
+def test_evr_argument_contract_optional_attributes_default_to_none():
+    argument = CompleteEvrArgument()
+    assert isinstance(argument, EvrArgumentContract)
+    assert argument.name == 'count'
+    assert argument.type is None
+    assert argument.length is None
+    assert argument.enum is None
+
+
+class CompleteEnumTable(EnumTableContract):
+    @property
+    def name(self):
+        return 'modes'
+
+    @property
+    def values(self):
+        return []
+
+
+class CompleteEnumValue(EnumValueContract):
+    @property
+    def name(self):
+        return 'OFF'
+
+    @property
+    def value(self):
+        return 0
+
+
+def test_enum_contracts_expose_required_attributes():
+    table = CompleteEnumTable()
+    value = CompleteEnumValue()
+    assert isinstance(table, EnumTableContract)
+    assert isinstance(value, EnumValueContract)
+    assert table.name == 'modes'
+    assert table.values == []
+    assert value.name == 'OFF'
+    assert value.value == 0
+
+
+class ExtendedArgument(ArgumentContract):
+    @property
+    def name(self):
+        return 'mode'
+
+    @property
+    def length(self):
+        return 8
+
+
+def test_argument_contract_extended_attributes_default_to_none():
+    argument = ExtendedArgument()
+    assert argument.type is None
+    assert argument.description is None
+    assert argument.enum is None

{tts_dictionary_interface-0.3.0 → tts_dictionary_interface-0.4.0}/src/tts_dictionary_interface/tree.py

@@ -204,11 +204,11 @@ class TreeSemanticDictionary(BaseSemanticDictionary):
         """
         if filters:
             # For TreeSemanticDictionary, we append the filter to the path.
-            # Note: we use ' and ' as per the original implementation, 
+            # Note: we use ' and ' as per the original implementation,
             # but BaseSemanticDictionary calls select() in a loop for OR.
             filter_str = ' and '.join(f'{attr.strip()}="{val}"' for attr, val in filters.items())
             path = f"{path}[{filter_str}]"
-        
+
         return select(self.node, path)
 
     def path(self, path):

{tts_dictionary_interface-0.3.0 → tts_dictionary_interface-0.4.0/src/tts_dictionary_interface.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tts-dictionary-interface
-Version: 0.3.0
+Version: 0.4.0
 Summary: Core code for developing Python AMPCS dictionary interfaces.
 Author: muszynsk
 Author-email: muszynsk <matt.muszynski@jpl.nasa.gov>

{tts_dictionary_interface-0.3.0 → tts_dictionary_interface-0.4.0}/src/tts_dictionary_interface.egg-info/SOURCES.txt

@@ -8,9 +8,11 @@ ci/sphinx_ignore_tags.txt
 docs/conf.py
 docs/foo.rst
 docs/index.rst
+docs/narrative.rst
 docs/semantic_dictionary_cache_spec.md
 docs/_static/bugfix.css
 docs/agents/README.md
+docs/agents/check_docstring_coverage.py
 src/__init__.py
 src/tts_dictionary_interface/__init__.py
 src/tts_dictionary_interface/base.py
@@ -28,6 +30,7 @@ src/tts_dictionary_interface/test/__init__.py
 src/tts_dictionary_interface/test/conftest.py
 src/tts_dictionary_interface/test/test_ait_loader.py
 src/tts_dictionary_interface/test/test_base.py
+src/tts_dictionary_interface/test/test_cache.py
 src/tts_dictionary_interface/test/test_contracts.py
 src/tts_dictionary_interface/test/test_tree.py
 src/tts_dictionary_interface/test/fixtures/ait_yaml/demosat_includes/ccsds_header.yaml