Entity References

antelope.refs.base module

Motivation: The main idea is that one can manipulate entities by reference without possessing the actual source data. Each entity is identified as a string ‘origin/external_ref’, where an origin is a hierarchical specification with semantic significance (e.g. ecoinvent.3.4.cutoff) and the ‘external_ref’ is the unique id of the entity in that source.

A catalog can resolve a catalog reference by locating the appropriate source and retrieving the entity, or asking other questions about it. To that end, the origins and their mapping to source data must be curated.

Design principles: 1. References should be lightweight and should not require importing anything. Of course, references are useless without access to a query object that can implement the various methods.

  1. Un-grounded references are useless except for collecting metadata about entities.

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:

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.

exception antelope.refs.base.NoCatalog

Bases: Exception

exception antelope.refs.base.InvalidQuery

Bases: Exception

exception antelope.refs.base.EntityRefMergeError

Bases: Exception

exception antelope.refs.base.PropertyExists

Bases: Exception

exception antelope.refs.base.NoUuid

Bases: Exception

class antelope.refs.base.BaseRef(origin, external_ref, uuid=None, **kwargs)

Bases: BaseEntity

A base class for defining entity references. The base class can also store information, such as properties

property origin

Must return a resolvable unique ID, nominally ‘origin/external_ref’ :return:

property external_ref

Must return a resolvable unique ID, nominally ‘origin/external_ref’ :return:

property uuid
property entity_type
properties()
get(item, default=None)

get() is local only. subclasses should implement get_item() to access items via a query :param item: :param default: :return:

has_property(item)
property resolved
merge(other)
show()

should be finessed in subclasses :return:

serialize(**kwargs)
Parameters:

kwargs – ‘domesticate’ has no effect- refs can’t be domesticated

Returns:

class antelope.refs.base.EntityRef(external_ref, query, reference_entity=None, masquerade=None, **kwargs)

Bases: BaseRef

An EntityRef is a CatalogRef that has been provided a valid catalog query. the EntityRef is still semi-abstract since there is no meaningful reference to an entity that is not typed.

property reference_field
make_ref(*args)

if is_entity is true, entity must return a ref made from the provided query :param query: :return:

property uuid
query_synonyms(term)

Provide access to root archive’s synonyms :param term: :return:

get_reference()
property reference_entity

Must have a .unit property that returns a string, should have .entity_type property that returns ‘quantity’ :return:

property resolved
signature_fields()
validate()

This is required by certain implementations to be added to archives (born legacy…) There should be no way to get through the instantiation without a valid query, so this should probably just return True (or be made more useful) :return:

check_bg()
properties(force_query=False)
get_item(item)
This keeps generating recursion errors. Let’s think it through.

  • first checks locally. If known, great.

  • if not, need to check remotely by running the query.

  • the query retrieves the entity and asks has_property – 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?

Parameters:

item

Returns:

has_property(item)

let’s deal with the recursion issue head-on :param item: :return:

serialize(**kwargs)
Parameters:

kwargs – ‘domesticate’ has no effect- refs can’t be domesticated

Returns:

antelope.refs.catalog_ref module

The main import.

exception antelope.refs.catalog_ref.UnknownOrigin

Bases: Exception

class antelope.refs.catalog_ref.CatalogRef(origin, external_ref, entity_type=None, reference_entity=None, **kwargs)

Bases: BaseRef

user-facing entity ref generator

CatalogRef.from_json(j, catalog=None)

A catalog ref is defined by an entity’s origin and external reference, which are all that is necessary to identify and/or recreate the entity. A ref can be “grounded” by being provided with a query that can resolve the reference and access the entity.

Parameters:

  • origin – semantic reference to data source (catalog must resolve to a physical data source)

  • ref – external reference of entity in semantic data source

  • _query – if a query is already on hand, set it and skip the catalog lookup

  • catalog – semantic resolver. Must provide the interfaces that can be used to answer queries

classmethod from_json(j, catalog=None)
classmethod from_query(external_ref, query, etype, **kwargs)
property reference_entity

Must have a .unit property that returns a string, should have .entity_type property that returns ‘quantity’ :return:

property name
quantity_terms()

Code repetition! for subclass purity :return:

validate()

Always returns true in order to add to an archive. this should probably be fixed. :return:

property entity_type
property unit
property is_lcia_method
has_lcia_engine()
cf(*args, **kwargs)
resolve()

Module contents