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

Methods

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

Compute this 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([geoctx, format, file, timeout, client])

Quickly compute this 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([name, description, client])

Publish this proxy object as a Workflow.

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

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

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_string(string)[source]

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

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

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

Methods

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

Compute this proxy object and wait for its result.

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.

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)

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

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

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