Function

Classes

Function(function)

Function[arg_type, ..., {kwarg: type, ...}, return_type]: Proxy function with args, kwargs,

class Function(function)[source]

Function[arg_type, ..., {kwarg: type, ...}, return_type]: Proxy function with args, kwargs, and return values of specific types.

Can be instantiated from any Python callable or string function name.

Examples

Attributes

arg_types

kwarg_types

return_type

Methods

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

Compute this proxy object and wait for its result.

from_callable(func, *arg_types)

Construct a Workflows Function from a Python callable.

inspect([geoctx, format, file, timeout, client])

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

publish([name, description, client])

Publish this proxy object as a Workflow.

>>> from descarteslabs.workflows import Bool, Int, Float, Function
>>> func_type = Function[Int, {}, Int] # function with Int arg, no kwargs, returning an Int
>>> func_type = Function[Int, {'x': Float}, Bool] # function with Int arg, kwarg 'x' of type Float, returning a Bool
>>> func_type = Function[{}, Int] # zero-argument function, returning a Int
>>> from descarteslabs.workflows import Function, Int
>>> func = Function[Int, Int, {}, Int](lambda x, y: x + y) # function taking two Ints and adding them together
>>> func
<descarteslabs.workflows.types.function.function.Function[Int, Int, {}, Int] object at 0x...>
>>> func(3, 4).compute() 
7
compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **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.

  • 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.

  • 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

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

  • **params (Proxytype) – Parameters under which to run the computation.

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

classmethod from_callable(func, *arg_types)[source]

Construct a Workflows Function from a Python callable.

Parameters
  • func (Python callable) –

  • *arg_types (ProxyType) – For each parameter of func, the type that it should accept. The number of argument types given much match the number of arguments func actually accepts. If not given, the number of parameters is inferred from the function’s signature, and Any is the type used for each.

Returns

Return type

Function

Example

>>> from descarteslabs.workflows import Function, Int, Image
>>> my_img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> def my_add(x, y):
...     return x + y # function taking two values and adding them together
>>> my_func = Function.from_callable(my_add, Image, Int) # Image and Int are the argument types
>>> my_func
<descarteslabs.workflows.types.function.function.Function[Image, Int, {}, Image] object at 0x...>
>>> my_func(my_img, 10).compute(my_geoctx) # my_geoctx is an arbitrary geocontext for 'img' 
ImageResult:
...
inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this 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.

  • timeout (int, optional, default 30) – 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

  • **params (Proxytype) – Parameters under which to run the computation.

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(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

property arg_types
property kwarg_types
property return_type