Client

Classes:

`Attribute`([type, default, doc, filterable, ...])	An attribute defined on a Document.
`DatetimeAttribute`([timezone, ...])	Represents a datetime attribute on a document.
`Document`([saved])	An Object or Document in a Descartes Labs service.
`DocumentState`(value)	An enumeration.
`ListAttribute`([type, default, mutable, ...])	Represents a list attribute on a document.
`Search`(document, client[, url])	A search request that iterates over its search results.

class Attribute(type: Type[T] | None = None, default: T | Callable | None = None, doc: str | None = None, filterable: bool = False, mutable: bool = True, readonly: bool = False, sortable: bool = False, sticky: bool = False)[source]

Bases: Property

An attribute defined on a Document.

Defines a document attribute.

Examples

class MyDocument(Document):
    id: id = Attribute(readonly=True)
    name: str = Attribute(str)
    set_once: str = Attribute(str, mutable=False)

doc = MyDocument(name="test", set_once="can only be set once")
doc.set_once = "error"

Parameters:

default (Any, Callable, None) – The default value for the attribute when no value is defined. If a callable is provided, it will be called once when the attribute is first fetched.
doc (str, None) – Sets the doc string for the attribute.
filterable (bool, False) – If set, the attribute can be used as a filter.
mutable (bool, True) – If not set, the attribute will be immutable and can only be set once.
readonly (bool, False) – If set, the attribute cannot be modified by the user. This is designed for attributes set and managed exclusively by the server.
sortable (bool, False) – If set, the attribute can be used to sort results.
sticky (bool, False) – If set, the attribute exists on the client only. This attribute will be ignored when set by the server.

Methods:

`any_of`(iterable)	The property must have any of the given values.
`deserialize`(value[, instance, force])	Deserializes a value to the type in the attribute.
`in_`(iterable)	The property must have any of the given values.
`like`(wildcard)	Compare against a wildcard string.
`prefix`(prefix)	Compare against a prefix string.
`serialize`(value)	Serializes a value to a JSON encodable type.
`startswith`(prefix)	Compare against a prefix 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.

deserialize(value: Any, instance: Document = None, force: bool = False) → T[source]

Deserializes a value to the type in the attribute.

Parameters:

value (Any) – The value to deserialize into a native Python type.
instance (Document, None) – The document instance the value is being deserialized for. When a value is set on a document, the instance will not be None.

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'.

prefix(prefix): Compare against a prefix string.

serialize(value)[source]: Serializes a value to a JSON encodable type.

startswith(prefix): Compare against a prefix string.

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 DatetimeAttribute(timezone=None, remote_timezone=datetime.timezone.utc, default: T | Callable | None = None, mutable: bool = True, readonly: bool = False, sticky: bool = False, **extra)[source]

Bases: Attribute

Represents a datetime attribute on a document.

Defines a datetime attribute.

Parameters:

timezone (timezone, None) – The timezone the client would like dates to be in. By default, this will used the timezone defined by the user’s machine.
remote_timezone (timezone, timezone.utc) – The timezone the server will return dates in. By default, this is assumed to be UTC.
default (Any, Callable, None) – The default value for the attribute when no value is defined. If a callable is provided, it will be called once when the attribute is first fetched.
mutable (bool, True) – If not set, the attribute will be immutable and can only be set once.
readonly (bool, False) – If set, the attribute cannot be modified by the user. This is designed for attributes set and managed exclusively by the server.
sticky (bool, False) – If set, the attribute exists on the client only. This attribute will be ignored when set by the server.

Methods:

`any_of`(iterable)	The property must have any of the given values.
`deserialize`(value[, instance, force])	Deserialize a server datetime.
`in_`(iterable)	The property must have any of the given values.
`like`(wildcard)	Compare against a wildcard string.
`prefix`(prefix)	Compare against a prefix string.
`serialize`(value)	Serialize a datetime in local time to server time in iso format.
`startswith`(prefix)	Compare against a prefix 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.

deserialize(value: str, instance: Document = None, force: bool = False) → T[source]: Deserialize a server datetime.

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'.

prefix(prefix): Compare against a prefix string.

serialize(value: datetime)[source]: Serialize a datetime in local time to server time in iso format.

startswith(prefix): Compare against a prefix string.

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 Document(saved=False, **kwargs)[source]

Bases: object

An Object or Document in a Descartes Labs service.

Methods:

`to_dict`([only_modified, exclude_readonly, ...])	Converts the document to a dictionary.
`update`([ignore_missing])	Updates the document setting multiple attributes at a time.

Attributes:

`is_modified`	Determines if the document has been modified.
`state`	Returns the state of the current document instance.

to_dict(only_modified: bool = False, exclude_readonly: bool = False, exclude_none: bool = False) → Dict[str, Any][source]

Converts the document to a dictionary.

Attributes will be serialized to JSON encodable types.

Parameters:

only_modified (bool, False) – If set, only modified attributes and their values will be included.
exclude_readonly (bool, False) – If set, readonly attributes and their values are excluded.
exclude_none (bool, False) – If set, attributes with a value of None will be excluded.

Returns:

The attributes matching the call parameters. The result of this function can be json encoded without modification.

Return type:

Dict[str, Any]

update(ignore_missing=False, **kwargs)[source]

Updates the document setting multiple attributes at a time.

Parameters:: ignore_missing (bool, False) – If set, unknown attributes will be ignored.

property is_modified: bool: Determines if the document has been modified.

property state: DocumentState

Returns the state of the current document instance.

Return type:: DocumentState

class DocumentState(value)[source]

Bases: LowercaseStrEnum

An enumeration.

Attributes:

`DELETED`
`MODIFIED`
`NEW`
`SAVED`

DELETED = 'deleted'

MODIFIED = 'modified'

NEW = 'new'

SAVED = 'saved'

class ListAttribute(type: Type[T] | None = None, default: T | Callable | None = None, mutable: bool = True, readonly: bool = False, sticky: bool = False, **extra)[source]

Bases: Attribute

Represents a list attribute on a document.

Defines a list attribute.

Parameters:

type (Type[T], None) – The type of the items in the list.
default (Any, Callable, None) – The default value for the attribute when no value is defined. If a callable is provided, it will be called once when the attribute is first fetched.
mutable (bool, True) – If not set, the attribute will be immutable and can only be set once.
readonly (bool, False) – If set, the attribute cannot be modified by the user. This is designed for attributes set and managed exclusively by the server.
sticky (bool, False) – If set, the attribute exists on the client only. This attribute will be ignored when set by the server.

Methods:

`any_of`(iterable)	The property must have any of the given values.
`deserialize`(value[, instance, force])	Deserialize a list of values.
`in_`(iterable)	The property must have any of the given values.
`like`(wildcard)	Compare against a wildcard string.
`prefix`(prefix)	Compare against a prefix string.
`serialize`(value)	Serialize a list of values.
`startswith`(prefix)	Compare against a prefix 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.

deserialize(value: Any, instance: Document = None, force: bool = False) → T[source]: Deserialize a list of values.

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'.

prefix(prefix): Compare against a prefix string.

serialize(value)[source]: Serialize a list of values.

startswith(prefix): Compare against a prefix string.

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 Search(document: T, client: ApiService, url: str = None, **params)[source]

Bases: Generic[T]

A search request that iterates over its search results.

The search can be narrowed by using the methods on the search object.

Example

>>> search = Search(Model).filter(Model.name == "test")
>>> list(search) 
>>> search.collect() 

Methods:

`collect`(**kwargs)	Execute the search query and return the appropriate collection.
`count`()	Fetch the number of documents that match the search.
`filter`(expression)	Filter results by the values of various fields.
`limit`(limit)	Limit the number of search results returned by the search execution.
`param`(**params)	Add additional parameters to the search request.
`sort`(*sorts)	Sort the returned results by the given fields.

collect(**kwargs) → Collection[T][source]

Execute the search query and return the appropriate collection.

Returns:

Collection of objects that match the type of document beng searched.

Return type:

Collection

Raises:

BadRequestError – If any of the query parameters or filters are invalid
ClientError or ServerError – Spurious exception that can occur during a network request.

count() → int[source]

Fetch the number of documents that match the search.

Returns:

Number of matching records

Return type:

int

Raises:

BadRequestError – If any of the query parameters or filters are invalid
ClientError or ServerError – Spurious exception that can occur during a network request.

Example

>>> from descarteslabs.compute import Function
>>> search = Function.search().filter(Function.status == "building")
>>> count = search.count() 

filter(expression: Expression | LogicalExpression) → AnySearch[source]

Filter results by the values of various fields.

Successive calls to filter will add the new filter(s) using the and Boolean operator (&).

Parameters:: expression (Expression) – Expression used to filter objects in the search by their attributes, built from class attributes ex. Job.id == ‘some-id’. You can construct filter expressions using the ==, !=, <, >, <= and >= operators as well as the in_() or any_of() method. You cannot use the boolean keywords and and or because of Python language limitations; instead combine filter expressions using & (boolean “and”) and | (boolean “or”).
Returns:: A new Search instance with the new filter(s) applied (using and if there were existing filters)
Return type:: Search
Raises:: ValueError – If the filter expression provided is not supported.

Example

>>> from descarteslabs.compute import Job
>>> search = Job.search().filter(
...     (Job.runtime > 60) | (Job.status == "failure")
... )
>>> list(search) 

limit(limit: int) → AnySearch[source]

Limit the number of search results returned by the search execution.

Successive calls to limit will overwrite the previous limit parameter.

Parameters:: limit (int) – The maximum number of records to return.
Return type:: Search

param(**params) → AnySearch[source]

Add additional parameters to the search request.

Parameters:: params (dict) – The parameters to add to the search request.
Return type:: Search

sort(*sorts: List[Attribute | Sort]) → AnySearch[source]

Sort the returned results by the given fields.

Parameters:: sorts (List[Union[Attribute, Sort]]) – The attributes and direction to sort by.
Return type:: Search

Example

>>> from descarteslabs.compute import Function
>>> Function.search().sort(Function.id, -Function.creation_date) 
>>> list(search) 