Catalog Objects

Classes

descarteslabs.catalog.CatalogClient

CatalogObject

NamedCatalogObject

AttributeValidationError

Data Types

DocumentState


class CatalogClient(url=None, auth=None, **kwargs)[source]

The CatalogClient handles the HTTP communication with the Descartes Labs catalog. It is almost sufficient to use the default client that is automatically retrieved using get_default_client. However, if you want to adjust e.g. the retries, you can create your own.

Parameters
  • url (str, optional) – The URL to use when connecting to the Descartes Labs catalog. Only change this if you are being asked to use a non-default Descartes Labs catalog. If not set, the logic will first look for the environment variable DESCARTESLABS_CATALOG_V2_URL and then use the default Descartes Labs catalog.

  • auth (Auth, optional) – The authentication object used when connecting to the Descartes Labs catalog. This is typically the default Auth object that uses the cached authentication token retrieved with the shell command “$ descarteslabs auth login”.

  • retries (int, optional) – The number of retries when there is a problem with the connection. Set this to zero to disable retries. The default is 3 retries.

static get_default_client()[source]

Retrieve the default client.

This client is used whenever you don’t explicitly set the client.

static set_default_client(client)[source]

Change the default client to the given client.

This is the client that will be used whenever you don’t explicitly set the client

class CatalogObject(**kwargs)[source]

A base class for all representations of objects in the Descartes Labs catalog.

Parameters
  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any (inherited) attribute listed below can also be used as a keyword argument.

Methods

delete(id[, client, ignore_missing])

Delete the catalog object with the given id.

exists(id[, client])

Checks if an object exists in the Descartes Labs catalog.

get(id[, client])

Get an existing object from the Descartes Labs catalog.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

reload()

Reload all attributes from the Descartes Labs catalog.

save([extra_attributes])

Saves this object to the Descartes Labs catalog.

search([client])

A search query for all object of the type this class represents.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

serialize_attribute(name, value)

Serialize a single attribute value.

Attributes

is_modified

Whether any attributes were changed.

state

The state of this catalog object.

The attributes documented below are shared by all catalog objects.

id

Required, immutable: A unique identifier for this object. Note that if you pass a string that does not begin with your Descartes Labs user organization ID, it will be prepended to your id` with a : as separator. Once set, it cannot be changed.

Type

str

created

Readonly: The point in time this object was created. Filterable, sortable.

Type

datetime

modified

Readonly: The point in time this object was last modified. Filterable, sortable.

Type

datetime

owners

Optional: User, group, or organization IDs that own this object. Defaults to [user:current_user, org:current_org]. The owner can edit, delete, and change access to this object. Filterable.

Type

list(str)

readers

Optional: User, group, or organization IDs that can read this object. Will be empty by default. This attribute is only available to the owners of a catalog object.

Type

list(str)

writers

Optional: User, group, or organization IDs that can edit this object (includes read permission). Will be empty by default. This attribute is only available to the owners of a catalog object.

Type

list(str)

extra_properties

Optional: A dictionary of up to 50 key/value pairs where the strings as keys and numbers or strings as values. This allows for more structured custom metadata to be associated with objects.

Type

dict

tags

Optional: A list of up to 20 tags that may support the classification and custom filtering of objects. Filterable.

Type

list(str)

Note

All owner, reader, and writer IDs must be prefixed with email:, user:, group: or org:. Using org: as an owner will assign those privileges only to administrators for that organization; using org: as a reader or writer assigns those privileges to everyone in that organization. The readers and writers attributes are only visible to the owners, you will not see them otherwise.

delete(ignore_missing=False)[source]

Delete this catalog object from the Descartes Labs catalog.

Once deleted, you cannot use the catalog object and should release any references.

Parameters

ignore_missing (bool, optional) – Whether to ignore (not raise) the NotFoundError exception if the object to be deleted is not found in the Descartes Labs catalog. The default is False.

Returns

True if this object was successfully deleted. Returns False if the object was not found, and ignore_missing = True.

Return type

bool

Raises
  • ConflictError – If the object has related objects (bands, images) that exist.

  • NotFoundError – If the object does not exist in the Descartes Labs catalog and ignore_missing is False.

classmethod delete(id, client=None, ignore_missing=False)[source]

Delete the catalog object with the given id.

Parameters
  • id (str) – The id of the object to be deleted.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • ignore_missing (bool, optional) – Whether to ignore (not raise) the NotFoundError exception if the object to be deleted is not found in the Descartes Labs catalog. False by default which raises the exception.

Returns

True if this object was successfully deleted. False if the object was not found, and ignore_missing = True.

Return type

bool

Raises
  • ConflictError – If the object has related objects (bands, images) that exist.

  • NotFoundError – If the object does not exist in the Descartes Labs catalog and ignore_missing is False.

Example

>>> Image.delete('my-image-id')
classmethod exists(id, client=None)[source]

Checks if an object exists in the Descartes Labs catalog.

Parameters
Returns

Returns True if the given id represents an existing object in the Descartes Labs catalog and False if not.

Return type

bool

classmethod get(id, client=None)[source]

Get an existing object from the Descartes Labs catalog.

Parameters
Returns

The object you requested, or None if an object with the given id does not exist in the Descartes Labs catalog.

Return type

CatalogObject or None

classmethod get_many(ids, ignore_missing=False, client=None)[source]

Get existing objects from the Descartes Labs catalog.

Parameters
  • ids (list(str)) – A list of identifiers for the objects you are requesting.

  • ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the Descartes Labs catalog. False by default which raises the exception.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Raises

NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and ignore_missing is False.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

reload()[source]

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this catalog object from the object in the Descartes Labs catalog. This may be necessary if there are concurrent updates and the object in the Descartes Labs catalog was updated from another client. The instance state must be SAVED.

Raises
  • NotFoundError – If the object no longer exists.

  • ValueError – If the catalog object was not in the SAVED state.

save(extra_attributes=None)[source]

Saves this object to the Descartes Labs catalog.

If this instance has not yet been added to the catalog (i.e. it was created using the constructor), a new object is created. If this instance was previously saved or fetched from the Descartes Labs catalog, and has attributes that have been modified, the object is updated in the Descartes Labs catalog.

Parameters

extra_attributes (dict, optional) – A dictionary of attributes that should be sent to the catalog along with attributes already set on this object. Empty by default. If not empty, the object is updated in the Descartes Labs catalog even if no attributes were modified.

Raises

BadRequestError – If the given id already exists in the Descartes Labs catalog or if attribute values are invalid.

Example

>>> new_product = Product(
...     id="my-product",
...     name="My Product",
...     description="This is a test product"
... )
>>> new_product.save()
>>> # ids will be automatically prefixed by the Descartes Labs catalog
>>> # with your organization id
>>> new_product.id
classmethod search(client=None)[source]

A search query for all object of the type this class represents.

Parameters

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

An instance of the Search class.

Return type

Search

Example

>>> search = Product.search().limit(10)
>>> for result in search:
        print(result.name)
serialize(modified_only=False, jsonapi_format=False)[source]

Serialize the catalog object into json.

Parameters
  • modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.

  • jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

classmethod serialize_attribute(name, value)[source]

Serialize a single attribute value.

Allow the given value to be serialzed using the serialization logic of the given attribute.

Parameters
  • name (str) – The name of the attribute used for serialization logic.

  • value (object) – The value to be serialized.

Raises

descarteslabs.catalog.AttributeValidationError – If the attribute is not serializable.

property is_modified

Whether any attributes were changed.

True if any of the attributes have changed since the last time this catalog object was retrieved or saved. False otherwise.

property state

The state of this catalog object.

See DocumentState.

class NamedCatalogObject(**kwargs)[source]

A catalog object with a required name and product_id instead of id.

A catalog object without a required id but instead a required name and product or product_id. The id is generated from the product_id and the name (product_id:name). If the id is provided, it will be used to extract the name and product_id, if available.

Parameters

kwargs (dict) – With the exception of readonly attributes (created, modified), any (inherited) attribute listed below can also be used as a keyword argument.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base class:


The attributes documented below are shared by all named catalog objects, namely Band and Image.

id

Immutable: An optional unique identifier for this object, a concatenation of the product_id and name, separated by a colon. It will be generated from the product_id and the name if not provided. Otherwise, the name and product_id are extracted from the id. A AttributeValidationError will be raised if it conflicts with an existing product_id and/or name.

Type

str

name

Required, immutable: The name of the catalog object, unique within a product. The name can contain alphanumeric characters, -, _, and .. If the id contains a name, it will be used instead. Once set, it cannot be changed. Sortable.

Type

str

product_id

Required, immutable: The id of the product this catalog object belongs to. If the id contains a product id, it will be used instead. Once set, it cannot be changed. Filterable, sortable.

Type

str

product

The representation of the product this catalog object belongs to. If given, it is used to retrieve the product_id. Filterable.

Type

Product

Example

Any combination that will yield the image name and the product id will work, but the preferred way is using the name and product:

>>> product_id = "some_org:some_product_name"
>>> product = Product.get(product_id)
>>> image_name = "some_image_name"
>>> # Preferred
>>> image = Image(name=image_name, product=product)
>>> # Also possible...
>>> image_id = "{}:{}".format(product.id, image_name)
>>> image = Image(id=image_id)
class DocumentState[source]

The state of the catalog object.

UNSAVED

The catalog object was never synchronized with the Descartes Labs catalog. All values are considered modified and saving the catalog object will create the corresponding object in the Descartes Labs catalog.

Type

enum

MODIFIED

The catalog object was synchronized with the Descartes Labs catalog (using get() or save()), but at least one attribute value has since been changed. You can save() a modified catalog object to update the object in the Descartes Labs catalog.

Type

enum

SAVED

The catalog object has been fully synchronized with the Descartes Labs catalog (using get() or save()).

Type

enum

DELETED

The catalog object has been deleted from the Descartes Labs catalog. Many operations cannot be performed on DELETED objects.

Type

enum

Note

A SAVED catalog object can still be out-of-date with respect to the Descartes Labs catalog if there was an update from another client since the last sycnronization. To re-synchronize a SAVED catalog object you can use reload().

class AttributeValidationError[source]

There was a problem validating the corresponding attribute.

This exception indicates that the attribute value may have been required, may be incorrect, or cannot be serialized.