Primitives

Classes:

Any(value)

Represents a proxy object of an unknown type.

Bool(obj)

Proxy boolean.

NoneType(obj)

Proxy type(None).

Float(obj)

Proxy float.

Int(obj)

Proxy integer.

Number(obj)

Abstract base class for numeric Proxytypes.

Primitive(obj)

Proxy wrapper around a Python primitive type.

Str(obj)

Proxy string.

class Any(value)[source]

Represents a proxy object of an unknown type.

Any is most commonly encountered when accessing unknown fields from metadata (for example, image.properties["foobar"]). Any should generally be converted to the correct type with the cast method. However for convenience, Any also supports binary operators.

x = image.properties["x"]  # Any
y = image.properties["y"]  # Any
# either of these work; the first is better practice
result = x.cast(Int) + y.cast(Float)
result = x + y

Note that cast is simply changing the type representation in your client; the actual object on the backend isn’t changed. It’s up to you to cast to the correct Proxytype. At compute time, there is no check that you cast to the actual type that exists on the backend– though if you cast to the wrong type, subsequent operations will probably fail.

Any can also be constructed with any JSON-serializable value, or other ProxyType, though there is little reason to do this.

Examples

>>> from descarteslabs.workflows import Any, Int
>>> my_any = Any(2)
>>> my_int = my_any.cast(Int) # cast to an Int
>>> my_int
<descarteslabs.workflows.types.primitives.number.Int object at 0x...>
>>> my_int.compute() 
2
>>> from descarteslabs.workflows import Any, List, Int
>>> my_any = Any([1, 2, 3])
>>> my_list = my_any.cast(List[Int]) # cast to a list of ints
>>> my_list
<descarteslabs.workflows.types.containers.list_.List[Int] object at 0x...>
>>> my_list[0].compute() 
1
>>> from descarteslabs.workflows import Any, Int
>>> my_any = Any(2)
>>> other_any = Any(3)
>>> val = my_any * other_any
>>> val.cast(Int).compute() 
6

Methods:

cast(cls)

Convert this Any to another type.

compute([format, destination, file, …])

Compute a proxy object and wait for its result.

contains(other)

Contains is equivalient to the Python in operator.

inspect([format, file, cache, _ruster, …])

Quickly compute a proxy object using a low-latency, lower-reliability backend.

length()

Length is equivalent to the Python len operator.

publish(version[, title, description, …])

Publish a proxy object as a Workflow with the given version.

cast(cls)[source]

Convert this Any to another type.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters
  • geoctx (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.

  • format (Str or Dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None.

  • destination (str or dict, default "download") – The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (Int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError 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.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous compute requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information.

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.

Return type

Python object, bytes, or None

Raises

RetryError – Raised if there are too many failed retries. Inspect RetryError.exceptions to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more ResourceExhausted exceptions.

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 Boolean ProxyType

Return type

Boolean

Example

>>> from descarteslabs.workflows import Any
>>> Any([1, 2, 3]).contains(3).compute() 
True
>>> Any([1, 2, 3]).contains(5).compute() 
False
inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

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.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • cache (bool, default True) – Whether to use the cache for this job.

  • timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

length()[source]

Length is equivalent to the Python len operator.

Returns

An Int proxytype

Return type

Int

Example

>>> from descarteslabs.workflows import Any
>>> Any([5, 4, 3, 2, 1]).length().compute() 
5
publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters
  • id (Str) – ID for the new Workflow object. This should be of the form email:workflow_name and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (Str) – The version to be set, tied to the given obj. This should adhere to the semantic versioning schema.

  • title (Str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • labels (Dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (Str, default "") – The docstring for this version.

  • version_labels (Dict, optional) – Key-value pair labels to add to the version.

  • 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 or Function

class Bool(obj)[source]

Proxy boolean.

Note that this cannot be compared with Python’s and and or operators; you must use the bitwise operators & and |. Also note that more parenthesis are needed with bitwise operators than with and and or.

Examples

>>> from descarteslabs.workflows import Bool
>>> my_bool = Bool(True)
>>> my_bool
<descarteslabs.workflows.types.primitives.bool_.Bool object at 0x...>
>>> other_bool = Bool(False)
>>> val = my_bool | other_bool
>>> val.compute() 
True

Methods:

compute([format, destination, file, …])

Compute a proxy object and wait for its result.

inspect([format, file, cache, _ruster, …])

Quickly compute a proxy object using a low-latency, lower-reliability backend.

publish(version[, title, description, …])

Publish a proxy object as a Workflow with the given version.

Attributes:

literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters
  • geoctx (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.

  • format (Str or Dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (Int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError 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.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous compute requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information.

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.

Return type

Python object, bytes, or None

Raises

RetryError – Raised if there are too many failed retries. Inspect RetryError.exceptions to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more ResourceExhausted exceptions.

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

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.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • cache (bool, default True) – Whether to use the cache for this job.

  • timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters
  • id (Str) – ID for the new Workflow object. This should be of the form email:workflow_name and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (Str) – The version to be set, tied to the given obj. This should adhere to the semantic versioning schema.

  • title (Str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • labels (Dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (Str, default "") – The docstring for this version.

  • version_labels (Dict, optional) – Key-value pair labels to add to the version.

  • 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 or Function

property literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

class NoneType(obj)[source]

Proxy type(None).

Cannot be computed directly.

Examples

>>> from descarteslabs.workflows import NoneType
>>> NoneType(None)
<descarteslabs.workflows.types.primitives.none.NoneType object at 0x...>

Methods:

compute([format, destination, file, …])

Compute a proxy object and wait for its result.

inspect([format, file, cache, _ruster, …])

Quickly compute a proxy object using a low-latency, lower-reliability backend.

publish(version[, title, description, …])

Publish a proxy object as a Workflow with the given version.

Attributes:

literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters
  • geoctx (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.

  • format (Str or Dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (Int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError 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.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous compute requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information.

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.

Return type

Python object, bytes, or None

Raises

RetryError – Raised if there are too many failed retries. Inspect RetryError.exceptions to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more ResourceExhausted exceptions.

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

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.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • cache (bool, default True) – Whether to use the cache for this job.

  • timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters
  • id (Str) – ID for the new Workflow object. This should be of the form email:workflow_name and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (Str) – The version to be set, tied to the given obj. This should adhere to the semantic versioning schema.

  • title (Str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • labels (Dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (Str, default "") – The docstring for this version.

  • version_labels (Dict, optional) – Key-value pair labels to add to the version.

  • 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 or Function

property literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

class Float(obj)[source]

Proxy float.

Examples

>>> from descarteslabs.workflows import Float
>>> my_float = Float(2.3)
>>> my_float
<descarteslabs.workflows.types.primitives.number.Float object at 0x...>
>>> other_float = Float(5.6)
>>> val = my_float + other_float
>>> val.compute() 
7.9
>>> val = my_float > other_float
>>> val.compute() 
False

Methods:

compute([format, destination, file, …])

Compute a proxy object and wait for its result.

inspect([format, file, cache, _ruster, …])

Quickly compute a proxy object using a low-latency, lower-reliability backend.

publish(version[, title, description, …])

Publish a proxy object as a Workflow with the given version.

Attributes:

literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters
  • geoctx (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.

  • format (Str or Dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (Int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError 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.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous compute requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information.

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.

Return type

Python object, bytes, or None

Raises

RetryError – Raised if there are too many failed retries. Inspect RetryError.exceptions to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more ResourceExhausted exceptions.

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

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.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • cache (bool, default True) – Whether to use the cache for this job.

  • timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters
  • id (Str) – ID for the new Workflow object. This should be of the form email:workflow_name and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (Str) – The version to be set, tied to the given obj. This should adhere to the semantic versioning schema.

  • title (Str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • labels (Dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (Str, default "") – The docstring for this version.

  • version_labels (Dict, optional) – Key-value pair labels to add to the version.

  • 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 or Function

property literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

class Int(obj)[source]

Proxy integer.

Examples

>>> from descarteslabs.workflows import Int
>>> my_int = Int(2)
>>> my_int
<descarteslabs.workflows.types.primitives.number.Int object at 0x...>
>>> other_int = Int(5)
>>> val = my_int + other_int
>>> val.compute() 
7
>>> val = my_int < other_int
>>> val.compute() 
True

Methods:

compute([format, destination, file, …])

Compute a proxy object and wait for its result.

inspect([format, file, cache, _ruster, …])

Quickly compute a proxy object using a low-latency, lower-reliability backend.

publish(version[, title, description, …])

Publish a proxy object as a Workflow with the given version.

Attributes:

literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters
  • geoctx (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.

  • format (Str or Dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (Int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError 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.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous compute requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information.

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.

Return type

Python object, bytes, or None

Raises

RetryError – Raised if there are too many failed retries. Inspect RetryError.exceptions to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more ResourceExhausted exceptions.

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

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.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • cache (bool, default True) – Whether to use the cache for this job.

  • timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters
  • id (Str) – ID for the new Workflow object. This should be of the form email:workflow_name and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (Str) – The version to be set, tied to the given obj. This should adhere to the semantic versioning schema.

  • title (Str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • labels (Dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (Str, default "") – The docstring for this version.

  • version_labels (Dict, optional) – Key-value pair labels to add to the version.

  • 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 or Function

property literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

class Number(obj)[source]

Abstract base class for numeric Proxytypes.

Use the concrete subtypes Int and Float instead; Number cannot be instantiated and should only be used for isinstance() checks.

You can explicitly construct one numeric type from another, performing a cast (Int(Float(4.2))), but one numeric type will not implicitly promote to another (Int._promote(Float(4.2)) will fail).

Methods:

compute([format, destination, file, …])

Compute a proxy object and wait for its result.

inspect([format, file, cache, _ruster, …])

Quickly compute a proxy object using a low-latency, lower-reliability backend.

publish(version[, title, description, …])

Publish a proxy object as a Workflow with the given version.

Attributes:

literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters
  • geoctx (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.

  • format (Str or Dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (Int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError 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.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous compute requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information.

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.

Return type

Python object, bytes, or None

Raises

RetryError – Raised if there are too many failed retries. Inspect RetryError.exceptions to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more ResourceExhausted exceptions.

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

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.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • cache (bool, default True) – Whether to use the cache for this job.

  • timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters
  • id (Str) – ID for the new Workflow object. This should be of the form email:workflow_name and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (Str) – The version to be set, tied to the given obj. This should adhere to the semantic versioning schema.

  • title (Str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • labels (Dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (Str, default "") – The docstring for this version.

  • version_labels (Dict, optional) – Key-value pair labels to add to the version.

  • 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 or Function

property literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

class Primitive(obj)[source]

Proxy wrapper around a Python primitive type.

Do not use Primitive directly; instead, use one of the built-in subtypes (Int, Str, etc.)

Methods:

compute([format, destination, file, …])

Compute a proxy object and wait for its result.

inspect([format, file, cache, _ruster, …])

Quickly compute a proxy object using a low-latency, lower-reliability backend.

publish(version[, title, description, …])

Publish a proxy object as a Workflow with the given version.

Attributes:

literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters
  • geoctx (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.

  • format (Str or Dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (Int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError 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.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous compute requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information.

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.

Return type

Python object, bytes, or None

Raises

RetryError – Raised if there are too many failed retries. Inspect RetryError.exceptions to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more ResourceExhausted exceptions.

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

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.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • cache (bool, default True) – Whether to use the cache for this job.

  • timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters
  • id (Str) – ID for the new Workflow object. This should be of the form email:workflow_name and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (Str) – The version to be set, tied to the given obj. This should adhere to the semantic versioning schema.

  • title (Str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • labels (Dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (Str, default "") – The docstring for this version.

  • version_labels (Dict, optional) – Key-value pair labels to add to the version.

  • 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 or Function

property literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

class Str(obj)[source]

Proxy string.

Supports most of the same API as Python’s string type.

Examples

>>> from descarteslabs.workflows import Str
>>> my_str = Str("hello")
>>> my_str
<descarteslabs.workflows.types.primitives.string.Str object at 0x...>
>>> other_str = Str("world")
>>> val = my_str + " " + other_str
>>> val.compute() 
'hello world'
>>> val.upper().compute() 
'HELLO WORLD'
>>> val = val * 3
>>> val.compute() 
'hello worldhello worldhello world'

Methods:

capitalize()

Return a capitalized version of the string.

center(width[, fillchar])

Return a centered string of length width.

compute([format, destination, file, …])

Compute a proxy object and wait for its result.

contains(other)

Whether this string contains the given substring (returns Bool)

count(sub)

Return an Int of the number of non-overlapping occurrences of the substring sub in this string.

endswith(suffix)

Return True if S ends with the specified suffix, False otherwise.

expandtabs([tabsize])

Return a copy where all tab characters are expanded using spaces.

find(sub)

Return the lowest index in S where substring sub is found in this string.

format(*args, **kwargs)

Return a formatted version of S, using substitutions from args and kwargs.

inspect([format, file, cache, _ruster, …])

Quickly compute a proxy object using a low-latency, lower-reliability backend.

isalnum()

Return True if the string is an alpha-numeric string, False otherwise.

isalpha()

Return True if the string is an alphabetic string, False otherwise.

isdigit()

Return True if the string is a digit string, False otherwise.

islower()

Return True if the string is a lowercase string, False otherwise.

isspace()

Return True if the string is a whitespace string, False otherwise.

istitle()

Return True if the string is a title-cased string, False otherwise.

isupper()

Return True if the string is an uppercase string, False otherwise.

join(strings)

Concatenate a List[Str].

length()

The length of the string (returns Int)

ljust(width[, fillchar])

Return a left-justified string of length width.

lower()

Return a copy of the string converted to lowercase.

lstrip([chars])

Return a copy of the string with leading whitespace removed.

partition(sep)

Partition the string into three parts using the given separator.

publish(version[, title, description, …])

Publish a proxy object as a Workflow with the given version.

replace(old, new[, count])

Return a copy with all occurrences of substring old replaced by new.

rfind(sub)

Return the highest index in S where substring sub is found.

rjust(width[, fillchar])

Return a right-justified string of length width.

rpartition(sep)

Partition the string into three parts using the given separator.

rsplit([sep, maxsplit])

Return a list of the words in the string, using sep as the delimiter string.

rstrip([chars])

Return a copy of the string with trailing whitespace removed.

split([sep, maxsplit])

Return a List[Str] of the words in the string, using sep as the delimiter string.

splitlines()

Return a List[Str] of the lines in the string, breaking at line boundaries.

startswith(prefix)

Return True if S starts with the specified prefix, False otherwise.

strip([chars])

Return a copy of the string with leading and trailing whitespaces removed.

swapcase()

Convert uppercase characters to lowercase and lowercase characters to uppercase.

title()

Return a version of the string where each word is titlecased.

upper()

Return a copy of the string converted to uppercase.

zfill(width)

Pad a numeric string with zeros on the left, to fill a field of the given width.

Attributes:

literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

capitalize()[source]

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").capitalize().compute() 
'Hello'
center(width, fillchar=' ')[source]

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").center(9).compute() 
'  hello  '
compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters
  • geoctx (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.

  • format (Str or Dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (Int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError 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.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous compute requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information.

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.

Return type

Python object, bytes, or None

Raises

RetryError – Raised if there are too many failed retries. Inspect RetryError.exceptions to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more ResourceExhausted exceptions.

contains(other)[source]

Whether this string contains the given substring (returns Bool)

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").contains("o").compute() 
True
count(sub)[source]

Return an Int of the number of non-overlapping occurrences of the substring sub in this string.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").count("l").compute() 
2
endswith(suffix)[source]

Return True if S ends with the specified suffix, False otherwise.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").endswith("o").compute() 
True
expandtabs(tabsize=8)[source]

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello  ").expandtabs().compute() 
'hello   '
find(sub)[source]

Return the lowest index in S where substring sub is found in this string.

Return -1 on failure.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").find("l").compute() 
2
format(*args, **kwargs)[source]

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{‘ and ‘}’).

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello {}").format("world").compute() 
'hello world'
inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

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.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • cache (bool, default True) – Whether to use the cache for this job.

  • timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **arguments (Any) – Values for all parameters that obj depends on (or arguments that obj takes, if it’s a Function). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

isalnum()[source]

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").isalnum().compute() 
True
isalpha()[source]

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").isalpha().compute() 
True
isdigit()[source]

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

Example

>>> from descarteslabs.workflows import Str
>>> Str("3").isdigit().compute() 
True
islower()[source]

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").islower().compute() 
True
isspace()[source]

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

Example

>>> from descarteslabs.workflows import Str
>>> Str(" ").isspace().compute() 
True
istitle()[source]

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

Example

>>> from descarteslabs.workflows import Str
>>> Str("Hello World").istitle().compute() 
True
isupper()[source]

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

Example

>>> from descarteslabs.workflows import Str
>>> Str("HELLO").isupper().compute() 
True
join(strings)[source]

Concatenate a List[Str].

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example

>>> from descarteslabs.workflows import Str
>>> Str(".").join(['ab', 'pq']).compute() 
'ab.pq'
length()[source]

The length of the string (returns Int)

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").length().compute() 
5
ljust(width, fillchar=' ')[source]

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").ljust(6).compute() 
'hello '
lower()[source]

Return a copy of the string converted to lowercase.

Example

>>> from descarteslabs.workflows import Str
>>> Str("HELLO").lower().compute() 
'hello'
lstrip(chars=None)[source]

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

Example

>>> from descarteslabs.workflows import Str
>>> Str("  hello ").lstrip().compute() 
'hello '
partition(sep)[source]

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a Tuple[Str, Str, Str] containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a Tuple[Str, Str, Str] containing the original string and two empty strings.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").partition("e").compute() 
('h', 'e', 'llo')
publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters
  • id (Str) – ID for the new Workflow object. This should be of the form email:workflow_name and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (Str) – The version to be set, tied to the given obj. This should adhere to the semantic versioning schema.

  • title (Str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • labels (Dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (Str, default "") – The docstring for this version.

  • version_labels (Dict, optional) – Key-value pair labels to add to the version.

  • 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 or Function

replace(old, new, count=-1)[source]

Return a copy with all occurrences of substring old replaced by new. If the optional argument count is given, only the first count occurrences are replaced.

Parameters
  • old (Str) – Substring to replace

  • new – Replacement substring

  • count (Int) – Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").replace("e", "a").compute() 
'hallo'
rfind(sub)[source]

Return the highest index in S where substring sub is found.

Return -1 on failure.

Parameters

sub (Str) – Substring to find

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").rfind("l").compute() 
3
rjust(width, fillchar=' ')[source]

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

Parameters
  • width (Int) – Total length of resulting padded string

  • fillchar (Str) – Character to pad string with

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").rjust(9).compute() 
'    hello'
rpartition(sep)[source]

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

Parameters

sep (Str) – String to partition on

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").rpartition("l").compute() 
('hel', 'l', 'o')
rsplit(sep=None, maxsplit=-1)[source]

Return a list of the words in the string, using sep as the delimiter string.

Parameters
  • sep (Str) – The delimiter according which to split the string. None (the default value) means split according to any whitespace, and discard empty strings from the result.

  • maxsplit (Int) – Maximum number of splits to do. -1 (the default value) means no limit.

  • are done starting at the end of the string and working to the front. (Splits) –

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").rsplit("l").compute() 
['he', '', 'o']
rstrip(chars=None)[source]

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

Parameters

chars (Str, optional) – Characters to remove

Example

>>> from descarteslabs.workflows import Str
>>> Str(" hello  ").rstrip().compute() 
' hello'
split(sep=None, maxsplit=-1)[source]

Return a List[Str] of the words in the string, using sep as the delimiter string.

Parameters
  • sep (Str, optional) – The delimiter according which to split the string. None (the default value) means split according to any whitespace, and discard empty strings from the result.

  • maxsplit (Int, optional) – Maximum number of splits to do. -1 (the default value) means no limit.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").split("e").compute() 
['h', 'llo']
splitlines()[source]

Return a List[Str] of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting strings.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello\nworld").splitlines().compute() 
['hello', 'world']
startswith(prefix)[source]

Return True if S starts with the specified prefix, False otherwise.

Parameters

prefix (Str) – Prefix string

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").startswith("h").compute() 
True
strip(chars=None)[source]

Return a copy of the string with leading and trailing whitespaces removed.

If chars is given and not None, remove characters in chars instead.

Parameters

chars (Str, optional) – Optional characters to remove

Example

>>> from descarteslabs.workflows import Str
>>> Str("  hello  ").strip().compute() 
'hello'
swapcase()[source]

Convert uppercase characters to lowercase and lowercase characters to uppercase.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").swapcase().compute() 
'HELLO'
title()[source]

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello world").title().compute() 
'Hello World'
upper()[source]

Return a copy of the string converted to uppercase.

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").upper().compute() 
'HELLO'
zfill(width)[source]

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

Parameters

width (Int) – Total length of resulting padded string

Example

>>> from descarteslabs.workflows import Str
>>> Str("hello").zfill(9).compute() 
'0000hello'
property literal_value

Python literal value this proxy object was constructed with, or None if not constructed from a literal value.