Containers

Classes

CollectionMixin()
Dict(*dct, **kwargs) Proxy mapping, from keys of a specific type to values of a specific type.
List(iterable) Proxy sequence of any number of elements, all of the same type.
Struct(**kwargs) Proxy container with named fields of specific types, meant as a helper base class.
Tuple(iterable) Proxy sequence of a fixed number of elements of specific types.
KnownDict() Mapping from specific keys to specific value types, with default type for unknown values.

Functions

zip(*lists) Returns a List of Tuple, where each tuple contains the i-th element from each of the argument List.
class CollectionMixin[source]

Methods

contains(other) Contains is equivalient to the Python in operator.
filter(func) Filter elements from an iterable proxytype.
length() Length is equivalent to the Python len operator.
map(func) Map a function over an iterable proxytype.
reduce(func[, initial]) Reduce a collection of elements to a single element.
sorted([key, reverse]) Copy of this collection, sorted by a key function.
contains(other)[source]

Contains is equivalient to the Python in operator.

Parameters:other (Proxytype) – A Proxytype or type that can be promoted to a Proxytype
Returns:A Bool Proxytype
Return type:Bool
filter(func)[source]

Filter elements from an iterable proxytype.

Parameters:func (Python callable) – A function that takes a single argument and returns a Bool Proxytype.
Returns:A Proxytype of the same type having only the elements where func returns True.
Return type:Proxtype

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("sentinel-2:L1C")
>>> filtered = col.filter(lambda img: img.properties["date"].year == 2018)
length()[source]

Length is equivalent to the Python len operator.

Returns:An Int Proxytype
Return type:Int
map(func)[source]

Map a function over an iterable proxytype.

Parameters:func (Python callable) – A function that takes a single argument and returns another proxytype.
Returns:The return type is dependent on the func and the type of the element returned. For example, calling map over an ImageCollection with a function that returns the date of the Image will now be a List[Datetime].
Return type:Proxtype

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("sentinel-2:L1C")
>>> dates = col.map(lambda img: img.properties["date"])
>>> type(dates).__name__
'List[Datetime]'
reduce(func, initial='__NO_INITIAL_REDUCE_VALUE__')[source]

Reduce a collection of elements to a single element.

NOTE: Optimized reducers such as sum have been implemented for some classes.

Parameters:
  • func (Python callable) – A function where the left argument is the accumulated value (the result of the previous call to func) and the right argument is the next value from the iterable. The function should return a single proxtype.
  • initial (Proxytype, optional) – An optional proxtype to provide for the first iteration. If no value is provided, the first element will be used.
Returns:

The return value of func for the last iteration of the collection.

Return type:

Proxytype

Example

>>> import descarteslabs.workflows as wf
>>> def add(accumulated, current):
...     return accumulated + current
>>> l = wf.List[wf.Int]([1, 2])
>>> reduced = l.reduce(add, initial=wf.Int(10))
>>> reduced.compute()  # doctest: +SKIP
13
sorted(key=None, reverse=False)[source]

Copy of this collection, sorted by a key function.

Parameters:
  • key (Function) – Function which takes an element and returns a value to sort by
  • reverse (Bool, default False) – Sorts in ascending order if False (default), descending if True.
class Dict(*dct, **kwargs)[source]

Proxy mapping, from keys of a specific type to values of a specific type.

Can be instantiated from a Python mapping and/or keyword arguments.

Examples

Methods

compute([geoctx, timeout, block, …]) Compute this proxy object and wait for its result.
items()
keys()
publish([name, description, client]) Publish this proxy object as a Workflow.
values()
>>> from descarteslabs.workflows import Dict, List, Str, Int, Float
>>> Dict[Str, Int](a=1, b=2)
<descarteslabs.workflows.types.containers.dict_.Dict[Str, Int] object at 0x...>
>>> Dict[Str, Int]({'a': 1, 'b': 2}, b=100, c=3)
<descarteslabs.workflows.types.containers.dict_.Dict[Str, Int] object at 0x...>
>>> Dict[Str, List[Float]](a=[1.1, 2.2], b=[3.3])
<descarteslabs.workflows.types.containers.dict_.Dict[Str, List[Float]] object at 0x...>
compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **params)

Compute this proxy object and wait for its result.

Parameters:
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.
  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError if the timeout passes.
  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).
  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.
  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
  • **params (Proxytype) – Parameters under which to run the computation.
Returns:

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.common.workflows.containers.

Return type:

result

items()[source]
keys()[source]
publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters:
  • name (str, default "") – Name for the new Workflow
  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.
  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type:

Workflow

values()[source]
class List(iterable)[source]

Proxy sequence of any number of elements, all of the same type.

Can be instantiated from any Python iterable, or another List of the same type.

Examples

Methods

compute([geoctx, timeout, block, …]) Compute this proxy object and wait for its result.
contains(other) Contains is equivalient to the Python in operator.
filter(func) Filter elements from an iterable proxytype.
length() Length is equivalent to the Python len operator.
map(func) Map a function over an iterable proxytype.
publish([name, description, client]) Publish this proxy object as a Workflow.
reduce(func[, initial]) Reduce a collection of elements to a single element.
sorted([key, reverse]) Copy of this collection, sorted by a key function.
>>> from descarteslabs.workflows import List, Str, Int
>>> List[Str](["foo", "bar", "baz"])
<descarteslabs.workflows.types.containers.list_.List[Str] object at 0x...>
>>> List[List[Int]]([[1, 2], [-1], [10, 11, 12]])
<descarteslabs.workflows.types.containers.list_.List[List[Int]] object at 0x...>
compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **params)

Compute this proxy object and wait for its result.

Parameters:
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.
  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError if the timeout passes.
  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).
  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.
  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
  • **params (Proxytype) – Parameters under which to run the computation.
Returns:

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.common.workflows.containers.

Return type:

result

contains(other)

Contains is equivalient to the Python in operator.

Parameters:other (Proxytype) – A Proxytype or type that can be promoted to a Proxytype
Returns:A Bool Proxytype
Return type:Bool
filter(func)

Filter elements from an iterable proxytype.

Parameters:func (Python callable) – A function that takes a single argument and returns a Bool Proxytype.
Returns:A Proxytype of the same type having only the elements where func returns True.
Return type:Proxtype

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("sentinel-2:L1C")
>>> filtered = col.filter(lambda img: img.properties["date"].year == 2018)
length()

Length is equivalent to the Python len operator.

Returns:An Int Proxytype
Return type:Int
map(func)

Map a function over an iterable proxytype.

Parameters:func (Python callable) – A function that takes a single argument and returns another proxytype.
Returns:The return type is dependent on the func and the type of the element returned. For example, calling map over an ImageCollection with a function that returns the date of the Image will now be a List[Datetime].
Return type:Proxtype

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("sentinel-2:L1C")
>>> dates = col.map(lambda img: img.properties["date"])
>>> type(dates).__name__
'List[Datetime]'
publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters:
  • name (str, default "") – Name for the new Workflow
  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.
  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type:

Workflow

reduce(func, initial='__NO_INITIAL_REDUCE_VALUE__')

Reduce a collection of elements to a single element.

NOTE: Optimized reducers such as sum have been implemented for some classes.

Parameters:
  • func (Python callable) – A function where the left argument is the accumulated value (the result of the previous call to func) and the right argument is the next value from the iterable. The function should return a single proxtype.
  • initial (Proxytype, optional) – An optional proxtype to provide for the first iteration. If no value is provided, the first element will be used.
Returns:

The return value of func for the last iteration of the collection.

Return type:

Proxytype

Example

>>> import descarteslabs.workflows as wf
>>> def add(accumulated, current):
...     return accumulated + current
>>> l = wf.List[wf.Int]([1, 2])
>>> reduced = l.reduce(add, initial=wf.Int(10))
>>> reduced.compute()  # doctest: +SKIP
13
sorted(key=None, reverse=False)

Copy of this collection, sorted by a key function.

Parameters:
  • key (Function) – Function which takes an element and returns a value to sort by
  • reverse (Bool, default False) – Sorts in ascending order if False (default), descending if True.
class Struct(**kwargs)[source]

Proxy container with named fields of specific types, meant as a helper base class.

Can be instantiated from kwargs.

Notes

Methods

compute([geoctx, timeout, block, …]) Compute this proxy object and wait for its result.
publish([name, description, client]) Publish this proxy object as a Workflow.

Adding certain fields to subclasses of concrete Structs changes their behavior:

  • _doc (dict of str): Docstrings for struct fields. The keys must match keys in the typespec (though not all fields must be documented). Resulting docstrings are formatted like "{}: {}".format(return_type_name, given_docstring). If no docstring is given, the field getter will just be documented with its return type.
  • _constructor (str): Function name to use in graft for instantiation
  • _optional (set of str, or None): Optional field names for constructor
  • _read_only: (set of str, or None): Field names that can’t be given to constructor

Examples

>>> from descarteslabs.workflows import Struct, Str, Int
>>> MyStructType = Struct[{'str_field': Str, 'int_field': Int}]
>>> instance = MyStructType(str_field="foo", int_field=1)

As a base class:

class Foo(Struct[{'x': Int, 'y': Str}]):
    _doc = {
        'x': "the x field",
        'y': "a y field. derived from x.",
    }
    _constructor = "make_foo"
    _optional = {'x'}
    _read_only = {'y'}
compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **params)

Compute this proxy object and wait for its result.

Parameters:
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.
  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError if the timeout passes.
  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).
  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.
  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
  • **params (Proxytype) – Parameters under which to run the computation.
Returns:

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.common.workflows.containers.

Return type:

result

publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters:
  • name (str, default "") – Name for the new Workflow
  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.
  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type:

Workflow

class Tuple(iterable)[source]

Proxy sequence of a fixed number of elements of specific types.

Can be instantiated from any Python iterable.

Examples

Methods

compute([geoctx, timeout, block, …]) Compute this proxy object and wait for its result.
length()
publish([name, description, client]) Publish this proxy object as a Workflow.
>>> from descarteslabs.workflows import Tuple, Int, Float, Str, Bool
>>> Tuple[Int, Float]([1, 2.2])
<descarteslabs.workflows.types.containers.tuple_.Tuple[Int, Float] object at 0x...>
>>> Tuple[Str, Tuple[Int, Bool]](["foo", (1, True)])
<descarteslabs.workflows.types.containers.tuple_.Tuple[Str, Tuple[Int, Bool]] object at 0x...>
compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **params)

Compute this proxy object and wait for its result.

Parameters:
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.
  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError if the timeout passes.
  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).
  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.
  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
  • **params (Proxytype) – Parameters under which to run the computation.
Returns:

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.common.workflows.containers.

Return type:

result

length()[source]
publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters:
  • name (str, default "") – Name for the new Workflow
  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.
  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type:

Workflow

class KnownDict[source]

Mapping from specific keys to specific value types, with default type for unknown values.

Cannot be instantiated directly; meant to be used as an element type in a container, or ._cast to.

Examples

Methods

compute([geoctx, timeout, block, …]) Compute this proxy object and wait for its result.
publish([name, description, client]) Publish this proxy object as a Workflow.
>>> from descarteslabs.workflows import Float, Bool, Str, Int, Any
>>> from descarteslabs.workflows.types.containers import KnownDict
>>> kd_type = KnownDict[{'x': Float, 'y': Bool}, Str, Int]
>>> kd = Any({'x': 1, 'y': 2.2})._cast(kd_type)
>>> kd['x']  # Float
<descarteslabs.workflows.types.primitives.number.Float object at 0x...>
>>> kd['foo']  # Int
<descarteslabs.workflows.types.primitives.number.Int object at 0x...>
compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **params)

Compute this proxy object and wait for its result.

Parameters:
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.
  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError if the timeout passes.
  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).
  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.
  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
  • **params (Proxytype) – Parameters under which to run the computation.
Returns:

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.common.workflows.containers.

Return type:

result

publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters:
  • name (str, default "") – Name for the new Workflow
  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.
  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type:

Workflow

zip(*lists)[source]

Returns a List of Tuple, where each tuple contains the i-th element from each of the argument List. All arguments must be Proxytype List. The returned List is truncated in length to the length of the shortest argument sequence.