****************
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.

.. code:: ipython3

    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``: 

.. code:: ipython3

    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:

.. code:: text

    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:

.. code:: ipython3

    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:

.. list-table:: 
   :widths: 30 70 
   :header-rows: 1

   * - For this timezone
     - use this datetime.timedelta object
   * - UTC-08:00
     - .. code:: ipython3
         
         datetime.timedelta(hours=-8)

   * - UTC+08:00 timezone 
     - .. code:: ipython3
         
         datetime.timedelta(hours=8)

   * - UTC-08:30 (both hours and minutes are negative)
     - .. code:: ipython3
         
         datetime.timedelta(hours=-8, minutes=-30)
         
   * - UTC-07:30 timezone (minutes is positive)
     - .. code:: ipython3
         
         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.