antelope-interface 0.3.4__tar.gz → 0.3.5__tar.gz

{antelope_interface-0.3.4/src/antelope_interface.egg-info → antelope_interface-0.3.5}/PKG-INFO

@@ -1,21 +1,20 @@
 Metadata-Version: 2.4
 Name: antelope_interface
-Version: 0.3.4
+Version: 0.3.5
 Summary: A common interface for accessing LCA data
 Author-email: Brandon Kuczenski <bkuczenski@ucsb.edu>
 License: BSD-3-Clause
 Keywords: one,two
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.6
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: synonym_dict>=0.2.5
+Requires-Dist: synonym_dict>=0.2.7
 Requires-Dist: pydantic>=2.5.0
 Dynamic: license-file
 

{antelope_interface-0.3.4 → antelope_interface-0.3.5}/pyproject.toml

@@ -9,20 +9,19 @@ authors =[
 ]
 description = "A common interface for accessing LCA data"
 readme ={ file = "README.md", content-type = "text/markdown"}
-requires-python = ">=3.6"
+requires-python = ">=3.10"
 keywords = ["one", "two"]
 license = {text = "BSD-3-Clause"}
 classifiers = [
          "Development Status :: 4 - Beta",
         "Intended Audience :: Science/Research",
-        "License :: OSI Approved :: BSD License",
         "Natural Language :: English",
         "Operating System :: OS Independent",
         "Programming Language :: Python :: 3",
         "Topic :: Scientific/Engineering"
 ]
-dependencies = ["synonym_dict >= 0.2.5", "pydantic >= 2.5.0"]
-version = "0.3.4"
+dependencies = ["synonym_dict >= 0.2.7", "pydantic >= 2.5.0"]
+version = "0.3.5"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{antelope_interface-0.3.4 → antelope_interface-0.3.5}/setup.py

@@ -5,6 +5,9 @@ setup()
 
 """
 Version History:
+0.3.5  2026/09/25 - Add ArchiveInterface. fix a bug with needy QuantityRefs.
+
+0.3.4.1           - rename 'enum' to 'e_' because that was messed up
 0.3.4  2026/03/31 - add 'dash' interface type; add 'grant_add' to XDB tokens
 
 0.3.3.1           - sanitize process reference exchange in entity model; cached basic queries

{antelope_interface-0.3.4 → antelope_interface-0.3.5}/src/antelope/__init__.py

@@ -5,7 +5,7 @@ The abstract classes in this sub-package define what information is made availab
 resource of some kind.  The interfaces must be instantiated in order to be used.  In the core package
 """
 
-from .interfaces import ANTELOPE_INTERFACES
+from .interfaces import ANTELOPE_INTERFACES, ArchiveInterface, TermManagerInterface
 
 from .interfaces.ibasic import BasicInterface, EntityNotFound, NoAccessToEntity, ItemNotFound
 from .interfaces.iconfigure import ConfigureInterface
@@ -58,7 +58,7 @@ class BasicQuery(BasicInterface, IndexInterface, ExchangeInterface, QuantityInte
      - archive.source: returns the physical source (or URI) for the archive's content
 
     """
-    def __init__(self, archive, debug=False, cached=True):
+    def __init__(self, archive: ArchiveInterface, debug=False, cached=True):
         self._archive = archive
         self._dbg = debug
         self.cached = cached
@@ -89,6 +89,16 @@ class BasicQuery(BasicInterface, IndexInterface, ExchangeInterface, QuantityInte
         else:
             return entity  # already a ref
 
+    def get(self, eid, **kwargs):
+        """
+        A query must return a ref, because the ref encapsulates the query
+        :param eid:
+        :param kwargs:
+        :return:
+        """
+        entity = self._perform_query('basic', 'get', EntityNotFound, eid, **kwargs)
+        return self.make_ref(entity)
+
     def __str__(self):
         return '%s(%s:%s:%s)' % (self.__class__.__name__, self.origin,
                                  self._archive.__class__.__name__,
@@ -155,7 +165,7 @@ def q_node_activity(fg):
         return fg.get_canonical('node activity')
 
 
-def enum(iterable, filt=None, invert=True):
+def e_(iterable, filt=None, invert=True):
     """
     Enumerate an iterable for interactive use. return it as a list. Optional negative filter supplied as regex.
 

{antelope_interface-0.3.4 → antelope_interface-0.3.5}/src/antelope/interfaces/__init__.py

@@ -1,3 +1,5 @@
 from .abstract_query import ANTELOPE_INTERFACES
 from .ibasic import EntityNotFound, NoAccessToEntity, ItemNotFound
 from .iindex import check_direction, InvalidDirection, InvalidSense
+from .iarchive import ArchiveInterface
+from .iterm_manager import TermManagerInterface

antelope_interface-0.3.5/src/antelope/interfaces/iarchive.py

@@ -0,0 +1,67 @@
+"""
+Abstract interface for archive providers.
+
+An archive is the object stored in ``BasicImplementation._archive`` (and all
+subclass implementations).  Any object that satisfies this interface can be
+used as a provider for the standard implementation classes.
+
+The surface was derived by auditing every ``self._archive.*`` access across
+``antelope_core/implementations/*.py``.
+"""
+
+from abc import abstractmethod
+from typing import runtime_checkable, Protocol
+
+
+@runtime_checkable
+class ArchiveInterface(Protocol):
+    """
+    Minimal contract that a provider object must satisfy to work with the
+    standard ``*Implementation`` classes in ``antelope_core``.
+
+    Read-only requirements are marked with ``@property``; methods that may
+    mutate the store are marked accordingly in their docstrings.
+    """
+
+    # ------------------------------------------------------------------
+    # Identity / metadata
+    # ------------------------------------------------------------------
+
+    @property
+    @abstractmethod
+    def ref(self) -> str:
+        """Semantic reference string used as the archive's origin identifier."""
+
+    @property
+    @abstractmethod
+    def source(self) -> str:
+        """Physical data source (file path, URL, etc.) — used for display."""
+
+    # ------------------------------------------------------------------
+    # Entity access
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def __getitem__(self, key):
+        """
+        Return the already-loaded entity for *key*, or ``None`` if not present.
+        Must never raise on a cache miss — return ``None`` instead.
+        """
+
+    @abstractmethod
+    def _fetch(self, key, **kwargs):
+        """
+        Obtain the entity for *key* in a provider-specific way.  Raise ``EntityNotFound`` on failure
+        """
+
+    # ------------------------------------------------------------------
+    # Interface factory
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def make_interface(self, itype: str):
+        """
+        Return an implementation object for the named interface type string
+        (``'basic'``, ``'index'``, ``'exchange'``, ``'quantity'``,
+        ``'background'``, ``'configure'``).
+        """

antelope_interface-0.3.5/src/antelope/interfaces/iterm_manager.py

@@ -0,0 +1,138 @@
+"""
+Abstract interface for term manager providers.
+
+A term manager is the object stored in ``archive.tm``.  It handles synonym
+resolution for flowables and contexts, and manages characterization factors.
+
+The surface was derived by auditing every ``self._archive.tm.*`` access across
+``antelope_core/implementations/*.py``.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class TermManagerInterface(ABC):
+    """
+    Minimal contract that a term manager object must satisfy to work with the
+    standard ``*Implementation`` classes in ``antelope_core``.
+    """
+
+    # ------------------------------------------------------------------
+    # Identity
+    # ------------------------------------------------------------------
+
+    @property
+    @abstractmethod
+    def is_lcia_engine(self) -> bool:
+        """
+        True if this term manager operates as a full LCIA engine — i.e. it
+        uses a standard canonical set of flowables and contexts and can match
+        synonyms across data sources.  False for a provincial term manager
+        that treats its own archive as the sole source of truth.
+        """
+
+    # ------------------------------------------------------------------
+    # Lookup
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def __getitem__(self, term):
+        """
+        Look up *term* and return the matching ``Context`` (or flowable
+        canonical name), or ``None`` if not found.  *term* may be a string
+        synonym, a ``Context`` object, or ``None``.
+
+        Used by ``BasicImplementation.get_context`` and
+        ``QuantityImplementation._get_flowable_info``.
+        """
+
+    @abstractmethod
+    def get_flowable(self, flow):
+        """
+        Return the canonical flowable name for *flow*.
+        Raises ``KeyError`` if not recognised.
+
+        Used by ``IndexImplementation.unmatched_flows``.
+        """
+
+    @abstractmethod
+    def get_canonical(self, quantity):
+        """
+        Return the canonical quantity entity for *quantity* (which may be a
+        string external_ref or a quantity object).
+        Raises ``EntityNotFound`` if not recognised.
+
+        Used by ``QuantityImplementation.get_canonical`` and related helpers.
+        """
+
+    # ------------------------------------------------------------------
+    # Enumeration
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def synonyms(self, item):
+        """
+        Generate synonym strings for the given flowable or context *item*.
+
+        Used by ``BasicImplementation.synonyms``.
+        """
+
+    @abstractmethod
+    def flowables(self, **kwargs):
+        """
+        Generate canonical flowable name strings, optionally filtered by
+        keyword arguments.
+
+        Used by ``IndexImplementation.flowables``.
+        """
+
+    @abstractmethod
+    def contexts(self, **kwargs):
+        """
+        Generate ``Context`` objects known to this term manager, optionally
+        filtered by keyword arguments.
+
+        Used by ``IndexImplementation.contexts``.
+        """
+
+    # ------------------------------------------------------------------
+    # Characterization factors
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def factors_for_quantity(self, quantity, flowable=None, context=None, dist=0):
+        """
+        Generate ``Characterization`` objects for the given canonical
+        *quantity*, optionally filtered by *flowable* and *context*.
+
+        *dist* controls context-matching strictness:
+          0 = exact match, 1 = child contexts, 2 = parent context,
+          3 = any ancestor including NullContext.
+
+        Used by ``QuantityImplementation.factors``.
+        """
+
+    @abstractmethod
+    def factors_for_flowable(self, flowable, quantity=None, context=None, **kwargs):
+        """
+        Generate ``Characterization`` objects for the given canonical
+        *flowable* string, optionally filtered by *quantity* and *context*.
+
+        Used by ``QuantityImplementation._quantity_engine`` and
+        ``_ref_qty_conversion``.
+        """
+
+    @abstractmethod
+    def add_characterization(self, flowable, ref_quantity, query_quantity,
+                             value, context=None, location='GLO', origin=None,
+                             **kwargs):
+        """
+        Store a characterization factor: 1 unit of *ref_quantity* of
+        *flowable* in *context* equals *value* units of *query_quantity*.
+
+        *location* defaults to ``'GLO'``; *origin* defaults to the archive's
+        own ``ref`` string when called from ``ConfigureImplementation``.
+
+        Used by ``QuantityImplementation.characterize`` and
+        ``ConfigureImplementation.characterize_flow``.
+        """

{antelope_interface-0.3.4 → antelope_interface-0.3.5}/src/antelope/refs/base.py

@@ -165,16 +165,14 @@ class BaseRef(BaseEntity):
 
     def __eq__(self, other):
         """
-        Catalog refs are equal if their external_refs are equal and their origins start with each other
+        Catalog refs are equal if their links are equal
         :param other:
         :return:
         """
         if other is None:
             return False
         try:
-            return (  # (other.entity_type == 'unknown' or self.entity_type == other.entity_type) and
-                    self.external_ref == other.external_ref and
-                    (self.origin.startswith(other.origin) or other.origin.startswith(self.origin)))
+            return self.link == other.link
         except AttributeError:
             return False
 

{antelope_interface-0.3.4 → antelope_interface-0.3.5}/src/antelope/refs/quantity_ref.py

@@ -16,6 +16,7 @@ but it depends on the LciaResult implementation, which is irretrievably part of
 """
 
 from ..flows import FlowInterface
+from ..interfaces.ibasic import ItemNotFound, EntityNotFound
 from .base import EntityRef
 from synonym_dict import LowerDict
 
@@ -160,13 +161,15 @@ class QuantityRef(EntityRef):
             yield self.uuid
         if self.origin is not None:
             yield self.link
-        if self.has_property('Synonyms'):
+        try:
             syns = self['Synonyms']
             if isinstance(syns, str):
                 yield syns
             else:
                 for syn in syns:
                     yield syn
+        except (KeyError, ItemNotFound, EntityNotFound):
+            pass
 
     """
     Interface methods

{antelope_interface-0.3.4 → antelope_interface-0.3.5/src/antelope_interface.egg-info}/PKG-INFO

@@ -1,21 +1,20 @@
 Metadata-Version: 2.4
 Name: antelope_interface
-Version: 0.3.4
+Version: 0.3.5
 Summary: A common interface for accessing LCA data
 Author-email: Brandon Kuczenski <bkuczenski@ucsb.edu>
 License: BSD-3-Clause
 Keywords: one,two
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.6
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: synonym_dict>=0.2.5
+Requires-Dist: synonym_dict>=0.2.7
 Requires-Dist: pydantic>=2.5.0
 Dynamic: license-file
 

{antelope_interface-0.3.4 → antelope_interface-0.3.5}/src/antelope_interface.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/antelope/flows/flow_interface.py
 src/antelope/flows/openlca_locales.json
 src/antelope/interfaces/__init__.py
 src/antelope/interfaces/abstract_query.py
+src/antelope/interfaces/iarchive.py
 src/antelope/interfaces/ibackground.py
 src/antelope/interfaces/ibasic.py
 src/antelope/interfaces/iconfigure.py
@@ -19,6 +20,7 @@ src/antelope/interfaces/iexchange.py
 src/antelope/interfaces/iforeground.py
 src/antelope/interfaces/iindex.py
 src/antelope/interfaces/iquantity.py
+src/antelope/interfaces/iterm_manager.py
 src/antelope/models/__init__.py
 src/antelope/models/auth.py
 src/antelope/models/comparators.py

antelope_interface-0.3.5/src/antelope_interface.egg-info/requires.txt

@@ -0,0 +1,2 @@
+synonym_dict>=0.2.7
+pydantic>=2.5.0

antelope_interface-0.3.4/src/antelope_interface.egg-info/requires.txt

@@ -1,2 +0,0 @@
-synonym_dict>=0.2.5
-pydantic>=2.5.0