DotDict

Classes:

DotDict	Subclass of dict, with “dot” (attribute) access to keys, a pretty-printed repr, which indents and truncates large containers, and a JSON repr for Jupyter Lab.
DotDict_items(dotdict)	Wrapper around a dict_values object that yields dicts and lists as DotDicts and DotLists when iterated.
DotDict_values(dotdict)	Wrapper around a dict_values object that yields dicts and lists as DotDicts and DotLists when iterated.
DotDict_view(dotdict)	Wrapper around a dictionary view object that yields dicts and lists as DotDicts and DotLists when iterated.
DotList	Returns contained dicts as DotDicts (and contained lists as DotLists), soley to allow attribute access past list indexing

class DotDict

Subclass of dict, with “dot” (attribute) access to keys, a pretty-printed repr, which indents and truncates large containers, and a JSON repr for Jupyter Lab.

Any dicts stored in DotDict are returned as DotDicts, to allow chained attribute access. Any lists stored in DotDict are returned as DotLists, which return any contained dict items as DotDicts, allowing chained attribute access past list indexing.

The repr() of a DotDict is truncated for readability, but str() is not.

Example

>>> d = DotDict(a=1, b=[{"foo": "bar"}])
>>> d.a
    1
>>> d["a"]
    1
>>> d.b
    [
      {
        'foo': 'bar'
      }
    ]
>>> d.b[0].foo
    'bar'

Methods:

asdict()	Raises RuntimeError if the container is recursive (contains itself as a value).
get(k[,d])	Values that are dicts or lists are cast to DotDicts and DotLists.
items()	Equivalent to dict.items.
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised.
popitem()	2-tuple; but raise KeyError if D is empty.
setdefault(k[,d])	If d is a dict or list, it is returned as a DotDict or DotList.
values()	Equivalent to dict.values.

asdict() → a deep copy of D, where any DotDicts or DotLists contained are converted to plain types.

Raises RuntimeError if the container is recursive (contains itself as a value).

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

Values that are dicts or lists are cast to DotDicts and DotLists.

items()

Equivalent to dict.items. Values that are plain dicts or lists are returned as DotDicts or DotLists.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised. If v is a dict or list, it is returned as a DotDict or DotList.

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty. If v is a dict or list, it is returned as a DotDict or DotList.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

If d is a dict or list, it is returned as a DotDict or DotList.

values()

Equivalent to dict.values. Values that are plain dicts or lists are returned as DotDicts or DotLists.

class DotDict_items(dotdict)

Wrapper around a dict_values object that yields dicts and lists as DotDicts and DotLists when iterated.

Methods:

isdisjoint(iterable)

Return True if the view and the given iterable have a null intersection.

isdisjoint(iterable)

Return True if the view and the given iterable have a null intersection.

class DotDict_values(dotdict)

Wrapper around a dict_values object that yields dicts and lists as DotDicts and DotLists when iterated.

class DotDict_view(dotdict)

Wrapper around a dictionary view object that yields dicts and lists as DotDicts and DotLists when iterated.

class DotList

Returns contained dicts as DotDicts (and contained lists as DotLists), soley to allow attribute access past list indexing

Methods:

aslist()	Raises RuntimeError if the container is recursive (contains itself as a value).
pop([index])	If item is a dict or list, it is returned as a DotDict or DotList.

aslist() → a deep copy of L, where any DotDicts or DotLists contained are converted to plain types.

Raises RuntimeError if the container is recursive (contains itself as a value).

pop([index]) → item -- remove and return item at index (default last).

If item is a dict or list, it is returned as a DotDict or DotList. Raises IndexError if list is empty or index is out of range.

Properties

A property or attribute is any field listed as part of a catalog object. For example, the property or attribute modified of a product:

Product.modified

You cannot filter on all attributes. The documentation will indicate whether an attribute is filterable.

The easiest way to generate a property or attribute, is to name it in a GenericProperties instance. Typically such an instance is already included as a properties instance in the corresponding module, for example descarteslabs.catalog.properties.

from descarteslabs.catalog import properties as p
p.modified

or

from descarteslabs.common.property_filtering import GenericProperties
p = GenericProperties()
p.modified

or

from descarteslabs.common.property_filtering import Properties
p = Properties("modified", "created")
p.modified

or

from descarteslabs.common.property_filtering import Property
Property("modified")

You can use a property in an expression. An expression is the result of any filtering operation. Refer to the explanation in Expression for more information.

Classes:

AndExpression(parts)	True if both expressions are True, False otherwise.
EqExpression(name, value)	Whether a property value is equal to the given value.
Expression	An expression is the result of a filtering operation.
IsNotNullExpression(name)	Whether a property value is not None or [].
IsNullExpression(name)	Whether a property value is None or [].
LikeExpression(name, value)	Whether a property value matches the given wildcard expression.
NeExpression(name, value)	Whether a property value is not equal to the given value.
OrExpression(parts)	True if either expression is True, False otherwise.
Properties(*args)	A wrapper object to construct filter properties by referencing instance attributes.
Property(name[, parts])	A filter property that can be used in an expression.
RangeExpression(name, parts)	Whether a property value is within the given range.

class AndExpression(parts)

True if both expressions are True, False otherwise.

class EqExpression(name, value)

Whether a property value is equal to the given value.

class Expression

An expression is the result of a filtering operation.

An expression can contain a Property, a comparison operator, and a value (or set of values):

property operator value

or

value operator property

where the operator can be

• ==
• !=
• <
• <=
• >
• >=

If the operator is <, <=, > or >=, you can construct a range using

value operator property operator value

Expressions can be combined using the Boolean operators & and | to form larger expressions. Due to language limitations the operator for and is expressed as & and the operator for or is expressed as |. Also, because of operator precedence, you must bracket expressions with ( and ) to avoid unexpected behavior:

( property operator value ) & ( value operator property )

In addition there is a method-like operator that can be used on a property.

• Property.any_of() or Property.in_()

And a couple of properties that allow you to verify whether a property value has been set or not. A property value is considered null when it’s either set to None or to the empty list [] in case of a list property. These are only available for the Catalog Service.

• Property.isnull
• Property.isnotnull

Examples

>>> from descarteslabs.common.property_filtering import Properties
>>> p = Properties()
>>> e = p.foo == 5
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.EqExpression'>
>>> e = p.foo.any_of([1, 2, 3, 4, 5])
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.OrExpression'>
>>> e = 5 < p.foo < 10
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.RangeExpression'>
>>> e = (5 < p.foo < 10) & p.foo.any_of([1, 2, 3, 4, 5])
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.AndExpression'>
>>> e = p.foo.isnotnull
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.IsNotNullExpression'>
>>> e = p.foo.isnull
>>> type(e)
<class 'descarteslabs.common.property_filtering.filtering.IsNullExpression'>

class IsNotNullExpression(name)

Whether a property value is not None or [].

class IsNullExpression(name)

Whether a property value is None or [].

class LikeExpression(name, value)

Whether a property value matches the given wildcard expression.

The wildcard expression can contain % for zero or more characters and _ for a single character.

This can only be used in expressions for the Vector product.

class NeExpression(name, value)

Whether a property value is not equal to the given value.

class OrExpression(parts)

True if either expression is True, False otherwise.

class Properties(*args)

A wrapper object to construct filter properties by referencing instance attributes.

By referring to any instance attribute, a corresponding property will be created. The instance validates whether the generated property is in the list of property names that this instance was created with.

See Properties Introduction for a more detailed explanation.

Parameters:name (str) – The property names that are allowed, each as a positional parameter.

Examples

>>> p = Properties("modified", "created")
>>> e = p.modified > "2020-01-01"
>>> e = p.deleted > "2020-01-01"  
Traceback (most recent call last):
  ...
AttributeError: 'Properties' object has no attribute 'deleted'
>>>

class Property(name, parts=None)

A filter property that can be used in an expression.

Although you can generate filter properties by instantiating this class, a more convenient method is to use a Properties instance. By referencing any attribute of a Properties instance the corresponding filter property will be created.

See Properties Introduction for a more detailed explanation.

Examples

>>> e = Property("modified") > "2020-01-01"

Methods:

any_of(iterable)	The property must have any of the given values.
in_(iterable)	The property must have any of the given values.
like(wildcard)	Compare against a wildcard string.

Attributes:

isnotnull	Whether a property value is not None or [].
isnull	Whether a property value is None or [].

any_of(iterable)

The property must have any of the given values.

Asserts that this property must have a value equal to one of the values in the given iterable. This can be thought of as behaving like an in expression in Python or an IN expression in SQL.

in_(iterable)

The property must have any of the given values.

Asserts that this property must have a value equal to one of the values in the given iterable. This can be thought of as behaving like an in expression in Python or an IN expression in SQL.

like(wildcard)

Compare against a wildcard string.

This can only be used in expressions for the Vector service. This allows for wildcards, e.g. like("bar%foo") where any string that starts with 'bar' and ends with 'foo' will be matched.

This uses the SQL LIKE syntax with single character wildcard '_' and arbitrary character wildcard '%'.

To escape either of these wilcard characters prepend it with a backslash, which becomes a double backslash in the python string, i.e. use like("bar\\%foo") to match exactly 'bar%foo'.

property isnotnull

Whether a property value is not None or [].

This can only be used in expressions for the Catalog service.

property isnull

Whether a property value is None or [].

This can only be used in expressions for the Catalog service.

class RangeExpression(name, parts)

Whether a property value is within the given range.

A range can have a single value that must be >, >=, < or <= than the value of the property. If the range has two values, the property value must be between the given range values.