tts-dictionary-interface 0.2.3__py3-none-any.whl

tts_dictionary_interface/base.py

@@ -0,0 +1,244 @@
+import pdb
+from pathlib import Path
+import os
+from lxml import etree
+
+from tts_utilities.logger import create_logger
+logger = create_logger('semantic_dictionary')
+
+#Requirements:
+#    Commands
+#        Every project needs to have a command dictioanry
+#        Every command class needs a stem attr
+#        Every command class needs an opcode attr
+#        Every command class needs an opscat attr
+#        Every command class needs an args attr that is an ArgumentList
+#        Every command argument needs a name attr
+#        Every command argument needs a units attr
+#        Every command argument needs a way to understand length
+#        Every command argument needs a min attr (is this true for all? or just for numeric?)
+#        Every command argument needs a max attr (is this true for all? or just for numeric?)
+#    Channels
+#        Every project needs to have a channel dictioanary
+#        Every channel class needs an measurement_id attr
+#        Every channel class needs a channel_id attr
+#        Every channel class needs a channel_name attr
+#        Every channel class needs an opscat attr
+#        Every channel class needs to have a type attr
+#            Needs to be translated to chill type (e.g. naive dn/eu/status/dnString)
+
+class SemanticDictionary:
+    """
+    A base reading AMPCS dictionaries (or really any XML file) more Pythonically.
+
+	This class is a bit obtuse, so please take a look at DemoSat's implementation in
+	tts-demosat/demosat_dictionary_interface for an example of how this looks when
+	realized against an actual space mission.
+
+    This class provides a dictionary-like interface to an XML tree. It allows retrieval of
+    items via specific unique IDs defined in the subclass configuration, and dynamic
+    attribute access via configured XPaths.
+
+    Attributes:
+        ITEM_XPATHS (list): A list of XPath strings used to find items. An item in this context is
+        the primary human-parseable artifact in the XML. (e.g. for command.xml, it's a command). If
+        you extend SemanticDictionary and do "for x in SemanticDictionaryExtension: x", you will
+        iterate through these "items""
+        ITEM_HUMAN_UNIQUE_IDS (list): The expected human-readable ID for items
+        ITEM_CLASSES (list): The class to pass items ETREE elements to.
+        ATTR_XPATHS (dict): A mapping of XML xpaths to Pyhton attributes
+    """
+    ITEM_XPATHS = []
+    ITEM_HUMAN_UNIQUE_IDS = []
+    ITEM_CLASSES = []
+    ATTR_XPATHS = {}
+
+    def __init__(self, source):
+        """
+        Initialize the SemanticDictionary with a source XML.
+
+        Args:
+            source (str, os.PathLike, etree._ElementTree, or etree.Element): The source of the
+                XML data. This can be a file path string, a Path object, a full ElementTree,
+                or a specific Element node. This library is meant to be called recursively,
+                so this might be the file passed by the user or it might be an ETREE Element
+                passed by another SemanticDictionary
+        """
+        # Check if source is a string OR a Path object (os.PathLike covers pathlib)
+        if isinstance(source, (str, os.PathLike)):
+            # Force conversion to string for lxml.parse, just to be safe
+            tree = etree.parse(str(source))
+            self.etree = tree.getroot()
+        elif isinstance(source, etree._ElementTree):
+            self.etree = source.getroot()
+        else:
+            # Assume it is already an lxml Element
+            self.etree = source
+
+    def xpath(self, xpath):
+        """
+        Run a raw XPath query against the root element of this dictionary. Literally just
+        a passthrough of etree.xpath so you can get to any part of the XML you want below
+        this node.
+
+        Args:
+            xpath (str): The XPath query string to execute.
+
+        Returns:
+            list: A list of lxml elements or values matching the query.
+        """
+        return self.etree.xpath(xpath)
+
+    def __getitem__(self, item):
+        """
+        Retrieve a specific item from the dictionary by its unique identifier.
+
+        This iterates through the configured ITEM_XPATHS and ITEM_HUMAN_UNIQUE_IDS. It constructs
+        an XPath query to find the element where the unique ID attribute matches the provided item.
+
+        Args:
+            item (str): The unique identifier value (e.g., a command stem or channel ID) to search for.
+
+        Returns:
+            object: An instance of the corresponding class from ITEM_CLASSES wrapping the found element.
+
+        Raises:
+            Exception: If no elements are found matching the identifier.
+            Exception: If more than one element is found matching the identifier.
+        """
+        elements = []
+        xpaths = []
+        
+        for itemxpath, itemid, itemclass in zip(self.ITEM_XPATHS, self.ITEM_HUMAN_UNIQUE_IDS, self.ITEM_CLASSES):
+            # 1. Build the condition list (Handles keys like 'name|abbreviation')
+            conditions = []
+            for attr in itemid.split('|'):
+                attr = attr.strip()
+                
+                # Special handling: Look at text content vs attributes
+                if attr == 'text()':
+                    conditions.append(f'text()="{item}"')
+                else:
+                    conditions.append(f'@{attr}="{item}"')
+            
+            # 2. Join with OR and wrap in brackets: [name="X" or abbreviation="X"]
+            attr_def = '[' + ' or '.join(conditions) + ']'
+            
+            # 3. Execute Query
+            xpath_query = f'{itemxpath}{attr_def}'
+            xpaths.append(xpath_query)
+            elements += [itemclass(x) for x in self.etree.xpath(xpath_query)]
+
+        if len(elements) == 0:
+            raise Exception(f'No elements found with value "{item}" on xpath(s): {xpaths}')
+        if len(elements) > 1:
+            raise Exception(f'More than one element found with value "{item}" on xpath(s): {xpaths}')
+            
+        return elements[0]
+
+    def __getattr__(self, attr):
+        """
+        Retrieve a dynamic attribute or a standard XML attribute.
+
+        If the attribute is defined in ATTR_XPATHS, the configured XPath is executed.
+        Otherwise, it attempts to get the value as a standard attribute of the XML root.
+
+        Args:
+            attr (str): The name of the attribute to retrieve.
+
+        Returns:
+            Any: The wrapped object, text content, or raw element if defined in ATTR_XPATHS;
+                 otherwise, the string value of the XML attribute on the root element.
+        """
+        if attr in self.ATTR_XPATHS.keys():
+            config = self.ATTR_XPATHS[attr]
+            xpath = config[0]
+            is_text = config[1]
+            attr_class = config[2]
+            # Safely get the 4th argument, default to False
+            return_list = config[3] if len(config) > 3 else False
+
+            element_list = self.etree.xpath(xpath)
+
+            # Helper to safely extract value/text from a single result
+            def resolve_value(item):
+                if attr_class is not None:
+                    return attr_class(item)
+                
+                # If we asked for text, but got an Element, get .text
+                if is_text and hasattr(item, 'text'):
+                    return item.text
+                
+                # If we asked for text, but item is already a string (because xpath ended in /text()), return it
+                if is_text and isinstance(item, str):
+                    return item
+                
+                # Otherwise return the raw item (Element or String)
+                return item
+
+            # --- 1. Nothing Found ---
+            if len(element_list) == 0:
+                # If expecting a list, return empty list. Otherwise None.
+                return [] if return_list else None
+
+            # --- 2. List Requested ---
+            if return_list:
+                return [resolve_value(e) for e in element_list]
+
+            # --- 3. Single Item Requested ---
+            return resolve_value(element_list[0])
+
+        else:
+            return self.etree.get(attr)
+
+    def __iter__(self):
+        """
+        Iterate over all configured items in the dictionary.
+
+        This method chains together all elements found by the configured ITEM_XPATHS,
+        wrapping them in their respective ITEM_CLASSES.
+
+        Yields:
+            object: Instances of the item classes defined in the configuration.
+        """
+        elements = []
+        for itemxpath, itemclass in zip(self.ITEM_XPATHS, self.ITEM_CLASSES):
+            elements += [itemclass(x) for x in self.etree.xpath(itemxpath)]
+        for e in elements: yield e
+
+    def __len__(self):
+        # Return the number of items in the members list
+        return len([x for x in self])
+
+    def __contains__(self, key):
+        """
+        Enables 'if "KEY" in dictionary' syntax.
+
+        Iterates through the configured ITEM_XPATHS and ITEM_HUMAN_UNIQUE_IDS
+        to checks if an element with the given key exists.
+        """
+        # Zip together the XPath locations and the Attribute IDs defining "uniqueness"
+        for itemxpath, itemid in zip(self.ITEM_XPATHS, self.ITEM_HUMAN_UNIQUE_IDS):
+            
+            # 1. Build the condition list (Handles keys like 'name|abbreviation')
+            conditions = []
+            for attr in itemid.split('|'):
+                attr = attr.strip()
+                
+                # Special handling: Look at text content vs attributes
+                if attr == 'text()':
+                    conditions.append(f'text()="{key}"')
+                else:
+                    conditions.append(f'@{attr}="{key}"')
+            
+            # 2. Join with OR: [name="X" or abbreviation="X"]
+            predicate = " or ".join(conditions)
+            
+            # 3. Construct full query: e.g. telemetry_definitions/telemetry[@name="X"]
+            query = f"{itemxpath}[{predicate}]"
+            
+            # 4. Check existence (xpath returns a list; empty list is False)
+            if self.etree.xpath(query):
+                return True
+                
+        return False        

tts_dictionary_interface/test/test_base.py

@@ -0,0 +1,172 @@
+import sys
+import pytest
+from unittest.mock import MagicMock, patch
+from lxml import etree
+
+# --- MOCKING EXTERNAL DEPENDENCIES ---
+# We mock tts_utilities before importing the module to avoid ModuleNotFoundError
+sys.modules['tts_utilities'] = MagicMock()
+sys.modules['tts_utilities.logger'] = MagicMock()
+
+# Assuming the user's code is in a file named `semantic_dictionary.py`
+# If you are pasting this into a single file, put the class definition above this line.
+from tts_dictionary_interface.base import SemanticDictionary
+
+# --- FIXTURES AND SETUP ---
+
+@pytest.fixture
+def sample_xml():
+    """Creates a temporary sample XML string for testing."""
+    return b"""
+    <Project name="TestProject" version="1.0">
+        <Commands>
+            <Command stem="CMD_A" opcode="0x01" opscat="flight">
+                <Args>
+                    <Arg name="arg1" units="sec" min="0" max="10"/>
+                </Args>
+            </Command>
+            <Command stem="CMD_B" opcode="0x02" opscat="ground">
+                <Args>
+                    <Arg name="arg2" units="m/s"/>
+                </Args>
+            </Command>
+             <Command stem="CMD_DUP" opcode="0x03" />
+            <Command stem="CMD_DUP" opcode="0x04" />
+        </Commands>
+        <Channels>
+            <Channel id="100" name="ChanA" type="float"/>
+        </Channels>
+        <Metadata>
+            <Description>A test dictionary</Description>
+        </Metadata>
+    </Project>
+    """
+
+class CommandWrapper:
+    """A dummy wrapper class to test ITEM_CLASSES instantiation."""
+    def __init__(self, element):
+        self.element = element
+        self.stem = element.get('stem')
+
+class ConcreteDictionary(SemanticDictionary):
+    """
+    A concrete implementation of the base class.
+    We must populate the configuration constants to test the logic.
+    """
+    # Look for Commands, identify them by 'stem' or 'opcode', wrap them in CommandWrapper
+    ITEM_XPATHS = ['.//Command']
+    ITEM_HUMAN_UNIQUE_IDS = ['stem|opcode'] 
+    ITEM_CLASSES = [CommandWrapper]
+    
+    # Map 'description' to the text of the Description tag
+    # Map 'project_name' to the 'name' attribute of the root (via fallback or XPath)
+    ATTR_XPATHS = {
+        'description': ('.//Description', True, None),  # (xpath, is_text, class)
+        'all_args': ('.//Arg', False, None) # Return raw element list (or first element)
+    }
+
+@pytest.fixture
+def concrete_dict(tmp_path, sample_xml):
+    """Creates an instance of the ConcreteDictionary using a temporary file."""
+    f = tmp_path / "test_dict.xml"
+    f.write_bytes(sample_xml)
+    return ConcreteDictionary(str(f))
+
+# --- TEST CASES ---
+
+class TestInitialization:
+    def test_init_with_path(self, tmp_path, sample_xml):
+        f = tmp_path / "test.xml"
+        f.write_bytes(sample_xml)
+        sd = SemanticDictionary(str(f))
+        assert isinstance(sd.etree, etree._Element)
+
+    def test_init_with_element(self, sample_xml):
+        root = etree.fromstring(sample_xml)
+        sd = SemanticDictionary(root)
+        assert sd.etree == root
+
+    def test_init_invalid_path(self):
+        with pytest.raises(OSError):
+            SemanticDictionary("non_existent_file.xml")
+
+class TestGetItem:
+    """Tests for __getitem__ (e.g., dict['key'])"""
+    
+    def test_get_item_by_stem_success(self, concrete_dict):
+        # Should find CMD_A using the 'stem' attribute defined in ITEM_HUMAN_UNIQUE_IDS
+        item = concrete_dict['CMD_A']
+        assert isinstance(item, CommandWrapper)
+        assert item.element.get('opcode') == '0x01'
+
+    def test_get_item_by_opcode_success(self, concrete_dict):
+        # Should find CMD_B using the 'opcode' attribute (second part of the split)
+        item = concrete_dict['0x02']
+        assert item.stem == 'CMD_B'
+
+    def test_get_item_not_found(self, concrete_dict):
+        with pytest.raises(Exception) as excinfo:
+            _ = concrete_dict['NON_EXISTENT']
+        assert "No elements found" in str(excinfo.value)
+
+    def test_get_item_multiple_found(self, concrete_dict):
+        # CMD_DUP exists twice in the XML
+        with pytest.raises(Exception) as excinfo:
+            _ = concrete_dict['CMD_DUP']
+        assert "More than one element found" in str(excinfo.value)
+
+class TestGetAttr:
+    """Tests for __getattr__ (e.g., dict.attr)"""
+
+    def test_getattr_configured_xpath_text(self, concrete_dict):
+        # 'description' is mapped to .//Description text
+        assert concrete_dict.description == "A test dictionary"
+
+    def test_getattr_configured_xpath_element(self, concrete_dict):
+        # 'all_args' is mapped to .//Arg, is_text=False
+        # It should return the first matching element
+        arg = concrete_dict.all_args
+        assert isinstance(arg, etree._Element)
+        assert arg.get('name') == 'arg1'
+
+    def test_getattr_fallback_to_root_attr(self, concrete_dict):
+        # 'version' is NOT in ATTR_XPATHS, so it should look at root attributes
+        assert concrete_dict.version == "1.0"
+
+    def test_getattr_not_found_in_config(self, concrete_dict):
+        # If xpath exists in config but finds nothing in XML
+        # We need to temporarily modify the ATTR_XPATHS for this specific instance/class test
+        # or rely on a specific test case.
+        # Let's try accessing a root attribute that doesn't exist
+        assert concrete_dict.non_existent_attr is None
+
+    def test_getattr_xpath_no_elements_returns_none(self, concrete_dict):
+        # We temporarily add a broken configuration to the class
+        ConcreteDictionary.ATTR_XPATHS['broken'] = ('.//NonExistentTag', True, None)
+        
+        # Access it
+        val = concrete_dict.broken
+        
+        # ASSERT: It should just return None gracefully (no crash)
+        # We removed the logger check because your implementation doesn't log anymore.
+        assert val is None
+
+class TestIteration:
+    """Tests for __iter__"""
+
+    def test_iter_yields_wrappers(self, concrete_dict):
+        items = list(concrete_dict)
+        # We expect 4 commands total in the sample XML (CMD_A, CMD_B, and 2x CMD_DUP)
+        assert len(items) == 4
+        assert all(isinstance(x, CommandWrapper) for x in items)
+        
+        stems = [x.stem for x in items]
+        assert "CMD_A" in stems
+        assert "CMD_B" in stems
+
+class TestXPathHelper:
+    def test_xpath_method(self, concrete_dict):
+        # Testing the wrapper method .xpath()
+        results = concrete_dict.xpath('.//Command')
+        assert len(results) == 4
+        assert isinstance(results[0], etree._Element)

tts_dictionary_interface-0.2.3.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: tts-dictionary-interface
+Version: 0.2.3
+Summary: Core code for developing Python AMPCS dictionary interfaces.
+Author: muszynsk
+Author-email: muszynsk <matt.muszynski@jpl.nasa.gov>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/NASA-JPL-Teamtools-Studio/tts_dictionary_interface
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: lxml
+Requires-Dist: pytest
+Requires-Dist: tomli
+Requires-Dist: tts-utilities<=1.0.0,>=0.2.2
+Dynamic: author
+Dynamic: requires-python
+
+# Teamtools Dictionary Interface
+
+![Project logo](https://github.com/NASA-JPL-Teamtools-Studio/teamtools_documentation/blob/main/docs/images/tts_image_artifacts/tts_dictionary_interface.png)
+
+## About Teamtools Studio
+
+Teamtools Studio Utilities is part of JPL's Teamtools Studio (TTS).
+
+TTS is an effort originated in JPL's Planning and Execution section to centralize shared repositories across missions. This benefits JPL by reducing cost through reducing duplicated code, collaborating across missions, and unifying standards for development and design across JPL.
+
+Although Planning and Execution is primarily concerned with flight operations, the TTS suite has been generalized and atomized to the point where many of these tools are applicable during other mission phases and even in non-spaceflight contexts. Through our work flying space missions, we hope to provide tools to the open source community that have utility in data analysis or planning for any complex system where failure is not an option.
+
+For more infomation on how to contribute, and how these libraries form a complete ecosystem for high reliability data analysis, see the [Full TTS Documentation](https://nasa-jpl-teamtools-studio.github.io/teamtools_documentation/).
+
+## What is Teamtools Dictionary Interface?
+
+### Overview
+
+The TTS Dicitonary Interface is an interoperability solution to ensure that other TTS libraries (Dexter, Tower, Dante, TTS Seq, FRESH) can
+make common assumptions about how to retreive the metadata on spacraft commands and telemetry they need in order to appropriately interpret it.
+This helps them answer questions like "is this arugment value valid?" and "what are the units for this telemetry point?".
+
+Dictionaries are a key part of the Flight Ground Interface for any spacecraft. They containing the information needed to translate human-readable commands and arugments to binary files that make sense to a spacecraft's command and sequencing flight software and the to take the stream of
+ones and zeros returned from the spacecraft back into human-readable telemetry back on the ground. They are the Rosetta Stone of any space mission.
+
+While TTS Dictionary Interface is built around AMPCS's XML dictionary schema, it can ostensibly be used with any format of dictionary so long
+as it can be made into a Pyhton class that behaves the same way that the SemanticDictionary does. More than anything this is an interoperability
+layer.
+
+For projects that do not use AMPCS, the easiest way to leverage this library is likely to write some middleware to turn your dictionary format
+into the kind of XML that would be required if you were using AMPCS. Short of that, it is likely that the only other solution is to write
+a completely new class that looks to downstream TTS modules as if it were generated by TTS Dictionary Interface. This is likely much harder
+to validate than simply converting to XML and validating against the multimisison AMPCS schema shared in the DemoSat extension of this library.
+
+### Projects Currently Supported
+
+* DemoSat
+* Orbiting Carbon Observatory 2 (OCO-2)
+* NISAR
+
+## Architecture
+
+### TTS dependencies
+
+* TTS Utilities

tts_dictionary_interface-0.2.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+tts_dictionary_interface/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tts_dictionary_interface/base.py,sha256=wSlfvspI4aNqlCabaFF417LG-ss0YM_7nIUsVy07CyQ,10172
+tts_dictionary_interface/test/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tts_dictionary_interface/test/conftest.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tts_dictionary_interface/test/test_base.py,sha256=qs7BK9_xMDJSJOhVG1tOfQ4AgUzSNiqkVK-KQhNfEeU,6557
+tts_dictionary_interface-0.2.3.dist-info/METADATA,sha256=ucgYDLUclmA8OT4ogYUI2TrkmqaGIq7yCvbTWC3QE6M,3801
+tts_dictionary_interface-0.2.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+tts_dictionary_interface-0.2.3.dist-info/top_level.txt,sha256=irz1oGRGtuTqgAI3v5XIQNQ_HcrqNQ46G3atDGfpG48,25
+tts_dictionary_interface-0.2.3.dist-info/RECORD,,

tts_dictionary_interface-0.2.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tts_dictionary_interface-0.2.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+tts_dictionary_interface