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

tts_dictionary_interface-0.4.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.4.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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tts-dictionary-interface
-Version: 0.2.3
+Version: 0.4.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.4.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.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.2.3 → 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.4.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.4.0}/pyproject.toml

@@ -15,6 +15,7 @@ dependencies = [
   "lxml",
   "pytest", 
   "tomli",
+  "pyyaml",
   "tts-utilities>=0.2.2,<=1.0.0"
 ]
 dynamic = ["version"]
@@ -37,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.4.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.4.0/src/tts_dictionary_interface/ait/loader.py

@@ -0,0 +1,106 @@
+"""
+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):
+    """
+    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)
+
+
+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.
+
+    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)
+
+
+class AitYamlDictionary(TreeSemanticDictionary):
+    """
+    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
+    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