Blob
A stored blob (arbitrary bytes) that can be searched and retrieved. |
|
The asynchronous deletion task's status |
- class Blob(*args, **kwargs)[source]
A stored blob (arbitrary bytes) that can be searched and retrieved.
Instantiating a blob indicates that you want to create a new Descartes Labs storage blob. If you instead want to retrieve an existing blob use
Blob.get()
. You can also useBlob.search()
. Also see the example forupload()
.- Parameters:
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.kwargs (dict) – With the exception of readonly attributes (
created
,modified
) and with the exception of properties (ATTRIBUTES
,is_modified
, andstate
), any attribute listed below can also be used as a keyword argument. Also seeATTRIBUTES
.
Note
The
reader
andwriter
IDs must be prefixed withemail:
,user:
,group:
ororg:
. Theowner
ID only acceptsorg:
anduser:
. Usingorg:
as anowner
will assign those privileges only to administrators for that organization; usingorg:
as areader
orwriter
assigns those privileges to everyone in that organization. Thereaders
andwriters
attributes are only visible in full to theowners
. If you are areader
or awriter
those attributes will only display the element of those lists by which you are gaining read or write access.Any user with
owner
privileges is able to read the blob attributes or data, modify the blob attributes, or delete the blob, including reading and modifying theowners
,writers
, andreaders
attributes.Any user with
writer
privileges is able to read the blob attributes or data, or modify the blob attributes, but not delete the blob. Awriter
can read theowners
and can only read the entry in thewriters
and/orreaders
by which they gain access to the blob.Any user with
reader
privileges is able to read the blob attributes or data. Areader
can read theowners
and can only read the entry in thewriters
and/orreaders
by which they gain access to the blob.Also see Sharing Resources.
- delete()[source]
Delete this catalog object from the Descartes Labs catalog.
Once deleted, you cannot use the catalog object and should release any references.
- Returns:
The status of the deletion task which can be used to wait for completion.
- Return type:
- Raises:
DeletedObjectError – If this catalog object was already deleted.
UnsavedObjectError – If this catalog object is being deleted without having been saved.
ClientError or ServerError – Spurious exception that can occur during a network request.
Methods:
data
([range])Downloads storage blob data.
delete
(id[, client])Delete the catalog object with the given
id
.delete_many
(ids[, raise_on_missing, ...])Delete many blobs from the Descartes Labs catalog.
download
(file[, range])Downloads storage blob to a file.
exists
(id[, client, headers])Checks if an object exists in the Descartes Labs catalog.
get
([id, storage_type, namespace, name, ...])Get an existing Blob from the Descartes Labs catalog.
get_data
([id, storage_type, namespace, ...])Downloads storage blob data.
get_many
(ids[, ignore_missing, client, ...])Get existing objects from the Descartes Labs catalog.
get_or_create
([id, storage_type, namespace, ...])Get an existing object from the Descartes Labs catalog or create a new object.
iter_data
([chunk_size, range])Downloads storage blob data.
iter_lines
([decode_unicode, delimiter])Downloads storage blob data.
namespace_id
(namespace_id[, client])Generate a fully namespaced id.
reload
([request_params, headers])Reload all attributes from the Descartes Labs catalog.
save
([request_params, headers])Saves this object to the Descartes Labs catalog.
search
([client, request_params, headers])A search query for all blobs.
serialize
([modified_only, jsonapi_format])Serialize the catalog object into json.
update
([ignore_errors])Update multiple attributes at once using the given keyword arguments.
upload
(file)Uploads storage blob from a file.
upload_data
(data)Uploads storage blob from a bytes or str.
Attributes:
The point in time this object was created.
A description with further details on this blob.
Timestamp when the blob should be expired and deleted.
A dictionary of up to 50 key/value pairs.
Geometry representing the location for the blob.
Content hash (MD5) for the blob.
Storage location for the blob.
A unique identifier for this object.
Whether any attributes were changed (see
state
).The point in time this object was last modified.
The name of this blob.
The namespace of this blob.
User, group, or organization IDs that own this blob.
User, email, group, or organization IDs that can read this blob.
Size of the blob in bytes.
The state of this catalog object.
Storage state of the blob.
Storage type of the blob.
A list of up to 32 tags, each up to 1000 bytes long.
The value of the attribute is checked against the given type.
User, group, or organization IDs that can edit this blob.
- data(range=None)[source]
Downloads storage blob data.
Downloads data from the blob and returns as a bytes object.
The Blob must be in the state
SAVED
.- Parameters:
range (str or list, optional) – Range(s) of blob to be downloaded. Can either be a string in the standard HTTP Range header format (e.g. “bytes=0-99”), or a list or tuple containing one or two integers (e.g.
(0, 99)
), or a list or tuple of the same (e.g.((0, 99), (200-299))
). A list or tuple of one integer implies no upper bound; in this case the integer can be negative, indicating the count back from the end of the blob.- Returns:
The data retrieved from the Blob.
- Return type:
bytes
- Raises:
ValueError – If any improper arguments are supplied.
DeletedObjectError – If this blob was deleted.
- classmethod delete(id, client=None)[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. Theget_default_client()
will be used if not set.
- Returns:
The status of the deletion task which can be used to wait for completion.
None
if the object was not found.- Return type:
- Raises:
ConflictError – If the object has related objects (bands, images) that exist.
ClientError or ServerError – Spurious exception that can occur during a network request.
Example
>>> Image.delete('my-image-id')
- classmethod delete_many(ids, raise_on_missing=False, wait_for_completion=False, client=None)[source]
Delete many blobs from the Descartes Labs catalog.
Only those blobs that exist and are owned by the user will be deleted. No errors will be raised for blobs that do not exist or are visible but not owned by the user. If you need to know, compare the supplied list of ids with the returned list of deleted ids.
All blobs to be deleted must belong to the same purchase.
- Parameters:
ids (list(str)) – A list of blob ids to delete.
raise_on_missing (bool, optional) – If True, raise an exception if any of the blobs are not found, otherwise ignore missing blobs. Defaults to False.
wait_for_completion (bool, optional) – If True, wait for the deletion to complete before returning. Defaults to False.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns:
A list of the ids of the blobs that were successfully deleted.
- Return type:
list(str)
- Raises:
ClientError or ServerError – Spurious exception that can occur during a network request.
- download(file, range=None)[source]
Downloads storage blob to a file.
Downloads data from the blob to a file.
The Blob must be in the state
SAVED
.- Parameters:
file (str or io.IOBase) – Where to write the downloaded blob. Can be string with path to the file in the local filesystem, or an file opened for writing (
io.IOBase
). If a file like object and already open, must be binary mode and writable. Open file-like objects remain open on return and must be closed by the caller.range (str or list, optional) – Range(s) of blob to be downloaded. Can either be a string in the standard HTTP Range header format (e.g. “bytes=0-99”), or a list or tuple containing one or two integers (e.g.
(0, 99)
), or a list or tuple of the same (e.g.((0, 99), (200-299))
). A list or tuple of one integer implies no upper bound; in this case the integer can be negative, indicating the count back from the end of the blob.
- Returns:
The name of the downloaded file.
- Return type:
str
- Raises:
ValueError – If any improper arguments are supplied.
DeletedObjectError – If this blob was deleted.
- classmethod exists(id, client=None, headers=None)
Checks if an object exists in the Descartes Labs catalog.
- Parameters:
id (str) – The id of the object.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns:
Returns
True
if the givenid
represents an existing object in the Descartes Labs catalog andFalse
if not.- Return type:
bool
- Raises:
ClientError or ServerError – Spurious exception that can occur during a network request.
- classmethod get(id=None, storage_type=StorageType.DATA, namespace=None, name=None, client=None, request_params=None, headers=None)[source]
Get an existing Blob from the Descartes Labs catalog.
If the Blob is found, it will be returned in the
SAVED
state. Subsequent changes will put the instance in theMODIFIED
state, and you can usesave()
to commit those changes and update the Descartes Labs catalog object. Also see the example forsave()
.Exactly one of the
id
andname
parameters must be specified. Ifname
is specified, it is used together with thestorage_type
andnamespace
parameters to form the correspondingid
.- Parameters:
id (str, optional) – The id of the object you are requesting. Required unless
name
is supplied. May not be specified ifname
is specified.storage_type (StorageType, optional) – The storage type of the Blob you wish to retrieve. Defaults to
data
. Ignored unlessname
is specified.namespace (str, optional) – The namespace of the Blob you wish to retrieve. Defaults to the user’s org name (if any) plus the unique user hash. Ignored unless
name
is specified.name (str, optional) – The name of the Blob you wish to retrieve. Required if
id
is not specified. May not be specified ifid
is specified.client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns:
The object you requested, or
None
if an object with the givenid
does not exist in the Descartes Labs catalog.- Return type:
CatalogObject
or None- Raises:
ClientError or ServerError – Spurious exception that can occur during a network request.
- classmethod get_data(id=None, storage_type=StorageType.DATA, namespace=None, name=None, client=None, range=None, stream=False, chunk_size=None)[source]
Downloads storage blob data.
Downloads data for a given blob id and returns as a bytes object.
- Parameters:
id (str, optional) – The id of the object you are requesting. Required unless
name
is supplied. May not be specified ifname
is specified.storage_type (StorageType, optional) – The storage type of the Blob you wish to retrieve. Defaults to
data
. Ignored unlessname
is specified.namespace (str, optional) – The namespace of the Blob you wish to retrieve. Defaults to the user’s org name (if any) plus the unique user hash. Ignored unless
name
is specified.name (str, optional) – The name of the Blob you wish to retrieve. Required if
id
is not specified. May not be specified ifid
is specified.client (Client, optional) – Client instance. If not given, the default client will be used.
range (str or list, optional) – Range(s) of blob to be downloaded. Can either be a string in the standard HTTP Range header format (e.g. “bytes=0-99”), or a list or tuple containing one or two integers (e.g.
(0, 99)
), or a list or tuple of the same (e.g.((0, 99), (200-299))
). A list or tuple of one integer implies no upper bound; in this case the integer can be negative, indicating the count back from the end of the blob.stream (bool, optional) – If True, return a generator that will yield the data in chunks. Defaults to False.
chunk_size (int, optional) – If stream is True, the size of chunks over which to stream. Default is whatever chunks are received on the wire.
- Returns:
The data retrieved from the Blob. If stream is True, returned as an iterator (generator) which will yeild the data in chunks.
- Return type:
bytes or generator
- Raises:
ValueError – If any improper arguments are supplied.
NotFoundError – If the Blob does not exist.
DeletedObjectError – If this blob was deleted.
- classmethod get_many(ids, ignore_missing=False, client=None, request_params=None, headers=None)
Get existing objects from the Descartes Labs catalog.
All returned Descartes Labs catalog objects will be in the
SAVED
state. Also seeget()
.For bands, if you request a specific band type, for example
SpectralBand.get_many()
, you will only receive that type. UseBand.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. Theget_default_client()
will be used if not set.
- Returns:
List of the objects you requested in the same order.
- Return type:
list(
CatalogObject
)- Raises:
NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and
ignore_missing
isFalse
.ClientError or ServerError – Spurious exception that can occur during a network request.
- classmethod get_or_create(id=None, storage_type=StorageType.DATA, namespace=None, name=None, client=None, **kwargs)[source]
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 forsave()
.- Parameters:
id (str, optional) – The id of the object you are requesting. Required unless
name
is supplied. May not be specified ifname
is specified.storage_type (StorageType, optional) – The storage type of the Blob you wish to retrieve. Defaults to
data
. Ignored unlessname
is specified.namespace (str, optional) – The namespace of the Blob you wish to retrieve. Defaults to the user’s org name (if any) plus the unique user hash. Ignored unless
name
is specified.name (str, optional) – The name of the Blob you wish to retrieve. Required if
id
is not specified. May not be specified ifid
is specified.client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_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 seeATTRIBUTES
).
- Returns:
The requested catalog object that was retrieved or created.
- Return type:
- iter_data(chunk_size=None, range=None)[source]
Downloads storage blob data.
Downloads data from the blob and returns as an iterator (generator) which will yield the data (as a bytes) in chunks. This enables the processing of very large files.
The Blob must be in the state
SAVED
.- Parameters:
chunk_size (int, optional) – Size of chunks over which to iterate. Default is whatever size chunks are received.
range (str or list, optional) – Range(s) of blob to be downloaded. Can either be a string in the standard HTTP Range header format (e.g. “bytes=0-99”), or a list or tuple containing one or two integers (e.g.
(0, 99)
), or a list or tuple of the same (e.g.((0, 99), (200-299))
). A list or tuple of one integer implies no upper bound; in this case the integer can be negative, indicating the count back from the end of the blob.
- Returns:
An iterator over the blob data.
- Return type:
generator
- Raises:
ValueError – If any improper arguments are supplied.
DeletedObjectError – If this blob was deleted.
- iter_lines(decode_unicode=False, delimiter=None)[source]
Downloads storage blob data.
Downloads data from the blob and returns as an iterator (generator) which will yield the data as text lines. This enables the processing of very large files.
The Blob must be in the state
SAVED
. The data within the blob must represent encoded text.Note
This method is not reentrant safe.
- Parameters:
decode_unicode (bool, optional) – If true, then decode unicode in the incoming data and return strings. Default is to return bytes.
delimiter (str or byte, optional) – Delimiter for lines. Type depends on setting of
decode_unicode
. Default is to use default line break sequence.
- Returns:
An iterator over the blob byte or text lines, depending on value of
decode_unicode
.- Return type:
generator
- Raises:
ValueError – If any improper arguments are supplied.
DeletedObjectError – If this blob was deleted.
- classmethod namespace_id(namespace_id, client=None)[source]
Generate a fully namespaced id.
- Parameters:
namespace_id (str or None) – 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. Theget_default_client()
will be used if not set.
- Returns:
The fully namespaced id.
- Return type:
str
Example
>>> namespace = Blob.namespace_id("myproject") 'myorg:myproject'
- reload(request_params=None, headers=None)
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’sid
.- Raises:
ValueError – If the catalog object is not in the
SAVED
state.DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
- save(request_params=None, headers=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 aBadRequestError
.If this instance was retrieved using
get()
,get_or_create()
or any other way (for example as part of asearch()
), and any of its values were changed, it will be in theMODIFIED
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 asearch()
), and none of its values were changed, it will be in theSAVED
state, and if norequest_params
parameter is given, nothing will happen.- Parameters:
request_params (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.headers (dict, optional) – A dictionary of header keys and values to be sent with the request.
- Raises:
ConflictError – If you’re trying to create a new object and the object with given
id
already exists in the Descartes Labs catalog.BadRequestError – If any of the attribute values are invalid.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
- classmethod search(client=None, request_params=None, headers=None)[source]
A search query for all blobs.
Return an
BlobSearch
instance for searching blobs in the Descartes Labs catalog. This instance extends theSearch
class with thesummary()
andsummary_interval()
methods which return summary statistics about the blobs that match the search query.- Parameters:
client (
CatalogClient
, optional) – ACatalogClient
instance to use for requests to the Descartes Labs catalog.- Returns:
An instance of the
BlobSearch
class- Return type:
BlobSearch
Example
>>> from descarteslabs.catalog import Blob >>> search = Blob.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 toTrue
, 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 toFalse
, the serialized data will directly contain the attributes of the catalog object. If set toTrue
, the serialized data will follow the exact JSONAPI with a top-leveldata
element which containsid
,type
, andattributes
. 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 toTrue
, it will suppressAttributeValidationError
andAttributeError
. 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.
- upload(file)[source]
Uploads storage blob from a file.
Uploads data from a file and creates the Blob.
The Blob must be in the state
UNSAVED
. Thestorage_state
,storage_type
,namespace
, and thename
attributes, must all be set. If either thesize_bytes
and thehash
attributes are set, they must agree with the actual file to be uploaded, and will be validated during the upload process.On return, the Blob object will be updated to reflect the full state of the new blob.
- Parameters:
file (str or io.IOBase) – File or files to be uploaded. Can be string with path to the file in the local filesystem, or a file-like object (
io.IOBase
). If a file like object and already open, must be binary mode and readable. Open file-like objects remain open on return and must be closed by the caller.- Returns:
The uploaded instance.
- Return type:
- Raises:
ValueError – If any improper arguments are supplied.
DeletedObjectError – If this blob was deleted.
- upload_data(data)[source]
Uploads storage blob from a bytes or str.
Uploads data from a string or bytes and creates the Blob.
The Blob must be in the state
UNSAVED
. Thestorage_state
,storage_type
,namespace
, and thename
attributes, must all be set. If either thesize_bytes
and thehash
attributes are set, they must agree with the actual data to be uploaded, and will be validated during the upload process.On return, the Blob object will be updated to reflect the full state of the new blob.
- Parameters:
data (str or bytes) – Data to be uploaded. A str will be default encoded to bytes.
- Returns:
The uploaded instance.
- Return type:
- Raises:
ValueError – If any improper arguments are supplied.
DeletedObjectError – If this blob was deleted.
- ATTRIBUTES = ('namespace', 'name', 'storage_state', 'storage_type', 'description', 'geometry', 'expires', 'href', 'size_bytes', 'hash', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'id', 'created', 'modified')
- created
The point in time this object was created.
Filterable, sortable.
- Type:
datetime, readonly
- description
A description with further details on this blob.
The description can be up to 80,000 characters and is used by
Search.find_text()
.Searchable
- Type:
str, optional
- expires
Timestamp when the blob should be expired and deleted.
Filterable, sortable.
- Type:
str or datetime, optional
- extra_properties
A dictionary of up to 50 key/value pairs.
The keys of this dictionary 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
- geometry
Geometry representing the location for the blob.
Filterable
(use
BlobSearch.intersects
to search based on geometry)- Type:
str or shapely.geometry.base.BaseGeometry, optional
- hash
Content hash (MD5) for the blob.
- Type:
str, optional
- href
Storage location for the blob.
This attribute may not be set by the end user.
- Type:
str, 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
- 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 blob.
All blobs are stored and indexed by name. Names are allowed a restricted alphabet (
a-zA-Z0-9:._/-
), but may not begin or end with a/
. The combined length of thenamespace
and thename
cannot exceed 979 bytes.The
/
is intended to be used like a directory in a pathname to allow for prefix search operations, but otherwise has no special meaning.Searchable, sortable.
- Type:
str
- namespace
The namespace of this blob.
All blobs are stored and indexed under a namespace. Namespaces are allowed a restricted alphabet (
a-zA-Z0-9:._-
), and must begin with the user’s org name, or their unique user hash if the user has no org. The required prefix is seperated from the rest of the namespace name (if any) by a:
. If not provided, the namespace will default to the users org (if any) and the unique user hash. The combined length of thenamespace
and thename
cannot exceed 979 bytes.Searchable, sortable.
- Type:
str
- owners
User, group, or organization IDs that own this blob.
Defaults to [
user:current_user
,org:current_org
]. The owner can edit, delete, and change access to this blob. See this note.Filterable.
- Type:
list(str), optional
- readers
User, email, group, or organization IDs that can read this blob.
Will be empty by default. This attribute is only available in full to the
owners
of the blob. See this note.- Type:
list(str), optional
- size_bytes
Size of the blob in bytes.
Filterable, sortable.
- Type:
int, optional
- property state
The state of this catalog object.
- Type:
- storage_state
Storage state of the blob.
The state is
AVAILABLE
if the data is available and can be retrieved,REMOTE
if the data is not currently available.Filterable, sortable.
- Type:
str or StorageState
- storage_type
Storage type of the blob.
DATA
is managed by end users (e.g. viadescarteslabs.catalog.Blob.upload()
. Other types are generated and managed by various components of the platform.Filterable, sortable.
- Type:
str or StorageType
- tags
A list of up to 32 tags, each up to 1000 bytes long.
The tags may support the classification and custom filtering of objects.
Filterable.
- Type:
list, optional
- v1_properties
The value of the attribute is checked against the given type.
- Parameters:
attribute_type (type) – The type of the attribute.
coerce (bool, optional) – Whether a non-conforming value should be coerced to that type.
False
by default.**kwargs (optional) – See
Attribute
.
- writers
User, group, or organization IDs that can edit this blob.
Writers will also have read permission. Writers will be empty by default. See note below. This attribute is only available in full to the
owners
of the blob. See this note.- Type:
list(str), optional
- class BlobCollection(iterable=None, item_type=None)[source]
Methods:
append
(x)Append x to the end of this
Collection
.extend
(x)Extend this
Collection
by appending elements from the iterable.filter
(predicate)Returns a
Collection
filtered by predicate.groupby
(*predicates)Groups items by predicates.
map
(f)Returns a
Collection
off
applied to each item.sort
(field[, ascending])Returns a
Collection
, sorted by the given field and direction.sorted
(*predicates, **reverse)Returns a
Collection
, sorted by predicates in ascending order.Attributes:
Any operations chained onto
each
(attribute access, item access, and calls) are applied to each item in theCollection
.- append(x)
Append x to the end of this
Collection
.The type of the item must match the type of the collection.
- Parameters:
x (Any) – Add an item to the collection
- extend(x)
Extend this
Collection
by appending elements from the iterable.The type of the items in the list must all match the type of the collection.
- Parameters:
x (List[Any]) – Extend a collection with the items from the list.
- filter(predicate)
Returns a
Collection
filtered by predicate.Predicate can either be a
callable
or anExpression
from Properties.If the predicate is a
callable
,filter()
will return all items for whichpredicate(item)
isTrue
.If the predicate is an
Expression
,filter()
will return all items for whichpredicate.evaluate(item)
isTrue
.- Parameters:
predicate (callable or Expression) – Either a callable or a Properties
Expression
which is called or evaluated for each item in the list.- Returns:
A new collection with only those items for which the predicate returned or evaluated to
True
.- Return type:
Collection
- groupby(*predicates)
Groups items by predicates.
Groups items by predicates and yields tuple of
(group, items)
for each group, whereitems
is aCollection
.Each predicate can be a key function, or a string of dot-chained attributes to use as sort keys.
- Parameters:
predicates (callable or str) – Any positional arguments are predicates. If the predicate is a string, it denotes an attribute for each element, potentially with levels separated by a dot. If the predicate is a callable, it must return the value to sort by for each given element.
- Yields:
Tuple[str, Collection] – A tuple of
(group, Collection)
for each group.
Examples
>>> import collections >>> FooBar = collections.namedtuple("FooBar", ["foo", "bar"]) >>> c = Collection([FooBar("a", True), FooBar("b", False), FooBar("a", False)])
>>> for group, items in c.groupby("foo"): ... print(group) ... print(items) a Collection([FooBar(foo='a', bar=True), FooBar(foo='a', bar=False)]) b Collection([FooBar(foo='b', bar=False)]) >>> for group, items in c.groupby("bar"): ... print(group) ... print(items) False Collection([FooBar(foo='b', bar=False), FooBar(foo='a', bar=False)]) True Collection([FooBar(foo='a', bar=True)])
- map(f)
Returns a
Collection
off
applied to each item.- Parameters:
f (callable) – Apply function
f
to each element of the collection and return the result as a collection.- Returns:
A collection with the results of the function
f
applied to each element of the original collection.- Return type:
Collection
- sort(field, ascending=True)
Returns a
Collection
, sorted by the given field and direction.- Parameters:
field (str) – The name of the field to sort by
ascending (bool) – Sorts results in ascending order if True (the default), and in descending order if False.
- Returns:
The sorted collection.
- Return type:
Collection
Example
>>> from descarteslabs.catalog import Product >>> collection = Product.search().collect() >>> sorted_collection = collection.sort("created", ascending=False) >>> sorted_collection
- sorted(*predicates, **reverse)
Returns a
Collection
, sorted by predicates in ascending order.Each predicate can be a key function, or a string of dot-chained attributes to use as sort keys. The reverse flag returns results in descending order.
- Parameters:
predicates (callable or str) – Any positional arguments are predicates. If the predicate is a string, it denotes an attribute for each element, potentially with levels separated by a dot. If the predicate is a callable, it must return the value to sort by for each given element.
reverse (bool) – The sort is ascending by default, by setting
reverse
toTrue
, the sort will be descending.
- Returns:
The sorted collection.
- Return type:
Collection
Examples
>>> import collections >>> FooBar = collections.namedtuple("FooBar", ["foo", "bar"]) >>> X = collections.namedtuple("X", "x") >>> c = Collection([FooBar(1, X("one")), FooBar(2, X("two")), FooBar(3, X("three"))])
>>> c.sorted("foo") Collection([FooBar(foo=1, bar=X(x='one')), FooBar(foo=2, bar=X(x='two')), FooBar(foo=3, bar=X(x='three'))]) >>> c.sorted("bar.x") Collection([FooBar(foo=1, bar=X(x='one')), FooBar(foo=3, bar=X(x='three')), FooBar(foo=2, bar=X(x='two'))])
- property each
Any operations chained onto
each
(attribute access, item access, and calls) are applied to each item in theCollection
.- Yields:
Any – The result of an item with all operations following
each
applied to it.
Notes
Add
combine()
at the end of the operations chain to combine the results into a list by default, or any container type passed intocombine()
Use
pipe(f, *args, **kwargs)
to yieldf(x, *args, **kwargs)
for each itemx
yielded by the preceeding operations chain
Examples
>>> c = Collection(["one", "two", "three", "four"]) >>> for x in c.each.capitalize(): ... print(x) One Two Three Four >>> c.each.capitalize()[:2] 'On' 'Tw' 'Th' 'Fo' >>> c.each.capitalize().pipe(len) 3 3 5 4 >>> list(c.each.capitalize().pipe(len).combine(set)) [3, 4, 5]
- class BlobDeletionTaskStatus(*args, **kwargs)[source]
The asynchronous deletion task’s status
- id
The id of the object for which this task is running.
- Type:
str
- 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 objects (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
- ids
The ids of the objects that were deleted.
- Type:
list
- reload()
Update the task information.
- Raises:
ClientError or ServerError – Spurious 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