Metadata-Version: 2.0
Name: Saturn
Version: 0.1
Summary: Functions for clean, easy datetime syntax; always tz-aware.
Home-page: https://github.com/David-OConnor/saturn
Author: David O'Connor
Author-email: david.alan.oconnor@gmail.com
License: Apache 2.0
Keywords: datetime,pytz,timezone,tzinfo
Platform: UNKNOWN
Requires-Dist: pytz (>=2016.3)

Saturn: Simple functions for tz-aware datetimes
===============================================

Performs common operations on datetimes with clean syntax, acting as a thin wrapper
for datetime and pytz. Force timezone-aware
datetimes. All operations are top-level functions: No dealing with
a methods from multiple modules and objects.

There are several existing modules designed to improve Python's datetime functionality.
Here's why Saturn is different:

 - Uses native datetime.datetime and datetime.timedelta types for compatibility and speed
 - Only one import required
 - Clean, intuitive syntax and function names.  No boilerplate.
 - Operates exclusively with top-level functions; no sorting through methods
   from multiple objects and modules

Saturn uses Pytz for timezones. Used as a dependency.:
`Pytz website <https://pypi.python.org/pypi/pytz/>`_
Pytz is licensed under the MIT license.

... and uses code from Arrow for string formatting and parsing. Not a dependency.:
`Arrow website: <http://arrow.readthedocs.io/en/latest/>`_
Arrow is licensed under Apache 2.

Python 2 is unsupported.

Included functions
------------------

 - datetime: Return a timezone-aware datetime.datetime object.  Created the same way as datetime.datetime,
   with an optional 'tz' argument for a timezone string. Defaults to UTC.
 - time: Same concept as datimetime; easily create a tz-aware time.
 - now: Find current utc time; timezone-aware.
 - range_dt: Iterate over datetimes, with a customizable interval. Similar to builtin range. Lazy.
 - fix_naive: Convert a timezone-naive datetime to an aware one.
 - move_tz: Change a datetime from one timezone to another.
 - combine: Similar to datetime.datetime.combine, but always tz-aware.
 - to_str: Similar to datetime.datetime.strftime, but with a cleaner format string, from Arrow.
 - from_str: Similar to datetime.datetime.strptime, but with a cleaner format string, from Arrow.
 - to_iso: Wrapper for datetime.datetime's isoformat() method, as a function.
 - from_iso: Create a datetime from an isoformat string.
 - timedelta and date are included as wrappers for their respective datetime classes, so you don't need to import datetime.


Installation
------------

.. code-block:: python

    pip install saturn


Basic documentation
-------------------

Create a timezone-aware datetime. If you don't specify a 'tz' argument, it defaults
to UTC. Works for times too:

.. code-block:: python

    saturn.datetime(2016, 1, 1, 16, tz='US/Eastern')
    # datetime.datetime(2016, 1, 1, 16, 0, tzinfo=<DstTzInfo 'US/Eastern' EST-1 day, 19:00:00 STD>)

    saturn.datetime(2016, 1, 1, 16)
    # datetime.datetime(2016, 1, 1, 16, 0, tzinfo=<UTC>)

    saturn.time(11, 29, 30)
    datetime.time(11, 29, 30, tzinfo=<UTC>)


Make a tz-naive datetime aware:

.. code-block:: python

    naive = datetime.datetime(2016, 1, 1)
    saturn.fix_naive(naive, "Pacific/Midway")
    # datetime.datetime(2016, 1, 1, 0, 0, tzinfo=<DstTzInfo 'Pacific/Midway' SST-1 day, 13:00:00 STD>)


Find the current datetime, in UTC:

.. code-block:: python

    saturn.now()
    # datetime.datetime(2016, 4, 29, 20, 36, 53, 257753, tzinfo=<UTC>)


Move from one timezone to another:

.. code-block:: python

    dt = saturn.datetime(2016,1,1, tz='Asia/Gaza')
    # datetime.datetime(2016, 1, 1, 0, 0, tzinfo=<DstTzInfo 'Asia/Gaza' EET+2:00:00 STD>)

    saturn.move_tz(dt, 'Europe/Vatican')
    # datetime.datetime(2015, 12, 31, 23, 0, tzinfo=<DstTzInfo 'Europe/Vatican' CET+1:00:00 STD>


Combine a date and time into a timezone-aware datetime. If the time is already aware, the 'tz' argument is ignored:

.. code-block:: python

    date, time = datetime.date(2016, 3, 2), datetime.time(16, 30)

    saturn.combine(date, time)
    # datetime.datetime(2016, 3, 2, 16, 30, tzinfo=<UTC>)

    saturn.combine(date, time, tz='Europe/London')
    # datetime.datetime(2016, 3, 2, 16, 30, tzinfo=<DstTzInfo 'Europe/London' GMT0:00:00 STD>)


Iterate through a range of datetimes. Valid intervals are 'week', 'month', 'day'
'hour', 'minute', 'second', 'millisecond', and 'microsecond':

.. code-block:: python

    start, end = saturn.datetime(2016, 1, 2, 12, 30), saturn.datetime(2016, 1, 5, 12, 30)
    for dt in saturn.range_dt(start, end, interval='day'):
        print(dt)

    # 2016-01-02 12:30:00+00:00
    # 2016-01-03 12:30:00+00:00
    # 2016-01-04 12:30:00+00:00

    for dt in saturn.range_dt(start, end, 4, interval='hour'):
        print(dt)

    # 2016-01-02 12:30:00+00:00
    # 2016-01-02 16:30:00+00:00
    # 2016-01-02 20:30:00+00:00
    ...
    # 2016-01-05 00:30:00+00:00
    # 2016-01-05 04:30:00+00:00
    # 2016-01-05 08:30:00+00:00


Convert a datetime a string. Uses format from Arrow:

.. code-block:: python

    saturn.to_str(saturn.now(), 'YYYY-MM-DD hh:mm')
    # '2016-04-29 03:30'


Convert a string to a datetime. Uses format from Arrow. If the string includes a timezone, the optional tz argument is ignored:

.. code-block:: python

    saturn.from_str('2016-04-29 03:30', 'YYYY-MM-DD hh:mm')
    # datetime.datetime(2016, 4, 29, 3, 30, tzinfo=<UTC>)

    saturn.from_str('2016-04-29 03:30', 'YYYY-MM-DD hh:mm', tz='Africa/Cairo')
    # datetime.datetime(2016, 4, 29, 3, 30, tzinfo=<DstTzInfo 'Africa/Cairo' EET+2:00:00 STD>)

    saturn.from_str('1381685817', 'X')
    # datetime.datetime(2013, 10, 13, 17, 36, 57, tzinfo=<UTC>)


Convert a datetime to an ISO-8601 string:

.. code-block:: python

        saturn.to_iso(saturn.now())
        # '2016-04-29T20:12:05.807558+00:00'

Convert an ISO-8601 string to a datetime:

.. code-block:: python

        saturn.from_iso('2016-04-29T20:12:05.000000+00:00')
        # datetime.datetime(2016, 4, 29, 20, 12, 05, tzinfo=<UTC>)


For details on to_str and from_str syntax, please reference `Arrow's formatting guide <http://arrow.readthedocs.io/en/latest/#tokens>`_.


Function input and output:
--------------------------

.. code-block:: python

    datetime(year: int, month: int, day: int, hour: int=0, minute: int=0,
             second: int=0, microsecond: int=0, tzinfo=None, tz=None) -> datetime.datetime

    time(hour: int=0, minute: int=0, second: int=0,
         microsecond: int = 0, tzinfo=None, tz=None) -> datetime.time

    now() -> datetime.datetime

    combine(_date: _datetime.date, _time: _datetime.time, tz: str='UTC') -> datetime.datetime

    fix_naive(dt: TimeOrDatetime, tz: str='UTC') -> datetime.datetime

    to_str(dt: DateOrDatetime, str_format: str) -> str

    from_str(dt_str: str, str_format: str, tz: str='UTC') -> datetime.datetime

    to_iso(dt: DateOrDatetime) -> str

    from_iso(iso_str: str, tz: str='UTC') -> _datetime.datetime

    move_tz(dt: datetime.datetime, tz: str) -> datetime.datetime:

    range_dt(start: DateOrDatetime, end: DateOrDatetime, step: int=1,
             interval: str='day') -> Iterator[datetime.datetime]



Some syntax we're dodging:
--------------------------


.. code-block:: python

        pytz.timezone('Europe/Berlin').localize(datetime.datetime(1985, 2, 1, 13, 21))

        arrow.Arrow(1999, 9, 9, 9, 30, tzinfo=dateutil.tz.gettz('US/Eastern'))

        pytz.timezone('US/Mountain').localize(datetime.datetime.combine(date, time))

        aware_dt.astimezone(pytz.timezone('US/Pacific'))




Replaced by:
------------


.. code-block:: python

        saturn.datetime(1985, 2, 1, 13, 21, tz='Europe/Berlin')

        saturn.datetime(1999, 9, 9, 9, 30, tz='US/Eastern')

        saturn.combine(date, time, 'US/Mountain')

        saturn.move_tz(aware_dt, 'US/Pacific')


