Client
Classes:
|
An attribute defined on a Document. |
|
Represents a datetime attribute on a document. |
|
An Object or Document in a Descartes Labs service. |
|
An enumeration. |
|
Represents a list attribute on a document. |
|
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:
Whether a property value is not
None
or[]
.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 anIN
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 anIN
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.
- 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:
Whether a property value is not
None
or[]
.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 anIN
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 anIN
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:
Determines if the document has been modified.
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:
- class DocumentState(value)[source]
Bases:
LowercaseStrEnum
An enumeration.
Attributes:
- 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:
Whether a property value is not
None
or[]
.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 anIN
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 anIN
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.
- 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 thein_()
orany_of()
method. You cannot use the boolean keywordsand
andor
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 (usingand
if there were existing filters)- Return type:
- 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:
- param(**params) AnySearch [source]
Add additional parameters to the search request.
- Parameters:
params (dict) – The parameters to add to the search request.
- Return type:
- 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:
Example
>>> from descarteslabs.compute import Function >>> Function.search().sort(Function.id, -Function.creation_date) >>> list(search)