Globus Timer#

class globus_sdk.TimerClient(*, environment: str | None = None, base_url: str | None = None, authorizer: GlobusAuthorizer | None = None, app_name: str | None = None, transport_params: dict[str, Any] | None = None)[source]#

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

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_job(data: TimerJob | dict[str, Any]) → 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#

The TimerJob class is used to set up request data to send to Timer for creating a recurring job. Currently only recurring transfers are supported. Thus, a TimerJob should not be initialized directly; use the TimerJob.from_transfer_data() method to construct one to start a Timer job to run a transfer. This will require having a TransferClient nstantiated first – see the Transfer service docs for details and examples.

class globus_sdk.TimerJob(callback_url: str, callback_body: dict[str, Any], start: datetime | str, interval: timedelta | int | None, *, name: str | None = None, stop_after: datetime | None = None, stop_after_n: int | None = None, scope: str | None = None)[source]#

Bases: PayloadWrapper

Class for specifying parameters used to create a job in the Timer service. Used as the data argument in create_job.

Timer operates through the Globus Automate API. Crucially, the callback_url parameter should always be the URL used to run an action provider.

Warning

Currently the only supported action provider for this is for Transfer. Thus, users should generally only use the from_transfer_data() method here. Any other usage is meant for internal purposes; proceed with caution!

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

classmethod from_transfer_data(transfer_data: TransferData | dict[str, Any], start: datetime | str, interval: timedelta | int | None, *, name: str | None = None, stop_after: datetime | None = None, stop_after_n: int | None = None, scope: str | None = None, environment: str | None = None) → TimerJob[source]#

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.