Globus Timer¶
Note
TimersClient
is also available under a legacy alias, TimerClient
.
- class globus_sdk.TimersClient(*, environment=None, base_url=None, app=None, app_scopes=None, authorizer=None, app_name=None, transport_params=None)[source]¶
Bases:
BaseClient
Client for the Globus Timer API.
Methods
- scopes: ScopeBuilder | None = <globus_sdk.scopes.builder.ScopeBuilder object>¶
the scopes for this client may be present as a
ScopeBuilder
- add_app_transfer_data_access_scope(collection_ids)[source]¶
Add a dependent
data_access
scope for one or more givencollection_ids
to this client’sGlobusApp
, under the Transferall
scope. Useful for preventingConsentRequired
errors when creating timers that use Globus Connect Server mapped collection(s) as the source or destination.Warning
This method must only be used on
collection_ids
for non-High-Assurance GCS Mapped Collections.Use on other collection types, e.g., on GCP Mapped Collections or any form of Guest Collection, will result in “Unknown Scope” errors during the login flow.
Returns
self
for chaining.Raises
GlobusSDKUsageError
if this client was not initialized with an app.- Parameters:
collection_ids (UUID | str | Iterable[UUID | str]) – a collection ID or an iterable of IDs.
- Return type:
app = UserApp("myapp", client_id=NATIVE_APP_CLIENT_ID) client = TimersClient(app=app).add_app_transfer_data_access_scope(COLLECTION_ID) transfer_data = TransferData( source_endpoint=COLLECTION_ID, destination_endpoint=COLLECTION_ID ) transfer_data.add_item("/staging/", "/active/") daily_timer = TransferTimer( name="test_timer", schedule=RecurringTimerSchedule(24 * 60 * 60), body=transfer_data ) client.create_timer(daily_timer)
- list_jobs(*, query_params=None)[source]¶
GET /jobs/
- Parameters:
query_params (dict[str, Any] | None) – additional parameters to pass as query params
- Return type:
Examples
>>> timer_client = globus_sdk.TimersClient(...) >>> jobs = timer_client.list_jobs()
- get_job(job_id, *, query_params=None)[source]¶
GET /jobs/<job_id>
- Parameters:
- Return type:
Examples
>>> timer_client = globus_sdk.TimersClient(...) >>> job = timer_client.get_job(job_id) >>> assert job["job_id"] == job_id
- create_timer(timer)[source]¶
- Parameters:
timer (dict[str, Any] | TransferTimer) – a document defining the new timer
- Return type:
A
TransferTimer
object can be constructed from aTransferData
object, which is the recommended way to create a timer for data transfers.Examples
>>> transfer_client = TransferClient(...) >>> transfer_data = TransferData(transfer_client, ...) >>> timer_client = globus_sdk.TimersClient(...) >>> create_doc = globus_sdk.TransferTimer( ... name="my-timer", ... schedule={"type": "recurring", "interval": 1800}, ... body=transfer_data, ... ) >>> response = timer_client.create_timer(timer=create_doc)
{ "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": "f906b04c-985b-11ef-a15a-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": "f906b0d8-985b-11ef-a15a-0242ac110002", "store_base_path_info": false, "verify_checksum": true }, "inactive_reason": null, "job_id": "f906af2a-985b-11ef-a15a-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" } }
POST /v2/timer
- create_job(data)[source]¶
POST /jobs/
- Parameters:
data (dict[str, Any] | TimerJob) – a timer document used to create the new timer (“job”)
- Return type:
Examples
>>> from datetime import datetime, timedelta >>> transfer_client = TransferClient(...) >>> transfer_data = TransferData(transfer_client, ...) >>> timer_client = globus_sdk.TimersClient(...) >>> 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, data)[source]¶
PATCH /jobs/<job_id>
- Parameters:
- Return type:
Examples
>>> timer_client = globus_sdk.TimersClient(...) >>> timer_client.update_job(job_id, {"name": "new name}"})
- delete_job(job_id)[source]¶
DELETE /jobs/<job_id>
- Parameters:
- Return type:
Examples
>>> timer_client = globus_sdk.TimersClient(...) >>> timer_client.delete_job(job_id)
- pause_job(job_id)[source]¶
Make a timer job inactive, preventing it from running until it is resumed.
- Parameters:
- Return type:
Examples
>>> timer_client = globus_sdk.TimersClient(...) >>> timer_client.pause_job(job_id)
- resume_job(job_id, *, update_credentials=None)[source]¶
Resume an inactive timer job, optionally replacing credentials to resolve issues with insufficient authorization.
- Parameters:
update_credentials (bool | None) – 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.
- Return type:
Examples
>>> timer_client = globus_sdk.TimersClient(...) >>> timer_client.resume_job(job_id)
Helper Objects¶
A helper is provided for constructing Transfer Timers:
- class globus_sdk.TransferTimer(*, name=MISSING, schedule, body)[source]¶
Bases:
PayloadWrapper
A helper for defining a payload for Transfer Timer creation. Use this along with
create_timer
to create a timer.Note
TimersClient
has two methods for creating timers,create_timer
andcreate_job
.create_job
uses a different API – onlycreate_timer
will work with this helper class.Users are strongly recommended to use
create_timer
and this helper for timer creation.- Parameters:
name (str | MissingType) – A name to identify this timer
schedule (dict[str, t.Any] | RecurringTimerSchedule | OnceTimerSchedule) – The schedule on which the timer runs
body (dict[str, t.Any] | TransferData) – A transfer payload for the timer to use. If it includes
submission_id
orskip_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. Aschedule
is specified as a dict, but the SDK provides two useful helpers for constructing these data.Example Schedules
schedule = OnceTimerSchedule()
schedule = OnceTimerSchedule(datetime="2023-09-22T00:00:00Z")
schedule = RecurringTimerSchedule( interval_seconds=300, end={"condition": "time", "datetime": "2023-10-01T00:00:00Z"}, )
schedule = RecurringTimerSchedule( interval_seconds=1800, end={"condition": "iterations", "iterations": 10}, )
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=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 | dt.datetime | MissingType) – 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, start=MISSING, end=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 | dt.datetime | MissingType) – 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[str, t.Any] | MissingType) – 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 thedatetime
value can be expressed as a pythondatetime
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.
- class globus_sdk.TimerJob(callback_url, callback_body, start, interval, *, name=None, stop_after=None, stop_after_n=None, scope=None)[source]¶
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 Timers service. Used as the
data
argument increate_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 Timers job will use.
callback_body (dict[str, t.Any]) – JSON data which Timers will send to the Action Provider on each invocation
start (dt.datetime | str) – The datetime at which to start the Timers job.
interval (dt.timedelta | int | None) – The interval at which the Timers 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 | None) – A (not necessarily unique) name to identify this job in Timers
stop_after (dt.datetime | None) – A date after which the Timers job will stop running
stop_after_n (int | None) – A number of executions after which the Timers job will stop
scope (str | None) – Timers defaults to the Transfer ‘all’ scope. Use this parameter to change the scope used by Timers when calling the Transfer Action Provider.
Methods
- classmethod from_transfer_data(transfer_data, start, interval, *, name=None, stop_after=None, stop_after_n=None, scope=None, environment=None)[source]¶
Specify data to create a Timers job using the parameters for a transfer. Timers will use those parameters to run the defined transfer operation, recurring at the given interval.
- Parameters:
transfer_data (TransferData | dict[str, Any]) – A
TransferData
object. Construct this object exactly as you would normally; Timers will use this to run the recurring transfer.start (datetime | str) – The datetime at which to start the Timers job.
interval (timedelta | int | None) – The interval at which the Timers 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 | None) – A (not necessarily unique) name to identify this job in Timers
stop_after (datetime | None) – A date after which the Timers job will stop running
stop_after_n (int | None) – A number of executions after which the Timers job will stop
scope (str | None) – Timers defaults to the Transfer ‘all’ scope. Use this parameter to change the scope used by Timers when calling the Transfer Action Provider.
environment (str | None) – For internal use: because this method needs to generate a URL for the Transfer Action Provider, this argument can control which environment the Timers job is sent to.
- Return type:
Client Errors¶
When an error occurs on calls to the Timers service, a TimersClient
will raise a TimersAPIError
.
Note
TimersAPIError
is also available under a legacy alias, TimerAPIError
.
- class globus_sdk.TimersAPIError(r, *args, **kwargs)[source]¶
Bases:
GlobusAPIError
Error class to represent error responses from Timers.
Has no particular additions to the base
GlobusAPIError
, but implements a different method for parsing error responses from Timers due to the differences between various error formats used.