unitpackage.descriptor

Wrappers for a Data Package’s metadata stored within the metadata descriptor property of a resource.

These wrappers are automatically applied to all metadata of each Entry in our Collection.

Metadata in data packages is stored as a JSON object. In Python, such a nested JSON object gets turned into a hierarchy of dictionaries and lists. Such raw data structures can be a bit tedious to work with, so the descriptors in this module provide some convenience wrappers for it, e.g., better tab-completion when working in an interactive session.

EXAMPLES:

To add convenience methods to a data package’s descriptor, run it through the Descriptor() factory function:

>>> descriptor = {'some': {'nested': 'metadata'}}
>>> descriptor = Descriptor(descriptor)

Such a descriptor has some added convenience methods that make it more convenient to work with.

For example, it can be easily dumped to YAML:

>>> print(descriptor.yaml)
some:
    nested: metadata

It can be explored with attributes that are more tab-completion friendly:

>>> descriptor.some.nested
'metadata'

Extra methods are added if the descriptor satisfies a certain interface:

>>> descriptor = {'some': {'nested': {'value': 13.37, 'unit': 'parsec'}}}
>>> descriptor = Descriptor(descriptor)
>>> descriptor.some.nested.quantity.to('km')
<Quantity 4.12555093e+14 km>

unitpackage.descriptor.Descriptor(descriptor)

Return descriptor augmented with additional convenience methods.

EXAMPLES:

Primitive types are returned unchanged:

>>> Descriptor("string")
'string'

Dictionaries are augmented with attribute access:

>>> descriptor = Descriptor({"an attribute": 13.37})
>>> descriptor.an_attribute
13.37

Lists are recursively augmented:

>>> descriptor = Descriptor([{"an attribute": 13.37}, {}])
>>> descriptor[0].an_attribute
13.37

Lists can also be represented in yaml format:

>>> print(descriptor.yaml)
- an attribute: 13.37
- {}

Dictionaries encoding a unit and value are augmented with astropy convenience methods:

>>> descriptor = Descriptor({"value": 1, "unit": "liter"})
>>> descriptor.quantity.to("m^3")
<Quantity 0.001 m3>

class unitpackage.descriptor.GenericDescriptor(descriptor)

Wrapper for a data package’s descriptor to make searching in metadata easier.

EXAMPLES:

>>> GenericDescriptor({'a': 0})
{'a': 0}

to_builtin()

Return this descriptor converted to plain Python built-ins.

EXAMPLES:

>>> GenericDescriptor({'a': 0}).to_builtin()
{'a': 0}

property yaml

Return a printable representation of this descriptor in yaml format.

EXAMPLES:

>>> descriptor = GenericDescriptor({'a': 0})
>>> descriptor.yaml
'a: 0\n'

A descriptor with nested dictionaries and lists is also properly represented:

>>> descriptor = GenericDescriptor({'first': 0, 'second': {'items': [1, 2]}})
>>> descriptor.yaml
'first: 0\nsecond:\n  items:\n  - 1\n  - 2\n'

class unitpackage.descriptor.GenericListDescriptor(descriptor)

Wrapper for list descriptors to make descriptor handling more consistent.

EXAMPLES:

>>> descriptor = GenericListDescriptor([{"a": 0}, {"b": 1}])
>>> descriptor[0].a
0

to_builtin()

Return this descriptor converted to plain Python built-ins.

EXAMPLES:

>>> GenericListDescriptor([{"a": 0}, {"b": 1}]).to_builtin()
[{'a': 0}, {'b': 1}]

property yaml

Return a printable representation of this descriptor in yaml format.

EXAMPLES:

>>> descriptor = GenericListDescriptor([{"a": 0}, {"b": 1}])
>>> descriptor.yaml
'- a: 0\n- b: 1\n'

class unitpackage.descriptor.QuantityDescriptor(descriptor)

Extends a descriptor with convenience methods when it is encoding a quantity, i.e., unit and value.

EXAMPLES:

>>> from unitpackage.entry import Entry
>>> entry = Entry.create_example()
>>> temperature = entry.echemdb.system.electrolyte.temperature
>>> temperature
298.15 K

property quantity

This quantity as an astropy quantity.

EXAMPLES:

>>> from unitpackage.entry import Entry
>>> entry = Entry.create_example()
>>> temperature = entry.echemdb.system.electrolyte.temperature
>>> temperature.quantity
<Quantity 298.15 K>