awaredatetime 0.0.2
Drop-in replacement for timezone aware datetime objects
License: Apache 2.0
Keywords: python datetime timezone aware awaredatetime utc

.. image:: https://img.shields.io/travis/mangohealth/awaredatetime.svg
    :alt: Build Status
    :target: https://travis-ci.org/mangohealth/awaredatetime/
.. image:: https://img.shields.io/coveralls/mangohealth/awaredatetime.svg
    :alt: Code Coverage
    :target: https://coveralls.io/github/mangohealth/awaredatetime
.. image:: https://img.shields.io/pypi/v/awaredatetime.svg
    :alt: PyPi Version
    :target: https://pypi.python.org/pypi/awaredatetime/
.. image:: https://img.shields.io/pypi/pyversions/awaredatetime.svg
    :alt: Supported Python Versions
    :target: https://pypi.python.org/pypi/awaredatetime/
.. image:: https://img.shields.io/pypi/implementation/awaredatetime.svg
    :alt: Supported Python Implementations
    :target: https://pypi.python.org/pypi/awaredatetime

=============
awaredatetime
=============
| Module providing a timezone aware ``datetime.datetime`` compatible object.
| Supports CPython 2.6 - 3.5 and PyPy.

--------
Features
--------
- Drop-in replacement for ``datetime.datetime``
- Simple implementation that leverages the built-in ``datetime`` module as much as possible
- Excellent test coverage

----------
Motivation
----------
| ``datetime.datetime`` objects aren't aware by default.
| New projects should always use timezone aware ``datetime.datetime`` objects, but the Python standard library doesn't make that easy.
  ``AwareDatetime`` is here to help!
|
| You may also have existing code that needs to become timezone aware and migrating code to become timezone aware is tricky.
| Using ``AwareDatetime`` will help you track what code has been migrated to support timezone.

---------------------------
awaredatetime.AwareDatetime
---------------------------
A drop-in replacement for ``datetime.datetime`` that always provide timezone aware objects.

Example Usage
=============
.. code:: python

          >>> from awaredatetime import AwareDatetime
          >>> AwareDatetime(2016, 1, 1)
          AwareDatetime(2016, 1, 1, 0, 0, tzinfo=<UTC>)
          >>> import datetime
          >>> AwareDatetime.from_datetime(datetime.datetime(2016, 1, 1))
          AwareDatetime(2016, 1, 1, 0, 0, tzinfo=<UTC>)
          >>>

-----------------------
awaredatetime.AwareTime
-----------------------
| Not implemented since times with a timezone don't make sense.
| e.g. What's the expected behavior for coverting ``24:00:00+00:00`` to positive UTC offset?

============
Dependencies
============
The only dependency is ``pytz``. We recommend that you use the latest version of ``pytz``, but this package will not force that upon you.

=======================
Migrating Existing Code
=======================


============
Similar work
============
- `datetime_tz`_
  - Another timezone aware drop-in replacement for the ``datetime`` module, but overrides more datetime behavior
- `arrow`_
  - An API-compatible re-write of the ``datetime`` module

.. _`datetime_tz`: https://github.com/mithro/python-datetime-tz
.. _`arrow`: https://github.com/crsmithdev/arrow

============
Contributing
============

----------
Guidelines
----------
- Do not change the CHANGELOG file or ``__version__`` in ``awaredatetime/__init__.py``. This is the responsibility of the repo and package owners.
- Before adding a dependency, open an `issue <https://github.com/mangohealth/awaredatetime/issues>`_ to discuss why the dependency is needed.
- Follow the `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html>`_.

-----
Steps
-----

#. Setup the development environment

   .. code:: bash

             pip install -U -r requirements.dev.txt

#. Make your changes

#. Add unittests for your changes

#. Run tests, which will also check the coding style

   .. code:: bash

             coverage run --source=awaredatetime setup.py test_dev

#. Once tests pass, ensure that your changes have proper test coverage

   .. code:: bash

             coverage html && ls htmlcov/index.html

#. Open a `PR <https://github.com/mangohealth/awaredatetime/pulls>`_

=========
Changelog
=========

------------------
0.0.2 (2016-06-20)
------------------
- Change how package versioning is determined

------------------
0.0.1 (2016-06-20)
------------------
- Initial commit

  - AwareDatetime is compatible with all known datetime.datetime methods and constants