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

antelope_interface-0.2.4/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.1
+Name: antelope_interface
+Version: 0.2.4
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: synonym_dict>=0.2.4
+Requires-Dist: pydantic>=2.5.0
+
+# antelope
+Standard Interface and reference framework for LCA
+
+The `antelope` package is an interface specification for accessing LCA data resources. 
+The goal of the Antelope project is to reduce the complexity of LCA along three central 
+fronts:
+
+ 1. Reduce complexity of *modeling* by providing a simple, recursive data structure (the
+fragment) that can effectively describe complex, dynamic LCA models;
+ 2. Reduce complexity of *software* by liberating users from costly and cumbersome desktop
+LCA software applications and relocating reference data to the cloud, without compromising
+computational sophistication;
+ 3. Reduce complexity of *communication* by providing online tools for describing and sharing
+LCA models that conceal or omit confidential and proprietary information.
+
+
+## Principles
+
+The Antelope framework is *distributed by design*, intended to allow data owners to independently
+create and manage their own intellectual property, allowing access by others while regulating
+what can be seen and concealed.
+
+Antelope provides a *hosting platform* for working online and sharing information within a
+trust network.  User-owned data is managed by owners, while reference data is curated by
+the user community.
+
+Antelope uses *separation of concerns* to help organize different computational facets of
+the LCA problem into separate services. 
+
+## Documentation
+
+Coming to github.io
+
+### See Also
+
+ * [vault.lc](https://vault.lc/) Home to the Antelope authentication service
+ * [antelope_core](https://github.com/AntelopeLCA/core) The reference implementation including local data source management.
+ * [antelope_background](https://github.com/AntelopeLCA/background) Used for partial ordering of databases and construction and inversion of matrices
+ * [antelope_foreground](https://github.com/AntelopeLCA/foreground) Used for building foreground models

antelope_interface-0.2.4/README.md

@@ -0,0 +1,39 @@
+# antelope
+Standard Interface and reference framework for LCA
+
+The `antelope` package is an interface specification for accessing LCA data resources. 
+The goal of the Antelope project is to reduce the complexity of LCA along three central 
+fronts:
+
+ 1. Reduce complexity of *modeling* by providing a simple, recursive data structure (the
+fragment) that can effectively describe complex, dynamic LCA models;
+ 2. Reduce complexity of *software* by liberating users from costly and cumbersome desktop
+LCA software applications and relocating reference data to the cloud, without compromising
+computational sophistication;
+ 3. Reduce complexity of *communication* by providing online tools for describing and sharing
+LCA models that conceal or omit confidential and proprietary information.
+
+
+## Principles
+
+The Antelope framework is *distributed by design*, intended to allow data owners to independently
+create and manage their own intellectual property, allowing access by others while regulating
+what can be seen and concealed.
+
+Antelope provides a *hosting platform* for working online and sharing information within a
+trust network.  User-owned data is managed by owners, while reference data is curated by
+the user community.
+
+Antelope uses *separation of concerns* to help organize different computational facets of
+the LCA problem into separate services. 
+
+## Documentation
+
+Coming to github.io
+
+### See Also
+
+ * [vault.lc](https://vault.lc/) Home to the Antelope authentication service
+ * [antelope_core](https://github.com/AntelopeLCA/core) The reference implementation including local data source management.
+ * [antelope_background](https://github.com/AntelopeLCA/background) Used for partial ordering of databases and construction and inversion of matrices
+ * [antelope_foreground](https://github.com/AntelopeLCA/foreground) Used for building foreground models

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

@@ -21,8 +21,8 @@ classifiers = [
         "Programming Language :: Python :: 3",
         "Topic :: Scientific/Engineering"
 ]
-dependencies = ["synonym_dict", "pydantic"]
-version = "0.2.3.2"
+dependencies = ["synonym_dict >= 0.2.4", "pydantic >= 2.5.0"]
+version = "0.2.4"
 
 [tool.setuptools.packages.find]
 where = ["src"]

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

@@ -1,14 +1,15 @@
-from setuptools import setup, find_packages
+from setuptools import setup
 
-ANTELOPE_VERSION = '0.2.3.2'
+setup()
 
-requires = [
-    "synonym_dict>=0.2.4",
-    "pydantic>=2.5.0"
-]
 
 """
 Version History:
+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
+                   First pass at API documentation
+
 0.2.3.2 2024/03/26 move to src layout
 
 0.2.3.1 2024/03/22 LciaDetail objects now return DirectedFlow instead of FlowSpec (as exchange proxy)
@@ -55,28 +56,3 @@ Version History:
                    
 0.1.0 2020/07/31 - Initial release - JIE paper 
 """
-
-setup(
-    name="antelope_interface",
-    version=ANTELOPE_VERSION,
-    author="Brandon Kuczenski",
-    author_email="bkuczenski@ucsb.edu",
-    license="BSD 3-Clause",
-    install_requires=requires,
-    url="https://github.com/AntelopeLCA/antelope",
-    summary="An interface specification for accessing LCA data",
-    long_description_content_type='text/markdown',
-    long_description=open('README.md').read(),
-    include_package_data=True,
-    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"
-    ],
-    python_requires='>=3.6',
-    packages=find_packages('src')
-)

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

@@ -5,8 +5,9 @@ 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.abstract_query import PrivateArchive, EntityNotFound, NoAccessToEntity
+from .interfaces import ANTELOPE_INTERFACES
 
+from .interfaces.ibasic import BasicInterface, EntityNotFound, NoAccessToEntity
 from .interfaces.iconfigure import ConfigureInterface
 from .interfaces.iexchange import ExchangeInterface, ExchangeRequired
 from .interfaces.iindex import IndexInterface, IndexRequired, directions, comp_dir, num_dir, check_direction, valid_sense, comp_sense
@@ -28,8 +29,6 @@ import re
 
 from os.path import splitext
 
-from collections import namedtuple
-
 
 class ValuesAccessRequired(Exception):
     """
@@ -50,14 +49,14 @@ Query classes
 '''
 
 
-class BasicQuery(IndexInterface, ExchangeInterface, QuantityInterface):
+class BasicQuery(BasicInterface, IndexInterface, ExchangeInterface, QuantityInterface):
     """
-    A basic query depends on an archive-- which is not yet well-defined, but which has the following API:
-    archive.make_interface(interface): returns an implementation of the designated interface
-    archive.ref: returns the archive's semantic reference
-    archive.source: returns the physical source for the archive's content
+    A basic query depends on an archive-- which has the following API:
+
+     - archive.make_interface(interface): returns an implementation of the designated interface
+     - archive.ref: returns the archive's semantic reference
+     - archive.source: returns the physical source (or URI) for the archive's content
 
-    Note that an alternative abstract query implementation could be imagined
     """
     def __init__(self, archive, debug=False):
         self._archive = archive
@@ -153,9 +152,10 @@ def q_node_activity(fg):
 
 def enum(iterable, filt=None, invert=True):
     """
-    Enumerate an iterable for interactive use. return it as a list. Optional negative filter supplied as regex
+    Enumerate an iterable for interactive use. return it as a list. Optional negative filter supplied as regex.
+
     :param iterable:
-    :param filt:
+    :param filt: regex to filter out entries from return and enumeration.
     :param invert: [True] sense of filter. note default is negative i.e. to screen *out* matches
      (the thinking is that the input is already positive-filtered)
     :return:
@@ -173,10 +173,10 @@ def enum(iterable, filt=None, invert=True):
         ret.append(v)
     return ret
 
+
 """
-In most LCA software, including the current operational version of lca-tools, a 'flow' is a composite entity
-that is made up of a 'flowable' (substance, product, intervention, or service) and a 'context', which is 
-synonymous with an environmental compartment.
+In most LCA software, a 'flow' is a composite entity that is made up of a 'flowable' (substance, product, 
+intervention, or service) and a 'context', which is synonymous with an environmental compartment.
 
 The US EPA review of elementary flows recommended managing the names of flowables and contexts separately, and that
 is the approach that is done here.  
@@ -196,9 +196,9 @@ CONTEXT_STATUS_ = 'new'  # 'compat': context = flow['Compartment']; 'new': conte
 
 # Exterior exchanges- with contexts outside the db.  Direction is given with respect to the Interior (e.g. "Output" "to air")
 # LciaResults should negate values when an exchange direction and a context are not complementary (i.e. "Input" "to air")
-ExteriorFlow = namedtuple('ExteriorFlow', ('origin', 'flow', 'direction', 'termination'))
+# ExteriorFlow = namedtuple('ExteriorFlow', ('origin', 'flow', 'direction', 'termination'))
 
-EntitySpec = namedtuple('EntitySpec', ('link', 'ref', 'name', 'group'))
+# EntitySpec = namedtuple('EntitySpec', ('link', 'ref', 'name', 'group'))
 
 # packages that contain 'providers'
 antelope_herd = [

{antelope_interface-0.2.3.2 → antelope_interface-0.2.4}/src/antelope/flows/flow.py

@@ -5,6 +5,8 @@ import os
 import re
 import json
 
+from abc import ABC
+
 from synonym_dict import SynonymSet
 from synonym_dict.flowables.cas_number import CasNumber, InvalidCasNumber
 
@@ -36,14 +38,16 @@ with open(os.path.join(os.path.dirname(__file__), 'openlca_locales.json')) as fp
     olca_locales = json.load(fp)
 
 
-class Flow(FlowInterface):
+class Flow(FlowInterface, ABC):
     """
     A partly-abstract class that implements the flow specification but not the entity specification.
 
     Included in this specification is a *detection of biogenic CO2 by regex*
     Each flow has a quell_co2 property which is True if:
+
      - the flow is a synonym for CO2 and
      - the flow's name matches the biogenic regex: '(biotic|biogenic|non-fossil|in air)' (case insensitive)
+
     There are 3 ways for a flow to be identified as a synonym for CO2:
      1. pass is_co2=True at instantiation
      2. set flow.is_co2 = True

{antelope_interface-0.2.3.2 → antelope_interface-0.2.4}/src/antelope/flows/flow_interface.py

@@ -1,3 +1,6 @@
+from abc import ABC
+
+
 class BaseEntity(object):
     """
     The very most basic characteristics of entities and entity refs
@@ -81,7 +84,7 @@ class NullEntity(BaseEntity):
         return NotImplemented
 
 
-class FlowInterface(BaseEntity):
+class FlowInterface(BaseEntity, ABC):
     """
     An abstract class that establishes common functionality for OBSERVATIONS OF FLOWS.  A Flow consists of:
      - a reference quantity with a fixed unit
@@ -138,8 +141,8 @@ class FlowInterface(BaseEntity):
 
     def lookup_cf(self, quantity, context, locale, refresh=False, **kwargs):
         """
-        Look for cached characterizations, and retrieve if none is found
-        :param quantity:
+        Look for cached characterizations, and retrieve one from the provided quantity if none is found.
+        :param quantity: a QuantityRef
         :param context:
         :param locale:
         :param refresh: [False] if True, discard cached CF

antelope_interface-0.2.4/src/antelope/interfaces/__init__.py

@@ -0,0 +1,3 @@
+from .abstract_query import ANTELOPE_INTERFACES
+from .ibasic import EntityNotFound, NoAccessToEntity
+from .iindex import check_direction, InvalidDirection, InvalidSense

antelope_interface-0.2.4/src/antelope/interfaces/abstract_query.py

@@ -0,0 +1,61 @@
+"""
+Root-level catalog interface
+"""
+
+
+#: The interfaces that exist in the Antelope framework
+ANTELOPE_INTERFACES = ('basic', 'exchange', 'index', 'quantity', 'background', 'configure', 'foreground')
+
+
+class PrivateArchive(Exception):
+    """
+    :meta exclude:
+    """
+    pass
+
+
+class AbstractQuery(object):
+    """ Not-quite-abstract base class for executing queries
+
+    Query implementation must provide:
+     - origin (property)
+     - _iface (generator: itype)
+     - _tm (property) a TermManager
+    """
+    _validated = None
+
+    '''
+    Overridde these methods
+    '''
+    @property
+    def origin(self):
+        return NotImplemented
+
+    def make_ref(self, entity):
+        raise NotImplementedError
+
+    def _perform_query(self, itype, attrname, exc, *args, **kwargs):
+        """
+        The workhorse of the abstract query.  The implementation uses this to perform whatever query is requested.
+
+        :param itype: type of query being performed (which interface is being invoked). Must be in ANTELOPE_INTERFACES
+        :param attrname: query name
+        :param exc: "fallback exception": ignore it if an implementation raises it; then raise it if no implementation
+         succeeds
+        :param args: to pass to the query
+        :param kwargs: to pass to the query or subclass
+        :return:
+        """
+        raise NotImplementedError
+
+    def _grounded_query(self, origin):
+        """
+        Pseudo-abstract method used to construct entity references from a query that is anchored to a metaresource.
+        must be overriden by user-facing subclasses if resources beyond self are required to answer
+        the queries (e.g. a catalog).
+        Can be overridden.
+
+        :param origin:
+        :return:
+        """
+        return self

antelope_interface-0.2.3.2/src/antelope/interfaces/abstract_query.py → antelope_interface-0.2.4/src/antelope/interfaces/ibasic.py

@@ -1,17 +1,25 @@
-"""
-Root-level catalog interface
-"""
+from .abstract_query import AbstractQuery
 
 
-class ValidationError(Exception):
+class BasicRequired(Exception):
+    """
+    Default exception to indicate that the requested method cannot be invoked without an implementation of the
+    basic interface (and none could be found).
+    """
     pass
 
 
-class PrivateArchive(Exception):
+class ValidationError(Exception):
+    """
+    :meta private:
+    """
     pass
 
 
 class EntityNotFound(Exception):
+    """
+    An exception of generic usefulness.
+    """
     pass
 
 
@@ -22,56 +30,15 @@ class NoAccessToEntity(Exception):
     pass
 
 
-class AbstractQuery(object):
+class BasicInterface(AbstractQuery):
     """
-    Not-quite-abstract base class for executing queries
+    BasicInterface core methods.
 
-    Query implementation must provide:
-     - origin (property)
-     - _iface (generator: itype)
-     - _tm (property) a TermManager
-    """
-    _validated = None
-
-    '''
-    Overridde these methods
-    '''
-    @property
-    def origin(self):
-        return NotImplemented
+    These are methods for retrieving objects and accessing documentary information about them. The basic interface
+    should provide access to the most authoritative source of information about a data resource.
 
-    def make_ref(self, entity):
-        raise NotImplementedError
-
-    def _perform_query(self, itype, attrname, exc, *args, **kwargs):
-        """
-
-        :param itype: type of query being performed (which interface is being invoked)
-        :param attrname: query name
-        :param exc: "fallback exception": ignore it if an implementation raises it; then raise it if no implementation
-         succeeds
-        :param args: to pass to the query
-        :param kwargs: to pass to the query or subclass
-        :return:
-        """
-        raise NotImplementedError
-
-    '''
-    Internal workings
-    '''
-    '''
-    Can be overridden
-    '''
-    def _grounded_query(self, origin):
-        """
-        Pseudo-abstract method used to construct entity references from a query that is anchored to a metaresource.
-        must be overriden by user-facing subclasses if resources beyond self are required to answer
-        the queries (e.g. a catalog).
-        :param origin:
-        :return:
-        """
-        return self
 
+    """
     """
     Basic "Documentary" interface implementation
     From JIE submitted:
@@ -86,6 +53,13 @@ class AbstractQuery(object):
     """
 
     def validate(self):
+        """
+        This method should return `True` whenever the implementation is attached to a valid data source that is
+        capable of answering questions.  The existence of a basic implementation is necessary and sufficient for a
+        query to be valid.
+
+        :return: bool
+        """
         if self._validated is None:
             try:
                 self._perform_query('basic', 'validate', ValidationError)
@@ -115,17 +89,12 @@ class AbstractQuery(object):
 
     def get_item(self, external_ref, item):
         """
-        access an entity's dictionary items
-        :param external_ref:
-        :param item:
+        access an entity's properties.  This requires de-referencing the query to the true entity.  This method
+        is used to access essentially all documentary information about an object.
+        :param external_ref: the entity's identifier
+        :param item: the desired property
         :return:
         """
-        '''
-        if hasattr(external_ref, 'external_ref'):  # debounce
-            err_str = external_ref.external_ref
-        else:
-            err_str = external_ref
-        '''
         return self._perform_query('basic', 'get_item', EntityNotFound,
                                    external_ref, item)
 
@@ -148,19 +117,24 @@ class AbstractQuery(object):
 
     def is_lcia_engine(self, **kwargs):
         """
-        A key question in the quantity interface is the way terms are managed.  There are two main footings:
-         - the terms specified by the source are authentic / canonical and should be reproduced
-         - terms from different data sources refer to the same concept.
+        A key question in the quantity interface is the way terms are managed.
         An archive's Term Manager determines how input terms are interpreted and how characterizations are looked up.
+        There are two main footings:
+
+         - the terms specified by the source are authentic / canonical and should be reproduced
+         - terms from different data sources refer to the same concept, and the *concept* should be returned.
+
+        A *provincial* term manager considers the local archive (to which it is attached) to be the source of all
+        truth. It will return flowables and contexts exactly as they are defined in the native data source.  In
+        this case, `is_lcia_engine()` returns `False`.
 
         if the term manager is an LciaEngine, it uses a standard set of contexts and flowables, and provides routes
         to add new synonyms for flowables/contexts and to report new flowables or contexts.  Ultimately the objective
-        is to manage characterization + knowledge of intermediate flows.
-
-        This routine reports whether an origin implements the LciaEngine [protocol?] for dealing with flows.
+        is to manage characterization + knowledge of both elementary and intermediate flows.
+        In this case, `is_lcia_engine()` returns `True`.
 
         :param kwargs:
-        :return: True/False - could also provide more structured information as needed.
+        :return: bool
         """
 
         try:
@@ -168,3 +142,4 @@ class AbstractQuery(object):
         except TypeError:
             return False
 
+

{antelope_interface-0.2.3.2 → antelope_interface-0.2.4}/src/antelope/interfaces/iconfigure.py

@@ -81,7 +81,8 @@ class ConfigureInterface(AbstractQuery):
     def characterize_flow(self, flow_ref, quantity_ref, value, location='GLO', **kwargs):
         """
         Add a characterization to the given flow in the given quantity, with respect to the flow's native reference
-         quantity.  Optional location field.
+        quantity.  Optional location field.
+
         :param flow_ref:
         :param quantity_ref:
         :param value:

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

@@ -13,19 +13,10 @@ EXCHANGE_VALUES_REQUIRED = {'ev', 'exchange_values', 'inventory', 'exchange_rela
 
 class ExchangeInterface(AbstractQuery):
     """
-    InventoryInterface core methods: individual processes, quantitative data.
-
-    Need to do some thinking here-- the list of methods is very short. In particular there is no way to do any of
-    the following:
-     * retrieve reference exchanges
-     * retrieve cutoff exchanges or only terminated exchanges
-     * retrieve only intermediate or only elementary exchanges [[ pending context refactor :(:( ]]
-       = this is frankly not possible to do, even after the context refactor, because there is no bulletproof way to
-         determine whether a termination is a context or a process or some non-elementary compartment, until you
-         introduce the Lcia Engine with its reference set of contexts, UNLESS you include the reference elementary set
-         in ALL context managers.  Which is feasible- since it's a short list- but still, not done as yet.
-    There's also no access to information from the original source that is not part of the data model, e.g. uncertainty
-    information, arbitrary XML queries, etc.
+    The Exchange Interface implements the Exchange Relation:
+     - given a process, a reference flow, and a query flow, report the quantity of the query flow that is exchanged
+       with respect to a unit of the reference flow.
+
     """
     def exchanges(self, process, **kwargs):
         """
@@ -39,6 +30,7 @@ class ExchangeInterface(AbstractQuery):
     def ev(self, process, flow, direction=None, termination=None, ref_flow=None, **kwargs):
         """
         Return a float.  Symmetric to quantity.cf
+
         :param process:
         :param flow:
         :param direction: [None] if none, if flows exist with both directions, raise an error
@@ -57,7 +49,8 @@ class ExchangeInterface(AbstractQuery):
         2022-12-27: is this really deprecated? it's used in computing reference_value and I don't see any other way...
         perhaps we should add reference_value() to the API but for now let's keep this around
 
-        Return a list of exchanges with values matching the specification
+        Return a list of exchanges with values matching the specification.
+
         :param process:
         :param flow:
         :param direction: [None] if none,
@@ -77,17 +70,18 @@ class ExchangeInterface(AbstractQuery):
 
         If a reference flow is supplied, expected behavior depends on a number of factors.
          - If the supplied reference flow is part of the process's reference entity, the inventory should return all
-         non-reference exchanges, appropriately allocated to the specified flow, and normalized to a unit of the
-         specified flow.
+           non-reference exchanges, appropriately allocated to the specified flow, and normalized to a unit of the
+           specified flow.
          - If the supplied reference flow is not part of the reference entity, NO allocation should be performed.
-         Instead, the inventory should return ALL exchanges except for the specified flow, un-allocated, normalized to
-         a unit of the specified flow.  This query is only valid if the specified flow is a cut-off (i.e. un-terminated)
-         exchange (i.e. it could be treated as a "silent reference" or effective co-product)
+           Instead, the inventory should return ALL exchanges except for the specified flow, un-allocated, normalized to
+           a unit of the specified flow.  This query is only valid if the specified flow is a cut-off (i.e. un-terminated)
+           exchange (i.e. it could be treated as a "silent reference" or effective co-product)
          - If the supplied reference flow is a non-reference, non-cutoff flow (i.e. it is a terminated exchange), then
-         the appropriate behavior is undefined. The default implementation raises an ExchangeError.
+           the appropriate behavior is undefined. The default implementation raises an ExchangeError.
 
         Note: if this is called on a fragment, the signature is the same but the 'ref_flow' argument is ignored and
         the alternative 'scenario' kwarg is accepted
+
         :param process:
         :param ref_flow: used only for processes
         :param scenario: used only for fragments (antelope_foreground)

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

@@ -80,7 +80,7 @@ class ForegroundInterface(AbstractQuery):
 
         :param flow: a flow entity/ref, or an external_ref known to the foreground
         :param direction:
-        :param kwargs: uuid=None, parent=None, comment=None, value=None, balance=False; **kwargs passed to LcFragment
+        :param kwargs: uuid=None, parent=None, comment=None, value=None, balance=False; kwargs passed to LcFragment
         :return: the fragment? or a fragment ref? <== should only be used in the event of a non-local foreground
         """
         return self._perform_query(_interface, 'new_fragment', ForegroundRequired,

{antelope_interface-0.2.3.2 → antelope_interface-0.2.4}/src/antelope/interfaces/iquantity.py

@@ -178,6 +178,7 @@ class QuantityInterface(AbstractQuery):
            (hence the basic interface)
          - either the quantity ref must be known locally or resolvable to a do_lcia operation by the catalog
          - there is also the implied need for sys_lcia which is a POST operation that uses sys_lci
+
         It needs to be rewritten.
 
         :param process:

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

@@ -72,7 +72,15 @@ class Entity(EntityRef):
         return self.entity_id
 
     @classmethod
-    def from_entity(cls, entity, **kwargs):
+    def from_search(cls, entity):
+        ent = cls(origin=entity.origin, entity_id=entity.external_ref, entity_type=entity.entity_type,
+                  properties=dict())
+        for k in entity.signature_fields():
+            ent.properties[k] = entity[k]
+        return ent
+
+    @classmethod
+    def from_entity(cls, entity):
         ent = cls(origin=entity.origin, entity_id=entity.external_ref, entity_type=entity.entity_type,
                   properties=dict())
         # ent.properties.update(kwargs)  # I don't know why this was here but I don't think I want it
@@ -162,6 +170,7 @@ class FlowEntity(Entity):
 
         obj.properties['name'] = entity.name
         obj.properties[entity.reference_field] = entity.reference_entity.external_ref
+        obj.properties['unit'] = entity.unit
         obj.properties['Synonyms'] = []
 
         for key, val in kwargs.items():
@@ -245,20 +254,6 @@ class FlowSpec(ResponseModel):
                    context=cx, locale=loc)
 
 
-class ExteriorFlow(ResponseModel):
-    """
-    Do we really need both an ExteriorFlow model and a FlowSpec model? this one has direction, and origin+flow;
-    that one has flowable+ref entity, and locale (but we added locale)
-
-    This is currently unused, but that's because we haven't implemented the {origin}/exterior route yet
-    """
-    origin: str
-    flow: str
-    direction: str  # antelope_interface specifies the direction as w/r/t/ context, as in "Input" "to air". This SEEMS WRONG.
-    context: List[str]
-    locale: Optional[str] = 'GLO'  # ???
-
-
 class DirectedFlow(ResponseModel):
     flow: FlowSpec
     direction: str
@@ -284,6 +279,38 @@ class DirectedFlow(ResponseModel):
         return cls(flow=FlowSpec.from_exchange(obj), direction=obj.direction)
 
 
+class ExteriorFlow(DirectedFlow):
+    """
+    An ExteriorFlow is essentially a row in the LCI Environment `B` matrix. It consists of a directed flow,
+    enhanced with a context. Now I know a flow already has a context, but (a) context is not required for a flow and
+    (b) flows can be terminated to contexts other than their 'default'
+    """
+    context: List[str]
+
+    @classmethod
+    def from_background(cls, flow, direction, context):
+        if hasattr(context, 'entity_type'):
+            if context.entity_type == 'context':
+                cx = context.as_list()
+            else:
+                raise TypeError('supplied Context %s (type %s)' % (context, context.entity_type))
+        elif context is None:
+            cx = []
+        else:
+            cx = list(context)
+        return cls(flow=FlowSpec.from_flow(flow), direction=direction, context=cx)
+
+    @classmethod
+    def from_exchange(cls, obj):
+        if obj.type == 'context':
+            context = obj.termination.as_list()
+        elif obj.type == 'cutoff':
+            context = []
+        else:
+            raise TypeError('exchange is not exterior (type %s)' % obj.type)
+        return cls(flow=FlowSpec.from_exchange(obj), direction=obj.direction, context=context)
+
+
 class Exchange(ResponseModel):
     """
     Do we need to add locale??
@@ -313,6 +340,15 @@ class ReferenceExchange(Exchange):
     is_reference: bool = True
     termination: None
 
+    @classmethod
+    def from_exchange(cls, x):
+        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))
+
 
 class ReferenceValue(ReferenceExchange):
     value: float
@@ -583,6 +619,7 @@ class DisaggregatedLciaScore(AggregatedLciaScore):
     details: List[LciaDetail] = []
 
     '''
+    :meta exclude:
     @classmethod
     def from_component(cls, obj, c):
         if hasattr(c.entity, 'name'):

{antelope_interface-0.2.3.2 → antelope_interface-0.2.4}/src/antelope/refs/base.py

@@ -33,7 +33,7 @@ The CatalogRef can instantiate a grounded reference if supplied with a query obj
 from synonym_dict import LowerDict
 
 from ..flows import BaseEntity
-from ..interfaces.abstract_query import NoAccessToEntity, EntityNotFound
+from ..interfaces import NoAccessToEntity, EntityNotFound
 
 import re
 
@@ -390,8 +390,8 @@ class EntityRef(BaseRef):
            -- which causes recursion error if the query actually gets the entity_ref
            --- attempted solution with NoAccessToEntity exception in BasicImplementation
          - fine. So when do we raise a key error?
+
         :param item:
-        :param force_query:
         :return:
         """
         if item == self._ref_field:

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

@@ -1,4 +1,4 @@
-from .base import EntityRef
+from .base import EntityRef, _MissingItem
 from .exchange_ref import ExchangeRef
 from itertools import chain
 
@@ -21,6 +21,11 @@ class ProcessRef(EntityRef):
     _etype = 'process'
     _ref_field = 'referenceExchange'
 
+    def signature_fields(self):
+        for k in ('Name', 'Comment', 'SpatialScope', 'TemporalScope'):
+            if self._d[k] is not _MissingItem:
+                yield k
+
     @property
     def _addl(self):
         return self.get('SpatialScope', default='')

{antelope_interface-0.2.3.2 → antelope_interface-0.2.4}/src/antelope/refs/quantity_ref.py

@@ -201,30 +201,38 @@ class QuantityRef(EntityRef):
         """
         Enter a characterization factor for the current object (query quantity) w.r.t. the specified reference quantity.
         The characterization value should report the amount of the query quantity (quantity being characterized) that
-         equals a unit of the reference quantity (used to measure the flow). The following is correct,
-         for mass in kg and volume in m3:
+        equals a unit of the reference quantity (used to measure the flow). The following is correct,
+        for mass in kg and volume in m3:
+
         >>> mass.characterize('water', 'volume', 1000.0)
-        "I {characterize} the [mass] of [water] in a unit [volume] to be 1000.0".  The thing being measured is mass.
+        "I {characterize} the [mass] of [water] in a unit [volume] to be 1000.0".
+
+        The thing being measured is mass.
         The flow's reference quantity is volume. a unit reference quantity of water is characterized as 1000.0 kg.
 
         The following is NOT correct, but it may SEEM more semantically natural:
+
         >>> mass.characterize('water', 'volume', 0.001)
         "I {characterize} the unit [mass] of [water] to have a [volume] of 0.001"
+
         The unit of the flow is measured in terms of the query quantity.  But we don't yet know the size of a unit
         of the query quantity because that is what is in fact being characterized.
 
         To see this borne out, imagine using characterize() in its most natural way, for LCIA:
+
         >>> gwp.characterize('methane', 'mass', 25)
         "I characterize the GWP of methane in a unit mass to be 25" <<--- CORRECT
         {I characterize the unit GWP of methane to have a mass of 0.04} <<--- plainly wrong
 
-        REALLY, the MOST natural way to characterize is as follows (see FlowRef.characterize()):
+        REALLY, the MOST natural way to characterize is to use `FlowRef.characterize()`:
+
         >>> m = q.get('methane')
         >>> m.unit
         'kg'
         >>> m.characterize(gwp, 25, context='to air')
 
         generations may determine whether this was a terrible mistake.
+
         :param flowable:
         :param ref_quantity:
         :param value:

antelope_interface-0.2.4/src/antelope_interface.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.1
+Name: antelope_interface
+Version: 0.2.4
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: synonym_dict>=0.2.4
+Requires-Dist: pydantic>=2.5.0
+
+# antelope
+Standard Interface and reference framework for LCA
+
+The `antelope` package is an interface specification for accessing LCA data resources. 
+The goal of the Antelope project is to reduce the complexity of LCA along three central 
+fronts:
+
+ 1. Reduce complexity of *modeling* by providing a simple, recursive data structure (the
+fragment) that can effectively describe complex, dynamic LCA models;
+ 2. Reduce complexity of *software* by liberating users from costly and cumbersome desktop
+LCA software applications and relocating reference data to the cloud, without compromising
+computational sophistication;
+ 3. Reduce complexity of *communication* by providing online tools for describing and sharing
+LCA models that conceal or omit confidential and proprietary information.
+
+
+## Principles
+
+The Antelope framework is *distributed by design*, intended to allow data owners to independently
+create and manage their own intellectual property, allowing access by others while regulating
+what can be seen and concealed.
+
+Antelope provides a *hosting platform* for working online and sharing information within a
+trust network.  User-owned data is managed by owners, while reference data is curated by
+the user community.
+
+Antelope uses *separation of concerns* to help organize different computational facets of
+the LCA problem into separate services. 
+
+## Documentation
+
+Coming to github.io
+
+### See Also
+
+ * [vault.lc](https://vault.lc/) Home to the Antelope authentication service
+ * [antelope_core](https://github.com/AntelopeLCA/core) The reference implementation including local data source management.
+ * [antelope_background](https://github.com/AntelopeLCA/background) Used for partial ordering of databases and construction and inversion of matrices
+ * [antelope_foreground](https://github.com/AntelopeLCA/foreground) Used for building foreground models

{antelope_interface-0.2.3.2 → antelope_interface-0.2.4}/src/antelope_interface.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ src/antelope/flows/openlca_locales.json
 src/antelope/interfaces/__init__.py
 src/antelope/interfaces/abstract_query.py
 src/antelope/interfaces/ibackground.py
+src/antelope/interfaces/ibasic.py
 src/antelope/interfaces/iconfigure.py
 src/antelope/interfaces/iexchange.py
 src/antelope/interfaces/iforeground.py

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

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

antelope_interface-0.2.3.2/PKG-INFO

@@ -1,40 +0,0 @@
-Metadata-Version: 2.1
-Name: antelope_interface
-Version: 0.2.3.2
-Summary: A common interface for accessing LCA data
-Home-page: https://github.com/AntelopeLCA/antelope
-Author: Brandon Kuczenski
-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
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: synonym_dict
-Requires-Dist: pydantic
-
-# antelope
-Standard Interface and reference framework for LCA
-
-The `antelope` package is an interface specification for accessing LCA data resources, as described in [JIE submitted].  It should be subclassed by implementations that wish to expose data using this uniform interface.  A reference implementation, including a stand-alone LCA computing tool, exists...
-
-## Documentation
-
-See the following articles:
-
- * [Antelope Design Principles](principles.md) for documentation of this repository.
- * [Entity Specification](entities.md) and nomenclature.
- * [Return Types](types.md) which are *references* to entities.
-
-### See Also
-
- * [antelope_core](https://github.com/AntelopeLCA/core) The reference implementation including local data source management.
- * [antelope_background](https://github.com/AntelopeLCA/background) Used for partial ordering of databases and construction and inversion of matrices
- * [antelope_foreground](https://github.com/AntelopeLCA/foreground) Used for building foreground models

antelope_interface-0.2.3.2/README.md

@@ -1,18 +0,0 @@
-# antelope
-Standard Interface and reference framework for LCA
-
-The `antelope` package is an interface specification for accessing LCA data resources, as described in [JIE submitted].  It should be subclassed by implementations that wish to expose data using this uniform interface.  A reference implementation, including a stand-alone LCA computing tool, exists...
-
-## Documentation
-
-See the following articles:
-
- * [Antelope Design Principles](principles.md) for documentation of this repository.
- * [Entity Specification](entities.md) and nomenclature.
- * [Return Types](types.md) which are *references* to entities.
-
-### See Also
-
- * [antelope_core](https://github.com/AntelopeLCA/core) The reference implementation including local data source management.
- * [antelope_background](https://github.com/AntelopeLCA/background) Used for partial ordering of databases and construction and inversion of matrices
- * [antelope_foreground](https://github.com/AntelopeLCA/foreground) Used for building foreground models

antelope_interface-0.2.3.2/src/antelope/interfaces/__init__.py

@@ -1,2 +0,0 @@
-from .abstract_query import EntityNotFound
-from .iindex import check_direction, InvalidDirection, InvalidSense

antelope_interface-0.2.3.2/src/antelope_interface.egg-info/PKG-INFO

@@ -1,40 +0,0 @@
-Metadata-Version: 2.1
-Name: antelope_interface
-Version: 0.2.3.2
-Summary: A common interface for accessing LCA data
-Home-page: https://github.com/AntelopeLCA/antelope
-Author: Brandon Kuczenski
-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
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: synonym_dict
-Requires-Dist: pydantic
-
-# antelope
-Standard Interface and reference framework for LCA
-
-The `antelope` package is an interface specification for accessing LCA data resources, as described in [JIE submitted].  It should be subclassed by implementations that wish to expose data using this uniform interface.  A reference implementation, including a stand-alone LCA computing tool, exists...
-
-## Documentation
-
-See the following articles:
-
- * [Antelope Design Principles](principles.md) for documentation of this repository.
- * [Entity Specification](entities.md) and nomenclature.
- * [Return Types](types.md) which are *references* to entities.
-
-### See Also
-
- * [antelope_core](https://github.com/AntelopeLCA/core) The reference implementation including local data source management.
- * [antelope_background](https://github.com/AntelopeLCA/background) Used for partial ordering of databases and construction and inversion of matrices
- * [antelope_foreground](https://github.com/AntelopeLCA/foreground) Used for building foreground models

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

@@ -1,2 +0,0 @@
-synonym_dict
-pydantic