Product

Product

A raster product that connects band information to imagery.

DeletionTaskStatus

The asynchronous deletion task’s status

UpdatePermissionsTaskStatus

The asynchronous task status for updating related objects’ access control permissions


class Product(**kwargs)[source]

A raster product that connects band information to imagery.

Instantiating a product indicates that you want to create a new Descartes Labs catalog product. If you instead want to retrieve an existing catalog product use Product.get(), or if you’re not sure use Product.get_or_create(). You can also use Product.search(). Also see the example for save().

Parameters

Attributes

ATTRIBUTES

Built-in immutable sequence.

created

The point in time this object was created.

default_display_bands

Which bands to use for RGBA display.

description

A description with further details on this product.

end_datetime

The end of the mission for this product.

extra_properties

A dictionary of up to 50 key/value pairs.

id

A unique identifier for this object.

is_core

Whether this is a Descartes Labs catalog core product.

is_modified

Whether any attributes were changed (see state).

modified

The point in time this object was last modified.

name

The name of this product.

owners

User, group, or organization IDs that own this object.

readers

User, group, or organization IDs that can read this object.

resolution_max

Maximum resolution of the bands for this product.

resolution_min

Minimum resolution of the bands for this product.

revisit_period_minutes_max

Maximum length of the time interval between observations.

revisit_period_minutes_min

Minimum length of the time interval between observations.

start_datetime

The beginning of the mission for this product.

state

The state of this catalog object.

tags

A list of up to 20 tags.

writers

User, group, or organization IDs that can edit this object.

Methods

bands()

A search query for all bands for this product, sorted by default band sort_order.

delete(id[, client])

Delete the catalog object with the given id.

delete_related_objects()

Delete all related bands and images for this product.

derived_bands()

A search query for all derived bands associated with this product.

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_band(name[, client])

Retrieve the request band associated with this product by name.

get_delete_status()

Fetches the status of a deletion task.

get_image(name[, client])

Retrieve the request image associated with this product by name.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

get_or_create(id[, client])

Get an existing object from the Descartes Labs catalog or create a new object.

get_update_permissions_status()

Fetches the status of an update task.

image_uploads()

A search query for all uploads in this product created by this user.

images()

A search query for all images in this product.

named_id(name)

Return the ~descarteslabs.catalog.NamedCatalogObject.id` for the given named catalog object.

namespace_id(id_[, client])

Generate a fully namespaced id.

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 objects of the type this class represents.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update([ignore_errors])

Update multiple attributes at once using the given keyword arguments.

update_related_objects_permissions([owners, …])

Update the owners, readers, and/or writers for all related bands and images.

Note

The reader and writer IDs must be prefixed with email:, user:, group: or org:. The owner ID only accepts org: and user:. 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.

Also see Sharing Resources.

delete()

Delete this catalog object from the Descartes Labs catalog.

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

Raises
bands()[source]

A search query for all bands for this product, sorted by default band sort_order.

Returns

A Search instance configured to find all bands for this product.

Return type

Search

Raises

DeletedObjectError – If this product was deleted.

classmethod delete(id, client=None)

Delete the catalog object with the given id.

Parameters
Returns

True if this object was successfully deleted. False if the object was not found.

Return type

bool

Raises

Example

>>> Image.delete('my-image-id')

Delete all related bands and images for this product.

Starts an asynchronous operation that deletes all bands and images associated with this product. If the product has a large number of associated images, this operation could take several minutes, or even hours.

Returns

Returns DeletionTaskStatus if deletion task was successfully started and None if there were no related objects to delete.

Return type

DeletionTaskStatus

Raises
derived_bands()[source]

A search query for all derived bands associated with this product.

Returns

A Search instance configured to find all derived bands for this product.

Return type

Search

Raises

DeletedObjectError – If this product was deleted.

classmethod exists(id, client=None)

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

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get(id, client=None)

Get an existing object from the Descartes Labs catalog.

If the Descartes Labs catalog object is found, it will be returned in the SAVED state. Subsequent changes will put the instance in the MODIFIED state, and you can use save() to commit those changes and update the Descartes Labs catalog object. Also see the example for save().

For bands, if you request a specific band type, for example SpectralBand.get(), you will only receive that type. Use Band.get() to receive any type.

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

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

get_band(name, client=None)[source]

Retrieve the request band associated with this product by name.

Parameters
Returns

A derived class of Band that represents the requested band object if found, None if not found.

Return type

Band or None

get_delete_status()[source]

Fetches the status of a deletion task.

Fetches the status of a deletion task started using delete_related_objects().

Returns

Return type

DeletionTaskStatus

Raises
get_image(name, client=None)[source]

Retrieve the request image associated with this product by name.

Parameters
Returns

The requested image if found, or None if not found.

Return type

Image or None

classmethod get_many(ids, ignore_missing=False, client=None)

Get existing objects from the Descartes Labs catalog.

All returned Descartes Labs catalog objects will be in the SAVED state. Also see get().

For bands, if you request a specific band type, for example SpectralBand.get_many(), you will only receive that type. Use Band.get_many() to receive any type.

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.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

Raises
classmethod get_or_create(id, client=None, **kwargs)

Get an existing object from the Descartes Labs catalog or create a new object.

If the Descartes Labs catalog object is found, and the remainder of the arguments do not differ from the values in the retrieved instance, it will be returned in the SAVED state.

If the Descartes Labs catalog object is found, and the remainder of the arguments update one or more values in the instance, it will be returned in the MODIFIED state.

If the Descartes Labs catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters
  • id (str) – The id of the object you are requesting.

  • 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 attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns

The requested catalog object that was retrieved or created.

Return type

CatalogObject

get_update_permissions_status()[source]

Fetches the status of an update task.

Fetches the status of an update task started using update_related_objects_permissions().

Returns

Return type

UpdatePermissionsTaskStatus

Raises

Example

>>> product = Product.get('product-id')
>>> product.update_related_objects_permissions()
>>> product.get_update_permissions_status()
image_uploads()[source]

A search query for all uploads in this product created by this user.

Returns

A Search instance configured to find all uploads in this product.

Return type

Search

Raises

DeletedObjectError – If this product was deleted.

images()[source]

A search query for all images in this product.

Returns

A Search instance configured to find all images in this product.

Return type

Search

Raises

DeletedObjectError – If this product was deleted.

named_id(name)[source]

Return the ~descarteslabs.catalog.NamedCatalogObject.id` for the given named catalog object.

Parameters

name (str) – The name of the catalog object within this product, see name.

Returns

The named catalog object id within this product.

Return type

str

classmethod namespace_id(id_, client=None)[source]

Generate a fully namespaced id.

Parameters
  • id_ (str) – The unprefixed part of the id that you want prefixed.

  • 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

The fully namespaced id.

Return type

str

Example

>>> product_id = Product.namespace_id("my-product")
reload()

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 in the SAVED state.

If you want to revert a modified object to its original one, you should use get() on the object class with the object’s id.

Raises

Example

>>> p = Product("my_org_id:my_product_id")
>>> # Some time elapses and a concurrent change was made
>>> p.state
<DocumentState.SAVED: 'saved'>
>>> p.reload()
>>> # But once you make changes, you cannot use this method any more
>>> p.name = "My name has changed"
>>> p.reload()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 47, in wrapper
    return f(self, *args, **kwargs)
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 879, in reload
    """Reload all attributes from the Descartes Labs catalog.
ValueError: Product instance with id my_org_id:my_product_id has not been saved
>>> # But you can revert
>>> p = Product.get(p.id)
>>> p.state
<DocumentState.SAVED: 'saved'>
save(extra_attributes=None)

Saves this object to the Descartes Labs catalog.

If this instance was created using the constructor, it will be in the UNSAVED state and is considered a new Descartes Labs catalog object that must be created. If the catalog object already exists in this case, this method will raise a BadRequestError.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and any of its values were changed, it will be in the MODIFIED state and the existing catalog object will be updated.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and none of its values were changed, it will be in the SAVED state, and if no extra_attributes parameter is given, nothing will happen.

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, and the object is in the SAVED state, it is updated in the Descartes Labs catalog even though no attributes were modified.

Raises

Example

>>> new_product = Product(
...     id="my-product",
...     name="My Product",
...     description="This is a test product"
... )
>>> new_product.state
<DocumentState.UNSAVED: 'unsaved'>
>>> new_product.save()
>>> # ids will be automatically prefixed by the Descartes Labs catalog
>>> # with your organization id
>>> new_product.id
my_org_id:my-product
>>> # Now you can retrieve the product and update it
>>> existing_product = Product.get(new_product.id)
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> existing_product.name = "My Updated Product"
>>> existing_product.state
<DocumentState.MODIFIED: 'modified'>
>>> existing_product.save()
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> # After you delete it...
>>> existing_product.delete()
True
>>> product.state
<DocumentState.DELETED: 'deleted'>
classmethod search(client=None)

A search query for all objects 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)

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.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters

ignore_errors (bool, optional) – False by default. When set to True, it will suppress AttributeValidationError and AttributeError. Any given attribute that causes one of these two exceptions will be ignored, all other attributes will be set to the given values.

Raises
  • AttributeValidationError – If one or more of the attributes being updated are immutable.

  • AttributeError – If one or more of the attributes are not part of this catalog object.

  • DeletedObjectError – If this catalog object was deleted.

Update the owners, readers, and/or writers for all related bands and images.

Starts an asynchronous operation that updates the owners, readers, and/or writers of all bands and images associated with this product. If the product has a large number of associated images, this operation could take several minutes, or even hours.

Parameters
  • owners (str or iterable(str), optional) – An empty list, a single owner or a list of owners; see owners. If None, ignored.

  • readers (str or iterable(str), optional) – An empty list, a single reader or a list of readers; see readers. If None, ignored.

  • writers (str or iterable(str), optional) – An empty list, a single writer or a list of writers; see writers. If None, ignored.

  • inherit (bool, optional) – Whether to inherit the values from the product for owners, readers, and/or writers that have not been set in this request. By default, this value is False and if a parameter is not set, it will not change the corresponding attribute in the related objects. When set to True, and a parameter is not set, it is inherited from the product and applied to all related objects. If inherit is False, at least one of the other parameters must be given. If inherit is True, all other parameters are optional.

Returns

Returns UpdatePermissionsTaskStatus if update task was successfully started and None if there were no related objects to update.

Return type

UpdatePermissionsTaskStatus

Raises
ATTRIBUTES = ('name', 'description', 'is_core', 'revisit_period_minutes_min', 'revisit_period_minutes_max', 'start_datetime', 'end_datetime', 'resolution_min', 'resolution_max', 'default_display_bands', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'id', 'created', 'modified')
created

The point in time this object was created.

Filterable, sortable.

Type

datetime, readonly

default_display_bands

Which bands to use for RGBA display.

This field defines the default bands that are used for display purposes. There are four supported formats: ["greyscale-or-class"], ["greyscale-or-class", "alpha"], ["red", "green", "blue"], and ["red", "green", "blue", "alpha"].

Type

list(str) or iterable

description

A description with further details on this product.

The description can be up to 80,000 characters and is used by Search.find_text().

Searchable

Type

str, optional

end_datetime

The end of the mission for this product.

Filterable, sortable.

Type

str or datetime, optional

extra_properties

A dictionary of up to 50 key/value pairs.

The keys of this dictonary must be strings, and the values of this dictionary can be strings or numbers. This allows for more structured custom metadata to be associated with objects.

Type

dict, optional

id

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. If you are not part of an organization, your user ID is used. Once set, it cannot be changed.

Type

str, immutable

is_core

Whether this is a Descartes Labs catalog core product.

A core product is a product that is fully supported by Descartes Labs. By default this value is False and you must have a special permission (descarteslabs:core:create) to set it to True.

Filterable, sortable.

Type

bool, optional

property is_modified

Whether any attributes were changed (see state).

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

Note that assigning an identical value does not affect the state.

Type

bool

modified

The point in time this object was last modified.

Filterable, sortable.

Type

datetime, readonly

name

The name of this product.

This should not be confused with a band name or image name. Unlike the band name and image name, this name is not unique and purely for display purposes and is used by Search.find_text(). It can contain a string with up to 2000 arbitrary characters.

Searchable, sortable.

Type

str

owners

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. See this note.

Filterable.

Type

list(str), optional

readers

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. See this note.

Type

list(str), optional

resolution_max

Maximum resolution of the bands for this product.

If applying a filter with a plain unitless number the value is assumed to be in meters.

Filterable, sortable.

Type

Resolution, readonly

resolution_min

Minimum resolution of the bands for this product.

If applying a filter with a plain unitless number the value is assumed to be in meters.

Filterable, sortable.

Type

Resolution, readonly

revisit_period_minutes_max

Maximum length of the time interval between observations.

The maximum length of the time interval between observations of any given area in minutes.

Filterable, sortable.

Type

float, optional

revisit_period_minutes_min

Minimum length of the time interval between observations.

The minimum length of the time interval between observations of any given area in minutes.

Filterable, sortable.

Type

float, optional

start_datetime

The beginning of the mission for this product.

Filterable, sortable.

Type

str or datetime, optional

property state

The state of this catalog object.

Type

DocumentState

tags

A list of up to 20 tags.

The tags may support the classification and custom filtering of objects.

Filterable.

Type

list, optional

writers

User, group, or organization IDs that can edit this object.

Writers will also have read permission. Writers will be empty by default. See note below. This attribute is only available to the owners of a catalog object. See this note.

Type

list(str), optional

class DeletionTaskStatus(objects_deleted=None, **kwargs)[source]

The asynchronous deletion task’s status

Methods

reload()

Update the task information.

wait_for_completion([timeout])

Wait for the task to complete.

product_id

The id of the product for which this task is running.

Type

str

status

The state of the task as explained in TaskState.

Type

TaskState

start_datetime

The date and time at which the task started running.

Type

datetime

duration_in_seconds

The duration of the task.

Type

float

objects_deleted

The number of object (a combination of bands or images) that were deleted.

Type

int

errors

In case the status is FAILED this will contain a list of errors that were encountered. In all other states this will not be set.

Type

list

reload()

Update the task information.

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

wait_for_completion(timeout=None)

Wait for the task to complete.

Parameters

timeout (int, optional) – If specified, will wait up to specified number of seconds and will raise a concurrent.futures.TimeoutError if the task has not completed.

Raises

concurrent.futures.TimeoutError – If the specified timeout elapses and the task has not completed

class UpdatePermissionsTaskStatus(objects_updated=None, **kwargs)[source]

The asynchronous task status for updating related objects’ access control permissions

Methods

reload()

Update the task information.

wait_for_completion([timeout])

Wait for the task to complete.

product_id

The id of the product for which this task is running.

Type

str

status

The state of the task as explained in TaskState.

Type

TaskState

start_datetime

The date and time at which the task started running.

Type

datetime

duration_in_seconds

The duration of the task.

Type

float

objects_updated

The number of object (a combination of bands or images) that were updated.

Type

int

errors

In case the status is FAILED this will contain a list of errors that were encountered. In all other states this will not be set.

Type

list

reload()

Update the task information.

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

wait_for_completion(timeout=None)

Wait for the task to complete.

Parameters

timeout (int, optional) – If specified, will wait up to specified number of seconds and will raise a concurrent.futures.TimeoutError if the task has not completed.

Raises

concurrent.futures.TimeoutError – If the specified timeout elapses and the task has not completed