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 timezone


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.

Timezones in shared documents

In shared documents, specifying spy.options.default_timezone can standardize behavior between users. If spy.options.default_timezone is not set, then SPy may have different outputs for different users based on their timezone settings.