Globus Timer#

Bases: BaseClient

Client for the Globus Timer API.

Parameters:

authorizer (GlobusAuthorizer) – An authorizer instance used for all calls to Timer
app_name (str) – Optional “nice name” for the application. Has no bearing on the semantics of client actions. It is just passed as part of the User-Agent string, and may be useful when debugging issues with the Globus team
transport_params (dict) – Options to pass to the transport for this client

Methods

create_job()
create_timer()
delete_job()
get_job()
list_jobs()
pause_job()
resume_job()
update_job()

scopes: ScopeBuilder | None = <globus_sdk.scopes.builder.ScopeBuilder object>#: the scopes for this client may be present as a ScopeBuilder

list_jobs(*, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse[source]#

GET /jobs/

Parameters:: query_params (dict, optional) – additional parameters to pass as query params

Examples

>>> timer_client = globus_sdk.TimerClient(...)
>>> jobs = timer_client.list_jobs()

get_job(job_id: UUID | str, *, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse[source]#

GET /jobs/<job_id>

Parameters:

job_id (str or UUID) – the ID of the timer (“job”)
query_params (dict, optional) – additional parameters to pass as query params

Examples

>>> timer_client = globus_sdk.TimerClient(...)
>>> job = timer_client.get_job(job_id)
>>> assert job["job_id"] == job_id

create_timer(timer: dict[str, Any] | TransferTimer) → GlobusHTTPResponse[source]#

Parameters:: timer (dict or TransferTimer) – a document defining the new timer

A TransferTimer object can be constructed from a TransferData object, which is the recommended way to create a timer for data transfers.

Examples

Example Usage

>>> transfer_client = TransferClient(...)
>>> transfer_data = TransferData(transfer_client, ...)
>>> timer_client = globus_sdk.TimerClient(...)
>>> create_doc = globus_sdk.TransferTimer(
...     name="my-timer",
...     schedule={"type": "recurring", "interval": 1800},
...     body=transfer_data,
... )
>>> response = timer_client.create_timer(timer=create_doc)

Example Response Data

{
  "timer": {
    "body": {
      "DATA": [
        {
          "DATA_TYPE": "transfer_item",
          "destination_path": "/~/dst.txt",
          "source_path": "/share/godata/file1.txt"
        }
      ],
      "DATA_TYPE": "transfer",
      "delete_destination_extra": false,
      "destination_endpoint": "3e5e2006-7fe1-11ee-9622-0242ac110002",
      "encrypt_data": false,
      "fail_on_quota_errors": false,
      "notify_on_failed": true,
      "notify_on_inactive": true,
      "notify_on_succeeded": true,
      "preserve_timestamp": false,
      "skip_source_errors": false,
      "source_endpoint": "3e5e2092-7fe1-11ee-9622-0242ac110002",
      "store_base_path_info": false,
      "verify_checksum": true
    },
    "inactive_reason": null,
    "job_id": "3e5e1ed0-7fe1-11ee-9622-0242ac110002",
    "last_ran_at": null,
    "name": "Very Cool Timer",
    "next_run": "2023-10-27T05:00:00+00:00",
    "number_of_errors": 0,
    "number_of_runs": 0,
    "schedule": {
      "type": "recurring",
      "end": {
        "count": 2
      },
      "interval_seconds": 604800,
      "start": "2023-10-27T05:00:00+00:00"
    },
    "status": "new",
    "submitted_at": "2023-10-26T20:31:09+00:00"
  }
}

API Info

POST /v2/timer

create_job(data: dict[str, Any] | TimerJob) → GlobusHTTPResponse[source]#

POST /jobs/

Parameters:: data (dict or TimerJob) – a timer document used to create the new timer (“job”)

Examples

>>> from datetime import datetime, timedelta
>>> transfer_client = TransferClient(...)
>>> transfer_data = TransferData(transfer_client, ...)
>>> timer_client = globus_sdk.TimerClient(...)
>>> job = TimerJob.from_transfer_data(
...     transfer_data,
...     datetime.utcnow(),
...     timedelta(days=14),
...     name="my-timer-job"
... )
>>> timer_result = timer_client.create_job(job)

update_job(job_id: UUID | str, data: dict[str, Any]) → GlobusHTTPResponse[source]#

PATCH /jobs/<job_id>

Parameters:

job_id (str or UUID) – the ID of the timer (“job”)
data (dict) – a partial timer document used to update the job

Examples

>>> timer_client = globus_sdk.TimerClient(...)
>>> timer_client.update_job(job_id, {"name": "new name}"})

delete_job(job_id: UUID | str) → GlobusHTTPResponse[source]#

DELETE /jobs/<job_id>

Parameters:: job_id (str or UUID) – the ID of the timer (“job”)

Examples

>>> timer_client = globus_sdk.TimerClient(...)
>>> timer_client.delete_job(job_id)

pause_job(job_id: UUID | str) → GlobusHTTPResponse[source]#

Make a timer job inactive, preventing it from running until it is resumed.

Parameters:: job_id (str or UUID) – The ID of the timer to pause

Examples

>>> timer_client = globus_sdk.TimerClient(...)
>>> timer_client.pause_job(job_id)

resume_job(job_id: UUID | str, *, update_credentials: bool | None = None) → GlobusHTTPResponse[source]#

Resume an inactive timer job, optionally replacing credentials to resolve issues with insufficient authorization.

Parameters:

job_id (str or UUID) – The ID of the timer to resume
update_credentials (bool, optional) – When true, replace the credentials for the timer using the credentials for this resume call. This can be used to resolve authorization errors (such as session and consent errors), but it also could introduce session and consent errors, if the credentials being used to resume lack some necessary properties of the credentials they’re replacing. If not supplied, the Timers service will determine whether to replace credentials according to the reason why the timer job became inactive.

Examples

>>> timer_client = globus_sdk.TimerClient(...)
>>> timer_client.resume_job(job_id)

Helper Objects#

A helper is provided for constructing Transfer Timers:

class globus_sdk.TransferTimer(*, name: str | ~globus_sdk.utils.MissingType = <globus_sdk.MISSING>, schedule: dict[str, ~typing.Any] | ~globus_sdk.services.timer.data.RecurringTimerSchedule | ~globus_sdk.services.timer.data.OnceTimerSchedule, body: dict[str, ~typing.Any] | ~globus_sdk.services.transfer.data.transfer_data.TransferData)[source]#

Bases: PayloadWrapper

A helper for defining a payload for Transfer Timer creation. Use this along with create_timer to create a timer.

Note

TimerClient has two methods for creating timers, create_timer and create_job. create_job uses a different API – only create_timer will work with this helper class.

Users are strongly recommended to use create_timer and this helper for timer creation.

Parameters:

name (str, optional) – A name to identify this timer
schedule (dict) – The schedule on which the timer runs
body (dict or TransferData) – A transfer payload for the timer to use. If it includes submission_id or skip_activation_check, these parameters will be removed, as they are not supported in timers.

The schedule field determines when the timer will run. Timers may be “run once” or “recurring”, and “recurring” timers may specify an end date or a number of executions after which the timer will stop. A schedule is specified as a dict, but the SDK provides two useful helpers for constructing these data.

Example Schedules

Run Once, Right Now

schedule = OnceTimerSchedule()

Run Once, At a Specific Time

schedule = OnceTimerSchedule(datetime="2023-09-22T00:00:00Z")

Run Every 5 Minutes, Until a Specific Time

schedule = RecurringTimerSchedule(
    interval_seconds=300,
    end={"condition": "time", "datetime": "2023-10-01T00:00:00Z"},
)

Run Every 30 Minutes, 10 Times

schedule = RecurringTimerSchedule(
    interval_seconds=1800,
    end={"condition": "iterations", "iterations": 10},
)

Run Every 10 Minutes, Indefinitely

schedule = RecurringTimerSchedule(interval_seconds=600)

Using these schedules, you can create a timer from a TransferData object:

>>> from globus_sdk import TransferData, TransferTimer
>>> schedule = ...
>>> transfer_data = TransferData(...)
>>> timer = TransferTimer(
...     name="my timer",
...     schedule=schedule,
...     body=transfer_data,
... )

Submit the timer to the Timers service with create_timer.

In order to schedule a timer, pass a schedule with relevant parameters. This can be done using the two schedule helper classes

class globus_sdk.OnceTimerSchedule(datetime: str | ~datetime.datetime | ~globus_sdk.utils.MissingType = <globus_sdk.MISSING>)[source]#

Bases: PayloadWrapper

A helper used as part of a timer to define when the timer will run.

A OnceTimerSchedule is used to describe a timer which runs exactly once. It may be scheduled for a time in the future.

Parameters:: datetime (str or datetime.datetime, optional) – The time at which to run the timer, either as an ISO 8601 string with timezone information, or as a datetime.datetime object.

class globus_sdk.RecurringTimerSchedule(interval_seconds: int, start: str | ~datetime.datetime | ~globus_sdk.utils.MissingType = <globus_sdk.MISSING>, end: dict[str, ~typing.Any] | ~globus_sdk.utils.MissingType = <globus_sdk.MISSING>)[source]#

Bases: PayloadWrapper

A helper used as part of a timer to define when the timer will run.

A RecurringTimerSchedule is used to describe a timer which runs repeatedly until some end condition is reached.

Parameters:

interval_seconds (int) – The number of seconds between each run of the timer.
start (str or datetime.datetime, optional) – The time at which to start the timer, either as an ISO 8601 string with timezone information, or as a datetime.datetime object.
end (dict, optional) – The end condition for the timer, as a dict. This either expresses a number of iterations for the timer or an end date.

Example end conditions:

# run 10 times
end = {"condition": "iterations", "iterations": 10}

# run until a specific date
end = {"condition": "time", "datetime": "2023-10-01T00:00:00Z"}

If the end condition is time, then the datetime value can be expressed as a python datetime type as well, e.g.

# end in 10 days
end = {
    "condition": "time",
    "datetime": datetime.datetime.now() + datetime.timedelta(days=10),
}

TimerJob (legacy)#

The TimerJob class is still supported for creating timers, but it is not recommended. New users should prefer the TransferTimer class.

Bases: PayloadWrapper

Warning

This method of specifying and creating Timers for data transfer is now deprecated. Users should use TimerData instead.

TimerJob is still supported for non-transfer use-cases.

Helper for creating a timer in the Timer service. Used as the data argument in create_job.

The callback_url parameter should always be the URL used to run an action provider.

Parameters:

callback_url (str) – URL for the action which the Timer job will use.
callback_body (dict) – JSON data which Timer will send to the Action Provider on each invocation
start (datetime.datetime or str) – The datetime at which to start the Timer job.
interval (datetime.timedelta or int) – The interval at which the Timer job should recur. Interpreted as seconds if specified as an integer. If stop_after_n == 1, i.e. the job is set to run only a single time, then interval must be None.
name (str, optional) – A (not necessarily unique) name to identify this job in Timer
stop_after (datetime.datetime, optional) – A date after which the Timer job will stop running
stop_after_n (int) – A number of executions after which the Timer job will stop
scope (str, optional) – Timer defaults to the Transfer ‘all’ scope. Use this parameter to change the scope used by Timer when calling the Transfer Action Provider.

Methods

Specify data to create a Timer job using the parameters for a transfer. Timer will use those parameters to run the defined transfer operation, recurring at the given interval.

Parameters:

transfer_data (globus_sdk.TransferData) – A TransferData object. Construct this object exactly as you would normally; Timer will use this to run the recurring transfer.
start (datetime.datetime or str) – The datetime at which to start the Timer job.
interval (datetime.timedelta or int) – The interval at which the Timer job should recur. Interpreted as seconds if specified as an integer. If stop_after_n == 1, i.e. the job is set to run only a single time, then interval must be None.
name (str, optional) – A (not necessarily unique) name to identify this job in Timer
stop_after (datetime.datetime, optional) – A date after which the Timer job will stop running
stop_after_n (int) – A number of executions after which the Timer job will stop
scope (str, optional) – Timer defaults to the Transfer ‘all’ scope. Use this parameter to change the scope used by Timer when calling the Transfer Action Provider.
environment (str, optional) – For internal use: because this method needs to generate a URL for the Transfer Action Provider, this argument can control which environment the Timer job is sent to.

Client Errors#

When an error occurs, a TimerClient will raise specifically a TimerAPIError rather than just a GlobusAPIError.

class globus_sdk.TimerAPIError(r: Response, *args: Any, **kwargs: Any)[source]#

Bases: GlobusAPIError

Error class to represent error responses from Timer.

Has no particular additions to the base GlobusAPIError, but implements a different method for parsing error responses from Timer due to the differences between various error formats used.