Timezones in SPy
When you provide a SPy function with a “naive” datetime, SPy will interpret
it using SPy’s fallback timezone. This timezone is equal to the
spy.options.default_timezone option if it has been set, or otherwise the
current user’s preferred timezone as specified in their user profile.
The spy.options.default_timezone setting will only be used for naive
datetimes. SPy will always use the timezone specified in timezone-aware
datetimes, regardless of default_timezone.
Setting default timezone
You’ll need to set spy.options.default_timezone in each session you want to
use it in (this means in every notebook, or for every spy.login()
you call). This makes it easy to customize different notebooks to different
timezones, and to have consistent behavior of a shared
notebook across users.
You can use a place-based timezone, like US/Pacific or Africa/Johannesburg. These take into account the daylight savings settings of the timezone.
spy.options.default_timezone = 'US/Pacific'
SPy will validate your input to confirm that this is a recognized timezone. If your timezone is not recognized at first, it may only be supported under a different name, as some names are ambiguous and used for multiple timezones.
You can also use pytz.timezone:
spy.options.default_timezone = pytz.timezone('US/Pacific')
You can use pytz to see supported timezones: pytz.all_timezones or
pytz.common_timezones return lists of supported timezones or
common supported timezones.
When specifying timezones, be aware of daylight savings changes:
2020-01-01 00:00:00 EST is 2020-01-01 00:00:00-05:00
2020-06-06 00:00:00 EST is 2020-06-06 00:00:00-04:00
If you want even more control over timezone, you can use
dateutil.tz.tzoffset. tzoffset lets you define your own timezone. This
is a fixed offset from UTC, so there won’t be any daylight savings handling.
tzoffset requires you to name your timezone and specify your offset from UTC
as a datetime.timedelta object. For example, to set the SPy default timezone
to UTC-08:00:
spy.options.default_timezone = dateutil.tz.tzoffset("my_tzoffset", datetime.timedelta(hours=-8))
In the datetime.timedelta object, remember to specify hours (or hours and
minutes in special timezone cases), and to specify whether your offset is
negative:
For this timezone |
use this datetime.timedelta object |
|---|---|
UTC-08:00 |
datetime.timedelta(hours=-8)
|
UTC+08:00 timezone |
datetime.timedelta(hours=8)
|
UTC-08:30 (both hours and minutes are negative) |
datetime.timedelta(hours=-8, minutes=-30)
|
UTC-07:30 timezone (minutes is positive) |
datetime.timedelta(hours=-8, minutes=30)
|
Also note that datetime.timedelta(-8) will create a UTC-(8 days) timezone.
Timezones in spy.pull()
SPy will interpret start and end (if naive) as the fallback timezone.
The status will display “Pull successful from … to …” as the start
and end times in whatever timezone SPy understood them to be in,
so that if you specify just 2020-01-01 00:00:00, you can see that
the pull interpretted that as being in your fallback timezone i.e.
2020-01-01 00:00:00{fallback offset}
Note that tz_convert does not apply to the start and end, only to the
results. If tz_convert is not specified, results will be in the same
timezone as start and/or end. For example, if you specify start and
end with timezone US/Pacific, results will have timestamps in timezone
US/Pacific. If you don’t specify a timezone for start and end,
results will have timestamps in your fallback timezone. If you provide a
datetime for only start or only end, the other will be calculated with
the same timezone as whichever was provided.
Timezones in spy.push()
Any naive datetimes will be interpretted as the fallback timezone. This includes
any naive datetimes in dataframes, as well as datetimes included in arguments,
e.g. the replace argument.
Timezones in spy.schedule()
Scheduling will be based on your fallback timezone, unless you specify in Quartz Cron syntax and include timezone in that specification.
The easiest way to specify a timezone for a schedule specification
is to set spy.options.default_timezone = '<Your timezone>' in
the notebook before running spy.schedule() as you normally would.