https://github.com/dgilland/zulu

A drop-in replacement for native Python datetimes that embraces UTC.
https://github.com/dgilland/zulu

date datetime python python3 time timedelta utc

Last synced: about 1 month ago
JSON representation

A drop-in replacement for native Python datetimes that embraces UTC.

• Host: GitHub
• URL: https://github.com/dgilland/zulu
• Owner: dgilland
• License: mit
• Created: 2016-07-18T03:09:07.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2023-11-20T16:30:45.000Z (about 1 year ago)
• Last Synced: 2024-11-28T23:17:08.969Z (about 2 months ago)
• Topics: date, datetime, python, python3, time, timedelta, utc
• Language: Python
• Homepage: https://zulu.readthedocs.io
• Size: 383 KB
• Stars: 60
• Watchers: 8
• Forks: 4
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.rst
  • Contributing: CONTRIBUTING.rst
  • License: LICENSE.rst
  • Authors: AUTHORS.rst

Awesome Lists containing this project

README

        
zulu

****

|version| |build| |coveralls| |license|

A drop-in replacement for native datetimes that embraces UTC

Links

=====

- Project: https://github.com/dgilland/zulu

- Documentation: https://zulu.readthedocs.io

- PyPI: https://pypi.python.org/pypi/zulu/

- Github Actions: https://github.com/dgilland/zulu/actions

Features

========

- All datetime objects converted and stored as UTC.

- Parses ISO8601 formatted strings and POSIX timestamps by default.

- Timezone representation applied only during string output formatting or when casting to native datetime object.

- Drop-in replacement for native datetime objects.

- Python 3.6+

Quickstart

==========

Install using pip:

::

    pip3 install zulu

.. code-block:: python

    import zulu

    zulu.now()

    # 

    dt = zulu.parse('2016-07-25T19:33:18.137493+00:00')

    # 

    dt = zulu.create(2016, 7, 25, 19, 33, 18, 137493)

    # 

    dt.isoformat()

    # '2016-07-25T19:33:18.137493+00:00'

    dt.timestamp()

    # 1469475198.137493

    dt.naive

    # datetime.datetime(2016, 7, 25, 19, 33, 18, 137493)

    dt.datetime

    # datetime.datetime(2016, 7, 25, 19, 33, 18, 137493, tzinfo=)

    dt.format('%Y-%m-%d')

    # 2016-07-25

    dt.format('YYYY-MM-dd')

    # 2016-07-25

    dt.format("E, MMM d, ''YY")

    # "Mon, Jul 25, '16"

    dt.format("E, MMM d, ''YY", locale='de')

    # "Mo., Juli 25, '16"

    dt.format("E, MMM d, ''YY", locale='fr')

    # "lun., juil. 25, '16"

    dt.shift(hours=-5, minutes=10)

    # 

    dt.replace(hour=14, minute=43)

    # 

    dt.start_of('day')

    # 

    dt.end_of('day')

    # 

    dt.span('hour')

    # (, )

    dt.time_from(dt.end_of('day'))

    # '4 hours ago'

    dt.time_to(dt.end_of('day'))

    # 'in 4 hours'

    list(zulu.range('hour', dt, dt.shift(hours=4)))

    # [Zulu [2016-07-25T19:33:18.137493+00:00]>,

    #  Zulu [2016-07-25T20:33:18.137493+00:00]>,

    #  Zulu [2016-07-25T21:33:18.137493+00:00]>,

    #  Zulu [2016-07-25T22:33:18.137493+00:00]>]

    list(zulu.span_range('minute', dt, dt.shift(minutes=4)))

    # [(Zulu [2016-07-25T19:33:00+00:00]>, Zulu [2016-07-25T19:33:59.999999+00:00]>),

    #  (Zulu [2016-07-25T19:34:00+00:00]>, Zulu [2016-07-25T19:34:59.999999+00:00]>),

    #  (Zulu [2016-07-25T19:35:00+00:00]>, Zulu [2016-07-25T19:35:59.999999+00:00]>),

    #  (Zulu [2016-07-25T19:36:00+00:00]>, Zulu [2016-07-25T19:36:59.999999+00:00]>)]

    zulu.parse_delta('1w 3d 2h 32m')

    # 

    zulu.parse_delta('2:04:13:02.266')

    # 

    zulu.parse_delta('2 days, 5 hours, 34 minutes, 56 seconds')

    # 

Why Zulu?

=========

Why zulu instead of `native datetimes `_:

- Zulu has extended datetime features such as ``parse()``, ``format()``, ``shift()``, and `python-dateutil`_ timezone support.

- Parses ISO8601 and timestamps by default without any extra arguments.

- Easier to reason about ``Zulu`` objects since they are only ever UTC datetimes.

- Clear delineation between UTC and other time zones where timezone representation is only applicable for display or conversion to native datetime.

- Supports more string parsing/formatting options using `Unicode date patterns`_ as well as ``strptime/strftime`` directives.

Why zulu instead of `Arrow`_:

- Zulu is a drop-in replacement for native datetimes (inherits from ``datetime.datetime``). No need to convert using ``arrow.datetime`` when you need a datetime (zulu is always a datetime).

- Stricter parsing to avoid silent errors. For example, one might expect ``arrow.get('02/08/1987', 'MM/DD/YY')`` to fail (input does not match format) but it gladly returns ``