antelope-interface 0.2.4__tar.gz → 0.2.6__tar.gz

{antelope_interface-0.2.4/src/antelope_interface.egg-info → antelope_interface-0.2.6}/PKG-INFO

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

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/pyproject.toml

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

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/setup.py

@@ -5,6 +5,12 @@ setup()
 
 """
 Version History:
+0.2.6 2024/05/29 - split_subfragment and fragments_with_flow into fg interface
+                   contrib_lcia is an exchange method
+                   un-resolved CatalogRefs can now return their replacement, if provided a query at instantiation 
+                   
+0.2.5 2024/05/06 - bg_lcia() becomes a basic interface route; sys_lcia() is the fully-featured background route
+
 0.2.4 2024/04/17 - split out BasicInterface from AbstractQuery. 
                    abandon setup.py except for this changelog.
                    Redesign ExteriorFlow to have maybe a little bit more logic

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/__init__.py

@@ -105,6 +105,10 @@ class LcQuery(BasicQuery, BackgroundInterface, ConfigureInterface):
     pass
 
 
+class FgQuery(LcQuery, ForegroundInterface):
+    pass
+
+
 '''
 Utilities
 

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/exchanges_from_spreadsheet.py

@@ -1,11 +1,15 @@
 """
 This module provides a routine that generates a list of exchange refs from a properly formatted spreadsheet
 """
+
 from .refs import CatalogRef, ExchangeRef
 from .interfaces import check_direction
 
 
 class ValueIsBalance(Exception):
+    """
+    Used to signal when an exchange is reached that is designated as a balance.
+    """
     pass
 
 
@@ -93,6 +97,7 @@ def exchanges_from_spreadsheet(sheetlike, term_dict=None, node=None, origin=None
      - row(0) returns a header list
      - row(1) is the process's reference flow
      - subsequent rows are dependent flows
+
      !TODO: support multiple references with is_ref or is_reference field
 
     "entries" in the row() return must be "cell-like":

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/interfaces/abstract_query.py

@@ -15,7 +15,8 @@ class PrivateArchive(Exception):
 
 
 class AbstractQuery(object):
-    """ Not-quite-abstract base class for executing queries
+    """
+    Not-quite-abstract base class for executing queries
 
     Query implementation must provide:
      - origin (property)

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/interfaces/ibackground.py

@@ -20,7 +20,6 @@ More plugins are yet imagined.
 
 from .abstract_query import AbstractQuery
 from ..refs import ExchangeRef
-from itertools import chain
 
 
 class BackgroundRequired(Exception):
@@ -136,7 +135,7 @@ class BackgroundInterface(AbstractQuery):
                                    process, ref_flow=ref_flow, **kwargs)
 
     def _make_sys_lci_exchange(self, x):
-        return ExchangeRef(self.get(x.process), self.make_ref(x.flow), x.direction, value=x.value,
+        return ExchangeRef(self.make_ref(x.process), self.make_ref(x.flow), x.direction, value=x.value,
                            termination=x.termination, comment='SYS LCI', is_reference=False)
 
     def sys_lci(self, demand, **kwargs):
@@ -160,7 +159,7 @@ class BackgroundInterface(AbstractQuery):
         for i in self._perform_query(_interface, 'sys_lci', BackgroundRequired, demand, **kwargs):
             yield self._make_sys_lci_exchange(i)
 
-    def bg_lcia(self, process, query_qty, observed=None, ref_flow=None, **kwargs):
+    def sys_lcia(self, process, query_qty, observed=None, ref_flow=None, **kwargs):
         """
 
         :param process:
@@ -170,7 +169,7 @@ class BackgroundInterface(AbstractQuery):
         :param kwargs:
         :return:
         """
-        return self._perform_query(_interface, 'bg_lcia', BackgroundRequired,
+        return self._perform_query(_interface, 'sys_lcia', BackgroundRequired,
                                    process, query_qty, observed=observed, ref_flow=ref_flow, **kwargs)
 
     '''

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/interfaces/ibasic.py

@@ -142,4 +142,17 @@ class BasicInterface(AbstractQuery):
         except TypeError:
             return False
 
+    def bg_lcia(self, process, query_qty=None, ref_flow=None, **kwargs):
+        """
+        Basic interface permits cumulative LCIA scores to be retrieved, but only if values=True
+
+        :param process:
+        :param query_qty: if omitted, a catalog may select a default LCIA method
+        :param ref_flow:
+        :param kwargs:
+        :return:
+        """
+        return self._perform_query('basic', 'bg_lcia', BasicRequired,
+                                   process, query_qty, ref_flow=ref_flow, **kwargs)
+
 

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/interfaces/iexchange.py

@@ -103,3 +103,17 @@ class ExchangeInterface(AbstractQuery):
         """
         return self._perform_query(_interface, 'exchange_relation', ExchangeRequired,
                                    process, ref_flow, exch_flow, direction, termination=termination, **kwargs)
+
+    def contrib_lcia(self, process, quantity=None, ref_flow=None, **kwargs):
+        """
+        exchange interface provides the ability to perform a contribution analysis of a process's LCIA scores.
+        In core, this is accomplished with ephemeral fragments.
+
+        :param process:
+        :param quantity: if omitted, a catalog may select a default LCIA method
+        :param ref_flow:
+        :param kwargs:
+        :return:
+        """
+        return self._perform_query(_interface, 'contrib_lcia', ExchangeRequired,
+                                   process, quantity, ref_flow, **kwargs)

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/interfaces/iforeground.py

@@ -95,6 +95,39 @@ class ForegroundInterface(AbstractQuery):
         """
         return self.make_ref(self._perform_query(_interface, 'child_flows', ForegroundRequired, fragment, **kwargs))
 
+    def fragments_with_flow(self, flow, direction=None,**kwargs):
+        """
+        Generates fragments made with the specified flow, optionally filtering by direction, reference status, and
+        background status.  For all three filters, the default None is to generate all fragments.
+        :param flow:
+        :param direction: [None | 'Input' | 'Output']
+        :param kwargs:
+        :return:
+        """
+        return self._perform_query(_interface, 'fragments_with_flow', ForegroundRequired,
+                                   flow, direction=direction, **kwargs)
+
+    def split_subfragment(self, fragment, replacement=None, **kwargs):
+        """
+                Given a non-reference fragment, split it off into a new reference fragment, and create a surrogate child
+        that terminates to it.
+
+        without replacement:
+        Old:   ...parent-->fragment
+        New:   ...parent-->surrogate#fragment;   (fragment)
+
+        with replacement:
+        Old:   ...parent-->fragment;  (replacement)
+        New:   ...parent-->surrogate#replacement;  (fragment);  (replacement)
+
+        :param fragment:
+        :param replacement:
+        :param kwargs:
+        :return:
+        """
+        return self._perform_query(_interface, 'split_subfragment', ForegroundRequired,
+                                   fragment, replacement=replacement, **kwargs)
+
     def anchors(self, fragment, **kwargs):
         """
         List observed anchors for a fragment

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/models/__init__.py

@@ -275,8 +275,8 @@ class DirectedFlow(ResponseModel):
         return self.flow.flowable
 
     @classmethod
-    def from_exchange(cls, obj):
-        return cls(flow=FlowSpec.from_exchange(obj), direction=obj.direction)
+    def from_observed(cls, obj):
+        return cls(flow=FlowSpec.from_flow(obj.flow), direction=obj.direction)
 
 
 class ExteriorFlow(DirectedFlow):
@@ -287,6 +287,10 @@ class ExteriorFlow(DirectedFlow):
     """
     context: List[str]
 
+    @property
+    def termination(self):
+        return self.context
+
     @classmethod
     def from_background(cls, flow, direction, context):
         if hasattr(context, 'entity_type'):
@@ -301,7 +305,7 @@ class ExteriorFlow(DirectedFlow):
         return cls(flow=FlowSpec.from_flow(flow), direction=direction, context=cx)
 
     @classmethod
-    def from_exchange(cls, obj):
+    def from_exterior(cls, obj):
         if obj.type == 'context':
             context = obj.termination.as_list()
         elif obj.type == 'cutoff':
@@ -313,7 +317,7 @@ class ExteriorFlow(DirectedFlow):
 
 class Exchange(ResponseModel):
     """
-    Do we need to add locale??
+    Do we need to add locale?? no it's in the flow entity
     """
     origin: str
     process: str
@@ -333,7 +337,8 @@ class Exchange(ResponseModel):
             term = x.termination
             cx = None
         return cls(origin=x.process.origin, process=x.process.external_ref, flow=FlowEntity.from_flow(x.flow),
-                   direction=x.direction, termination=term, context=cx, type=x.type, comment=x.comment, str=str(x), **kwargs)
+                   direction=x.direction, termination=term, context=cx, type=x.type, comment=x.comment, str=str(x),
+                   **kwargs)
 
 
 class ReferenceExchange(Exchange):
@@ -341,17 +346,18 @@ class ReferenceExchange(Exchange):
     termination: None
 
     @classmethod
-    def from_exchange(cls, x):
+    def from_exchange(cls, x, **kwargs):
         if x.termination is not None:
             cx = list(x.termination)
         else:
             cx = None
         return cls(origin=x.process.origin, process=x.process.external_ref, flow=FlowEntity.from_flow(x.flow),
-                   direction=x.direction, termination=None, context=cx, type=x.type, comment=x.comment, str=str(x))
+                   direction=x.direction, termination=None, context=cx, type=x.type, comment=x.comment, str=str(x),
+                   **kwargs)
 
 
 class ReferenceValue(ReferenceExchange):
-    value: float
+    value: float = 0.0
 
     @classmethod
     def from_rx(cls, x):
@@ -429,10 +435,11 @@ def generate_pydantic_inventory(xs, mode=None, values=False, ref_flow=None):
 
     :param xs: iterable of exchanges
     :param mode: [None] whether to filter the exchanges by type. could be one of:
-     None: generate all exchanges
-     'interior'
-     'exterior'
-     'cutoff'
+     - None: generate all exchanges
+     - 'interior'
+     - 'exterior'
+     - 'cutoff'
+
     :param values: (bool) [False] whether to include exchange values.
     :param ref_flow: (ignored if values=False) the reference flow with which the exchange value was computed. If None,
      this implies the exchange reports un-allocated exchange values
@@ -604,13 +611,13 @@ class SummaryLciaScore(AggregatedLciaScore):
 
 
 class LciaDetail(ResponseModel):
-    exchange: Optional[DirectedFlow]
+    exchange: Optional[ExteriorFlow]
     factor: QuantityConversion
     result: float
 
     @classmethod
     def from_detailed_lcia_result(cls, d):
-        return cls(exchange=DirectedFlow.from_exchange(d.exchange),
+        return cls(exchange=ExteriorFlow.from_exterior(d.exchange),
                    factor=QuantityConversion.from_qrresult(d.factor),
                    result=d.result)
 

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/refs/catalog_ref.py

@@ -3,7 +3,7 @@ The main import.
 """
 
 
-from .base import BaseRef
+from .base import BaseRef, InvalidQuery, NoCatalog
 from .flow_ref import FlowRef
 # from .fragment_ref import FragmentRef
 from .process_ref import ProcessRef
@@ -66,7 +66,7 @@ class CatalogRef(BaseRef):
                 return QuantityRef(external_ref, query, **kwargs)
         # elif etype == 'fragment':
         #     return FragmentRef(external_ref, query, reference_entity, **kwargs)
-        return cls(query.origin, external_ref, entity_type=etype, **kwargs)
+        return cls(query.origin, external_ref, entity_type=etype, query=query, **kwargs)
 
     def __init__(self, origin, external_ref, entity_type=None, reference_entity=None, **kwargs):
         """
@@ -78,7 +78,7 @@ class CatalogRef(BaseRef):
         """
         super(CatalogRef, self).__init__(origin, external_ref, **kwargs)
 
-        if 'Name' not in kwargs:
+        if 'Name' not in self._d:
             self['Name'] = self.link
 
         self._asgn_etype = entity_type
@@ -143,3 +143,12 @@ class CatalogRef(BaseRef):
 
     def cf(self, *args, **kwargs):
         return 0.0
+
+    def resolve(self):
+        if self.has_property('query'):
+            try:
+                return self['query'].get(self.external_ref)
+            except InvalidQuery:
+                return self
+        else:
+            raise NoCatalog(self.origin)

{antelope_interface-0.2.4 → antelope_interface-0.2.6}/src/antelope/refs/process_ref.py

@@ -306,6 +306,10 @@ class ProcessRef(EntityRef):
             for i in lci:
                 yield self._to_exch_ref(i, i.value)
 
+    def contrib_lcia(self, quantity=None, ref_flow=None, **kwargs):
+        ref_flow = self._use_ref_exch(ref_flow)
+        return self._query.contrib_lcia(self.external_ref, quantity, ref_flow=ref_flow, **kwargs)
+
     def bg_lcia(self, lcia_qty, observed=None, ref_flow=None, **kwargs):
         """
         :param lcia_qty: should be a quantity ref (or qty), not an external ID
@@ -315,4 +319,7 @@ class ProcessRef(EntityRef):
         :return:
         """
         ref_flow = self._use_ref_exch(ref_flow)
-        return self._query.bg_lcia(self.external_ref, lcia_qty, observed=observed, ref_flow=ref_flow, **kwargs)
+        if observed:
+            return self._query.sys_lcia(self.external_ref, lcia_qty, observed=observed, ref_flow=ref_flow, **kwargs)
+        else:
+            return self._query.bg_lcia(self.external_ref, lcia_qty, ref_flow=ref_flow, **kwargs)

{antelope_interface-0.2.4 → antelope_interface-0.2.6/src/antelope_interface.egg-info}/PKG-INFO

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