Datetimes

Classes:

Datetime(year[, month, day, hour, minute, …])

Proxy Datetime object, similar to Python’s datetime.

Timedelta([days, seconds, microseconds, …])

Proxy Timedelta object, similar to Python’s timedelta.

class Datetime(year, month=1, day=1, hour=0, minute=0, second=0, microsecond=0)[source]

Proxy Datetime object, similar to Python’s datetime.

Note: Datetimes are always in UTC.

Examples

>>> from descarteslabs.workflows import Datetime
>>> my_datetime = Datetime(year=2019, month=1, day=1)
>>> my_datetime
<descarteslabs.workflows.types.datetimes.datetime_.Datetime object at 0x...>
>>> my_datetime.compute() 
datetime.datetime(2019, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)
>>> my_datetime.year.compute() 
2019

Construct a Datetime from components. All parts are optional besides year.

Methods:

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

Compute a proxy object and wait for its result.

from_string(string)

Construct a Workflows Datetime from an ISO 8601-formatted string.

from_timestamp(seconds)

Construct a Workflows Datetime from a number of seconds since the Unix epoch (January 1, 1970, 00:00:00 (UTC)).

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

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

is_between(start, end[, inclusive])

Whether the datetime is between these start and end dates.

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

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

Attributes:

day

1 <= day <= number of days in the given month and year

hour

0 <= hour < 24

microsecond

0 <= microsecond < 1000000

minute

0 <= minute < 60

month

1 <= month <= 12

second

0 <= second < 60

year

1 <= year <= 9999

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.

classmethod from_string(string)[source]

Construct a Workflows Datetime from an ISO 8601-formatted string.

If there’s no timezone offset information in the string, it’s assumed to be UTC. If there is, it’s converted to UTC.

Parameters

string (Str) – An ISO 8601-formatted datetime string, such as 2018-03-22 or 2020-03-22T16:37:00Z.

Returns

Return type

Datetime

Example

>>> from descarteslabs.workflows import Datetime
>>> my_datetime = Datetime.from_string("2017-12-31")
>>> my_datetime.compute() 
datetime.datetime(2017, 12, 31, 0, 0, tzinfo=datetime.timezone.utc)
classmethod from_timestamp(seconds)[source]

Construct a Workflows Datetime from a number of seconds since the Unix epoch (January 1, 1970, 00:00:00 (UTC)).

Parameters

seconds (Int or Float) –

Returns

Return type

Datetime

Example

>>> from descarteslabs.workflows import Datetime
>>> my_datetime = Datetime.from_timestamp(1000)
>>> my_datetime.compute() 
datetime.datetime(1970, 1, 1, 0, 16, 40)
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

is_between(start, end, inclusive=True)[source]

Whether the datetime is between these start and end dates.

Parameters
  • start (Datetime) – Start date

  • end (Datetime) – End date

  • inclusive (Bool, optional, default True) –

    If True, equivalent to start <= self <= end

    If False, equivalent to start < self < end

Returns

Return type

Bool

Example

>>> import descarteslabs.workflows as wf
>>> dt = wf.Datetime(2019, 6, 1)
>>> dt.is_between("2019-01-01", "2020-01-01").compute()  
True
>>> dt.is_between("2019-06-01", "2020-07-01").compute()  
True
>>> dt.is_between("2019-06-01", "2020-07-01", inclusive=False).compute()  
False
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 day

1 <= day <= number of days in the given month and year

Type

Int

property hour

0 <= hour < 24

Type

Int

property microsecond

0 <= microsecond < 1000000

Type

Int

property minute

0 <= minute < 60

Type

Int

property month

1 <= month <= 12

Type

Int

property second

0 <= second < 60

Type

Int

property year

1 <= year <= 9999

Type

Int

class Timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)[source]

Proxy Timedelta object, similar to Python’s timedelta.

Examples

>>> from descarteslabs.workflows import Timedelta
>>> my_timedelta = Timedelta(days=10, minutes=100)
>>> my_timedelta
<descarteslabs.workflows.types.datetimes.timedelta.Timedelta object at 0x...>
>>> my_timedelta.compute() 
datetime.timedelta(days=10, seconds=6000)
>>> my_timedelta.total_seconds().compute() 
870000.0

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.

total_seconds()

The total number of seconds contained in the duration.

Attributes:

days

-999999999 <= days <= 999999999

microseconds

0 <= microseconds < 1000000

seconds

0 <= seconds < 3600*24 (the number of seconds in one day)

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

total_seconds()[source]

The total number of seconds contained in the duration.

Example

>>> from descarteslabs.workflows import Timedelta
>>> my_timedelta = Timedelta(minutes=30)
>>> my_timedelta.total_seconds().compute() 
1800.0
property days

-999999999 <= days <= 999999999

Type

Int

property microseconds

0 <= microseconds < 1000000

Type

Int

property seconds

0 <= seconds < 3600*24 (the number of seconds in one day)

Type

Int