antelope-interface 0.2.6.2__tar.gz → 0.3.0__tar.gz

{antelope_interface-0.2.6.2/src/antelope_interface.egg-info → antelope_interface-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: antelope_interface
-Version: 0.2.6.2
+Version: 0.3.0
 Summary: A common interface for accessing LCA data
 Author-email: Brandon Kuczenski <bkuczenski@ucsb.edu>
 License: BSD-3-Clause

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/pyproject.toml

@@ -22,7 +22,7 @@ classifiers = [
         "Topic :: Scientific/Engineering"
 ]
 dependencies = ["synonym_dict >= 0.2.4", "pydantic >= 2.5.0"]
-version = "0.2.6.2"
+version = "0.3.0"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/setup.py

@@ -5,6 +5,19 @@ setup()
 
 """
 Version History:
+0.3.0   2024/10/24 - 0.3.0 release. add comparators.
+
+0.3.0-pre 2024/09/22 - pre-release for workshop (minor bugfix on UnallocatedExchange model)
+
+0.2.7   2024/09/10 - synchronization release for background / LCI changes 
+                     add make_ref() machinery to a few interface routes
+                     alter extend_process to use dependencies instead of inventory
+                     make deep_lcia() biogenic-aware
+                     (note: folding observations directly into lci() / abandoning sys_lcia() still to come)
+
+0.2.6.3 2024/08/15 - cutoff_flows and remote traversal compatibility
+                   - modify FlowInterface and FlowEntity to not die on missing reference_entity
+
 0.2.6.2 2024/06/11 - get_context into basic interface
 0.2.6.1 2024/06/06 - ItemNotFound
 

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/src/antelope/flows/flow.py

@@ -6,6 +6,7 @@ import re
 import json
 
 from abc import ABC
+from collections import defaultdict
 
 from synonym_dict import SynonymSet
 from synonym_dict.flowables.cas_number import CasNumber, InvalidCasNumber
@@ -20,16 +21,6 @@ def flowname_is_biogenic(flowname):
     return bool(biogenic.search(flowname))
 
 
-class QuelledCO2(object):
-    def __init__(self, flowable, context):
-        self.flowable = flowable
-        self.context = context
-
-    @property
-    def value(self):
-        return 0.0
-
-
 """
 openlca_locales.json file created from: antelope_olca package, gen_locales('openlca_locales.json') 
 """
@@ -232,7 +223,7 @@ class Flow(FlowInterface, ABC):
     @property
     def _chars_seen(self):
         if self.__chars_seen is None:
-            self.__chars_seen = dict()
+            self.__chars_seen = defaultdict(dict)
         return self.__chars_seen
 
     @property
@@ -242,7 +233,7 @@ class Flow(FlowInterface, ABC):
                 return True
         return False
 
-    def lookup_cf(self, quantity, context, locale, refresh=False, quell_biogenic_co2=None, **kwargs):
+    def lookup_cf(self, quantity, context, locale, refresh=False, **kwargs):
         """
         Cache characterization factors obtained from quantity relation queries.  It is decided to leave this in
         the interface, since it does not depend on anything from outside the interface.
@@ -251,64 +242,32 @@ class Flow(FlowInterface, ABC):
         locale to retrieve a cached result.  Wildcard results, such as with 'None' specified for any of the three,
         are not supported.
 
-        Two, it requires implementations to properly handle the Quell-Biogenic-CO2 feature (see below).  This is
-        enabled EITHER by passing quell_biogenic_co2 as a parameter OR by assigning it as a property to the quantity.
-        The valid values for this parameter are True (suppress biogenic CO2), False (treat all flows the same), or
-        'only' (inverse of True: quell all flows except biogenic CO2).
+        Two, it requires implementations to properly handle the Quell-Biogenic-CO2 feature.
 
         BIOGENIC CO2: This function includes a mechanism to suppress ALL impact scores for biogenic CO2.  Any flow
-        can have the is_co2 flag set-- this happens automatically if the flow is given a CAS number that matches
-        CO2 (124-38-9). It can also be set in client code.  If this flag is true, AND the flow's name matches a
+        can have the is_co2 flag set-- this happens automatically if the flow is given a name that matches
+        'carbon dioxide' or a CAS number that matches CO2 (124-38-9). It can also be set in client code.
+
+        If this flag is true, AND the flow's name matches a
         regexp that describes non-fossil, biogenic, "in air", then the flow is considered to be biogenic CO2 (its
         quell_co2 property is True).
 
-        WHEN performing a lookup, the function determines whether to quell biogenic CO2 in the following two ways:
-        either the quantity has a property 'quell_biogenic_co2' or the lookup_cf receives a kwarg 'quell_biogenic_co2'
-        The kwarg overrides the quantity property.  IF the boolean value of the specification is 'True', AND the flow's
-        quell_co2 property is True, THEN the flow will return a "QuelledCO2" characterization that always equals 0.
-        Otherwise, it will perform the lookup.
-
-          ** Special feature ** setting the quantity's 'quell_biogenic_co2' property to the string "only" will cause it
-          to return the INVERSE of quell=True - will return quelled CF for all NON-quelled flows and ONLY measure
-          biogenic CO2.
+        It is up to implementation code to handle these properties.
 
         :param quantity:
         :param context:
         :param locale:
         :param refresh: drop cached result and re-query.
-        :param quell_biogenic_co2: [None] override quantity specification for this property.
         :param kwargs:
         :return: whatever the implementation's quantity_relation() returns
         """
         locale = locale or self.locale
         key = (quantity, context, locale)
 
-        _invert_bio = False
-
-        if quell_biogenic_co2 is not None:
-            if quell_biogenic_co2 == 'only':
-                qbc = False
-                _invert_bio = True
-            else:
-                qbc = bool(quell_biogenic_co2)
-        else:
-            qbc = quantity.get('quell_biogenic_co2')
-            if qbc == 'only':
-                qbc = False
-                _invert_bio = True
-
-        if _invert_bio:
-            if not self.quell_co2:
-                return QuelledCO2(self._flowable, context)
-        else:
-            if qbc:
-                if self.quell_co2:
-                    return QuelledCO2(self._flowable, context)
-
         if refresh:
-            self._chars_seen.pop(key, None)
+            self.pop_char(*key)
         try:
-            return self._chars_seen.__getitem__(key)
+            return self._check_char(*key)
         except KeyError:
             try:
                 qr = quantity.quantity_relation(self.name, self.reference_entity, context, locale=locale, **kwargs)
@@ -316,11 +275,20 @@ class Flow(FlowInterface, ABC):
                 qr = e.args[0]
             except NoFactorsFound:
                 qr = None
-        self._chars_seen[key] = qr
+        self._chars_seen[quantity][context, locale] = qr
         return qr
 
+    def _check_char(self, qq, cx, loc):
+        return self._chars_seen[qq][cx, loc]
+
     def pop_char(self, qq, cx, loc):
-        return self._chars_seen.pop((qq, cx, loc), None)
+        return self._chars_seen[qq].pop((cx, loc), None)
+
+    def clear_chars(self, quantity=None):
+        if quantity:
+            self._chars_seen.pop(quantity, None)
+        else:
+            self.__chars_seen = None
 
     def see_chars(self, qq, cx, cfs):
         """
@@ -331,12 +299,11 @@ class Flow(FlowInterface, ABC):
         :return:
         """
         for cf in cfs:
-            key = qq, cx, cf.locale
-            self._chars_seen[key] = cf
+            self._chars_seen[qq][cx, cf.locale] = cf
 
     def is_seen(self, qq, context=None, locale=None):
         if context is None:
             context = self.context
         if locale is None:
             locale = self.locale
-        return (qq, context, locale) in self._chars_seen
+        return (context, locale) in self._chars_seen[qq]

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/src/antelope/flows/flow_interface.py

@@ -98,7 +98,9 @@ class FlowInterface(BaseEntity, ABC):
     """
     @property
     def unit(self):
-        return self.reference_entity.unit
+        if hasattr(self.reference_entity, 'unit'):
+            return self.reference_entity.unit
+        return ''
 
     @property
     def name(self):

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/src/antelope/interfaces/iforeground.py

@@ -25,7 +25,7 @@ class ForegroundInterface(AbstractQuery):
         return self._perform_query(_interface, 'save', ForegroundRequired, **kwargs)
 
     def find_term(self, term_ref, origin=None, **kwargs):
-        """
+        """ # DEPRECATED
         Find a termination for the given reference.  Essentially do type and validity checking and return something
         that can be used as a valid termination.
         :param term_ref: either an entity, entity ref, or string
@@ -48,8 +48,8 @@ class ForegroundInterface(AbstractQuery):
         :param kwargs:
         :return:
         """
-        return self._perform_query(_interface, 'new_quantity', ForegroundRequired,
-                                   name, ref_unit=ref_unit, **kwargs)
+        return self.make_ref(self._perform_query(_interface, 'new_quantity', ForegroundRequired,
+                                                 name, ref_unit=ref_unit, **kwargs))
 
     def new_flow(self, name, ref_quantity=None, context=None, **kwargs):
         """
@@ -170,7 +170,7 @@ class ForegroundInterface(AbstractQuery):
 
         :param fragment:
         :param exchange_value: [this must be the second positional argument for legacy reasons, but can still be None]
-        :param anchor: [renamed from 'termination' - the latter is still accepted in core+]
+        :param anchor: type-agnostic; left to implementation
         :param name:
         :param scenario:
         :param kwargs:
@@ -204,6 +204,17 @@ class ForegroundInterface(AbstractQuery):
         return self._perform_query(_interface, 'traverse', ForegroundRequired,
                                    fragment, scenario, **kwargs)
 
+    def cutoff_flows(self, fragment, scenario=None, **kwargs):
+        """
+        Report cut-off flows (inputs and outputs to the fragment) grouped as exchanges
+        :param fragment:
+        :param scenario:
+        :param kwargs:
+        :return:
+        """
+        return self._perform_query(_interface, 'cutoff_flows', ForegroundRequired,
+                                   fragment, scenario, **kwargs)
+
     def activity(self, fragment, scenario=None, **kwargs):
         """
         Traverse the fragment, returning direct-descendent nodes only. This must be run on an authentic entity and
@@ -229,5 +240,3 @@ class ForegroundInterface(AbstractQuery):
         """
         return self._perform_query(_interface, 'fragment_lcia', ForegroundRequired,
                                    fragment, quantity_ref, scenario, **kwargs)
-
-

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/src/antelope/models/__init__.py

@@ -46,6 +46,10 @@ class EntityRef(ResponseModel):
     entity_id: str
     entity_type: Optional[str]
 
+    @property
+    def external_ref(self):  # what, was there some taboo against this?
+        return self.entity_id
+
     @classmethod
     def from_entity(cls, entity):
         return cls(origin=entity.origin, entity_id=entity.external_ref, entity_type=entity.entity_type)
@@ -67,10 +71,6 @@ class Entity(EntityRef):
         for k in self.properties.keys():
             yield k
 
-    @property
-    def external_ref(self):  # what, was there some taboo against this?
-        return self.entity_id
-
     @classmethod
     def from_search(cls, entity):
         ent = cls(origin=entity.origin, entity_id=entity.external_ref, entity_type=entity.entity_type,
@@ -169,7 +169,8 @@ class FlowEntity(Entity):
                   properties=dict())
 
         obj.properties['name'] = entity.name
-        obj.properties[entity.reference_field] = entity.reference_entity.external_ref
+        if entity.reference_entity:
+            obj.properties[entity.reference_field] = entity.reference_entity.external_ref
         obj.properties['unit'] = entity.unit
         obj.properties['Synonyms'] = []
 
@@ -198,6 +199,12 @@ class FlowEntity(Entity):
         return cls(origin=ex.origin, entity_id=ex.flow.external_ref, entity_type='flow', context=ex.flow.context,
                    locale=ex.flow.locale, properties=ex.flow.properties)
 
+    def serialize(self):
+        j = super(FlowEntity, self).serialize()
+        j['context'] = self.context
+        j['locale'] = self.locale
+        return j
+
 
 class Context(ResponseModel):
     name: str
@@ -245,7 +252,7 @@ class FlowSpec(ResponseModel):
         if x.type == 'context':
             cx = list(x.termination)
         elif x.type in ('reference', 'cutoff'):
-            cx = None
+            cx = []
         else:
             raise TypeError('%s\nUnknown exchange type %s' % (x, x.type))
         loc = locale or x.flow.locale
@@ -333,6 +340,8 @@ class Exchange(ResponseModel):
         if x.type == 'context':
             cx = list(x.termination)
             term = None
+        elif x.type == 'reference':
+            term = cx = None
         else:
             term = x.termination
             cx = None
@@ -486,9 +495,9 @@ class Characterization(ResponseModel):
     origin: str
     flowable: str
     ref_quantity: str
-    ref_unit: str
+    ref_unit: Optional[str] = None
     query_quantity: str
-    query_unit: str
+    query_unit: Optional[str] = None
     context: List[str]
     value: Dict
 
@@ -499,6 +508,19 @@ class Characterization(ResponseModel):
             ch.value[loc] = cf[loc]
         return ch
 
+    @classmethod
+    def from_cfs(cls, cfs):
+        rq = set(k.ref_quantity for k in cfs)
+        qq = set(k.quantity for k in cfs)
+        fb = set(k.flowable for k in cfs)
+        if len(rq) + len(qq) + len(fb) != 3:
+            raise ValueError('disagreeable CFs')
+        ch = cls.null(cfs[0])
+        for cf in cfs:
+            for loc in cf.locations:
+                ch.value[loc] = cf[loc]
+        return ch
+
     @classmethod
     def null(cls, cf):
         ch =  cls(origin=cf.origin, flowable=cf.flowable,

antelope_interface-0.3.0/src/antelope/models/comparators.py

@@ -0,0 +1,79 @@
+"""
+Comparators
+
+These tools enable quick comparison of sets of exchanges to see if they match
+"""
+from math import isclose
+
+
+def _rx_key(rx):
+    return rx.process.external_ref, rx.flow.external_ref, rx.direction
+
+
+def _exch_key(exch):
+    return exch.flow.external_ref, exch.direction, tuple(exch.termination)
+
+
+def compare_ref_exchanges(s1, s2):
+    """
+    Tests qualitative equivalence of two sets of *reference* exchanges (process, flow, direction).
+    :param s1:
+    :param s2:
+    :return:
+    """
+    set1 = {_rx_key(s) for s in s1}
+    set2 = {_rx_key(s) for s in s2}
+    d1 = set1.difference(set2)
+    d2 = set2.difference(set1)
+    if len(d1) + len(d2) == 0:
+        print('PASS (%d)' % len(set1))
+    else:
+        print('DIFFERENT (%d,%d / %d)' % (len(d1), len(d2), len(set1)))
+    return d1, d2
+
+
+def compare_exchanges(s1, s2):
+    """
+    Tests qualitative equivalence of two sets of *depenedent* exchanges (flow, direction, termination).
+    Returns two sets: those present only in s1, those present only in s2
+    :param s1:
+    :param s2:
+    :return:
+    """
+    set1 = {_exch_key(s) for s in s1}
+    set2 = {_exch_key(s) for s in s2}
+    d1 = set1.difference(set2)
+    d2 = set2.difference(set1)
+    if len(d1) + len(d2) == 0:
+        print('PASS (%d)' % len(set1))
+    else:
+        print('DIFFERENT (%d,%d / %d)' % (len(d1), len(d2), len(set1)))
+    return d1, d2
+
+
+def compare_exchange_values(s1, s2, rel_tol=1e-6):
+    """
+    The exchanges are unordered, so it's nontrivial to test two sets of results against one another.
+    We use the approach of mapping (flow.external_ref, direction, termination) to exchange value.
+    This is a summary test that compares the two sets and returns the entries in s2 that do NOT match
+    the entry in s1 (key error qualifies as nonmatch)
+    Thus a return value of length 0 indicates a passed test.
+    :param s1:
+    :param s2:
+    :param rel_tol: default 1e-6
+    :return: a list of failed exchanges, expressed as 2-tuples: (bad_exch, good_val) or (bad_exch, None)
+    """
+    c = {_exch_key(x): x.value for x in s1}
+    fail = []
+    for s in s2:
+        try:
+            v = c[_exch_key(s)]
+            if not isclose(v, s.value, rel_tol=rel_tol):
+                fail.append((s, v))
+        except KeyError:
+            fail.append((s, None))
+    if len(fail) == 0:
+        print('PASS (%d)' % len(c))
+    else:
+        print('DIFFERENT (%d / %d)' % (len(fail), len(c)))
+    return fail

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/src/antelope/refs/base.py

@@ -17,15 +17,15 @@ without access to a query object that can implement the various methods.
 3. Grounded references should behave equivalently to the entities themselves. (except the remote catalogs can act
 as gatekeepers to decide what information can be disclosed)
 
-The inheritance pattern is:
+The inheritance pattern is: ::
 
-BaseRef
-|    |
-|    EntityRef (grounded by a catalog query)
-|      | \ \
-|    ProcessRef, FlowRef, QuantityRef [...]
-|
-CatalogRef (un-grounded)
+    BaseRef
+    |    |
+    |    EntityRef (grounded by a catalog query)
+    |      |            |         |
+    |    ProcessRef, FlowRef, QuantityRef [...]
+    |
+    CatalogRef (un-grounded)
 
 The CatalogRef can instantiate a grounded reference if supplied with a query object that implements the interface.
 
@@ -56,6 +56,10 @@ class PropertyExists(Exception):
     pass
 
 
+class NoUuid(Exception):
+    pass
+
+
 class BaseRef(BaseEntity):
     """
     A base class for defining entity references.  The base class can also store information, such as properties
@@ -298,12 +302,14 @@ class EntityRef(BaseRef):
                     self._uuid = _uuid
             except InvalidQuery:
                 pass  # a None uuid is fine, but next time we ask, it will check again
+        if self._uuid is NoUuid:
+            return None
         return self._uuid
 
     @uuid.setter
     def uuid(self, value):
         # need to repeat this because uuid is overridden
-        if self._uuid is not None:
+        if self._uuid is not None and self._uuid is not NoUuid:
             raise PropertyExists(self.link, self._uuid)
         if uuid_regex.match(str(value)):
             self._uuid = str(value)
@@ -367,6 +373,9 @@ class EntityRef(BaseRef):
             return False
         return True
 
+    def check_bg(self):
+        return self._query.check_bg()
+
     def properties(self, force_query=False):
         if force_query:
             try:

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/src/antelope/refs/process_ref.py

@@ -1,5 +1,6 @@
 from .base import EntityRef, _MissingItem
 from .exchange_ref import ExchangeRef
+from ..interfaces.iindex import comp_dir
 from itertools import chain
 
 
@@ -97,9 +98,9 @@ class ProcessRef(EntityRef):
                 return next(x for x in self.reference_entity if x.flow.match(flow))
             except StopIteration:
                 pass
-        print(self.link)
+        # print(self.link)
         # self._show_ref()
-        raise NoReference(flow)
+        raise NoReference(self.link, flow)
 
     def references(self):
         for x in self.reference_entity:
@@ -227,7 +228,8 @@ class ProcessRef(EntityRef):
 
     def consumers(self, ref_flow=None, **kwargs):
         ref_flow = self._use_ref_exch(ref_flow)
-        return self._query.consumers(self.external_ref, ref_flow=ref_flow, **kwargs)
+        return [self._to_exch_ref(x, value=None) for x in
+                self._query.consumers(self.external_ref, ref_flow=ref_flow, **kwargs)]
 
     def dependencies(self, ref_flow=None, **kwargs):
         ref_flow = self._use_ref_exch(ref_flow)

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0/src/antelope_interface.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: antelope_interface
-Version: 0.2.6.2
+Version: 0.3.0
 Summary: A common interface for accessing LCA data
 Author-email: Brandon Kuczenski <bkuczenski@ucsb.edu>
 License: BSD-3-Clause

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/src/antelope_interface.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ src/antelope/interfaces/iindex.py
 src/antelope/interfaces/iquantity.py
 src/antelope/models/__init__.py
 src/antelope/models/auth.py
+src/antelope/models/comparators.py
 src/antelope/refs/__init__.py
 src/antelope/refs/base.py
 src/antelope/refs/catalog_ref.py

{antelope_interface-0.2.6.2 → antelope_interface-0.3.0}/src/antelope/interfaces/iquantity.py

@@ -220,7 +220,6 @@ class QuantityInterface(AbstractQuery):
     '''
     core required functionality
     NOTE: a foreground interface must have access to a qdb to run get_canonical
-    '''
     def new_quantity(self, name, ref_unit=None, **kwargs):
         """
         Creates a new quantity entity and adds it to the foreground
@@ -245,6 +244,7 @@ class QuantityInterface(AbstractQuery):
                                    name, ref_quantity=ref_quantity, context=context,
                                    **kwargs)
 
+    '''
     '''
     qdb-only queries
     '''