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[, return_type])

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(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

>>> from descarteslabs.workflows import Bool, Int, Float, Function
>>> @Function.from_callable
... def pow(base: Int, exp: Float) -> Float:
...     return base ** exp
>>> print(pow)
<descarteslabs.workflows.types.function.function.Function[Int, Float, {}, Float] object at 0x...>
>>> 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, return_type=None)[source]

Construct a Workflows Function from a Python callable.

You must specify the types of arguments the function takes. If the function has type annotations (preferable), from_callable can be used as a decorator:

@wf.Function.from_callable
def my_function(x: wf.Int, y: wf.Image) -> wf.ImageCollection:
    ...

Otherwise, the argument types must be passed to from_callable.

Parameters
  • func (Python callable) –

  • *arg_types (Proxytype, optional) – 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, func must have type annotations for all of its arguments. If func has type annotations, but arg_types are also given explicitly, then the annotations are ignored.

  • return_type (Proxytype, optional) – The type the function should return. If not given, and there is no return type annotation, the return type will be inferred from what the function actually returns when called.

Returns

Return type

Function

Example

>>> import descarteslabs.workflows as wf
>>> @wf.Function.from_callable  # types inferred from annotations
... def string_pow(base: wf.Str, exp: wf.Float) -> wf.Float:
...     return wf.Float(base) ** exp
>>> print(string_pow)
<descarteslabs.workflows.types.function.function.Function[Str, Float, {}, Float] object at 0x...>
>>> # or, passing Str and Float as the argument types explicitly:
>>> def string_pow(base, exp):
...     return wf.Float(base) ** exp
>>> wf_pow = Function.from_callable(string_pow, wf.Str, wf.Float, return_type=wf.Float)
>>> wf_pow
<descarteslabs.workflows.types.function.function.Function[Str, Float, {}, Float] object at 0x...>
>>> wf_pow("3", 2.0).inspect()  
9.0
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(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. 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 proxy_object. 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.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • 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

property arg_types
property kwarg_types
property return_type