Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sdispater/pendulum

Python datetimes made easy
https://github.com/sdispater/pendulum

date datetime python python3 time timezones

Last synced: 7 days ago
JSON representation

Python datetimes made easy

Awesome Lists containing this project

README 

        
Pendulum

########



.. image:: https://img.shields.io/pypi/v/pendulum.svg

    :target: https://pypi.python.org/pypi/pendulum



.. image:: https://img.shields.io/pypi/l/pendulum.svg

    :target: https://pypi.python.org/pypi/pendulum



.. image:: https://github.com/sdispater/pendulum/actions/workflows/tests.yml/badge.svg

    :alt: Pendulum Build status

    :target: https://github.com/sdispater/pendulum/actions



Python datetimes made easy.



Supports Python **3.8 and newer**.



.. code-block:: python



   >>> import pendulum



   >>> now_in_paris = pendulum.now('Europe/Paris')

   >>> now_in_paris

   '2016-07-04T00:49:58.502116+02:00'



   # Seamless timezone switching

   >>> now_in_paris.in_timezone('UTC')

   '2016-07-03T22:49:58.502116+00:00'



   >>> tomorrow = pendulum.now().add(days=1)

   >>> last_week = pendulum.now().subtract(weeks=1)



   >>> past = pendulum.now().subtract(minutes=2)

   >>> past.diff_for_humans()

   '2 minutes ago'



   >>> delta = past - last_week

   >>> delta.hours

   23

   >>> delta.in_words(locale='en')

   '6 days 23 hours 58 minutes'



   # Proper handling of datetime normalization

   >>> pendulum.datetime(2013, 3, 31, 2, 30, tz='Europe/Paris')

   '2013-03-31T03:30:00+02:00' # 2:30 does not exist (Skipped time)



   # Proper handling of dst transitions

   >>> just_before = pendulum.datetime(2013, 3, 31, 1, 59, 59, 999999, tz='Europe/Paris')

   '2013-03-31T01:59:59.999999+01:00'

   >>> just_before.add(microseconds=1)

   '2013-03-31T03:00:00+02:00'



Resources

=========



* `Official Website `_

* `Documentation `_

* `Issue Tracker `_



Why Pendulum?

=============



Native ``datetime`` instances are enough for basic cases but when you face more complex use-cases

they often show limitations and are not so intuitive to work with.

``Pendulum`` provides a cleaner and more easy to use API while still relying on the standard library.

So it's still ``datetime`` but better.



Unlike other datetime libraries for Python, Pendulum is a drop-in replacement

for the standard ``datetime`` class (it inherits from it), so, basically, you can replace all your ``datetime``

instances by ``DateTime`` instances in your code (exceptions exist for libraries that check

the type of the objects by using the ``type`` function like ``sqlite3`` or ``PyMySQL`` for instance).



It also removes the notion of naive datetimes: each ``Pendulum`` instance is timezone-aware

and by default in ``UTC`` for ease of use.



Pendulum also improves the standard ``timedelta`` class by providing more intuitive methods and properties.



Limitations

===========



Even though the ``DateTime`` class is a subclass of ``datetime`` there are some rare cases where

it can't replace the native class directly. Here is a list (non-exhaustive) of the reported cases with

a possible solution, if any:



* ``sqlite3`` will use the ``type()`` function to determine the type of the object by default. To work around it you can register a new adapter:



.. code-block:: python



    from pendulum import DateTime

    from sqlite3 import register_adapter



    register_adapter(DateTime, lambda val: val.isoformat(' '))



* ``mysqlclient`` (former ``MySQLdb``) and ``PyMySQL`` will use the ``type()`` function to determine the type of the object by default. To work around it you can register a new adapter:



.. code-block:: python



    import MySQLdb.converters

    import pymysql.converters



    from pendulum import DateTime



    MySQLdb.converters.conversions[DateTime] = MySQLdb.converters.DateTime2literal

    pymysql.converters.conversions[DateTime] = pymysql.converters.escape_datetime



* ``django`` will use the ``isoformat()`` method to store datetimes in the database. However since ``pendulum`` is always timezone aware the offset information will always be returned by ``isoformat()`` raising an error, at least for MySQL databases. To work around it you can either create your own ``DateTimeField`` or use the previous workaround for ``MySQLdb``:



.. code-block:: python



    from django.db.models import DateTimeField as BaseDateTimeField

    from pendulum import DateTime



    class DateTimeField(BaseDateTimeField):



        def value_to_string(self, obj):

            val = self.value_from_object(obj)



            if isinstance(value, DateTime):

                return value.to_datetime_string()



            return '' if val is None else val.isoformat()



Contributing

============



Contributions are welcome, especially with localization.



Getting started

---------------



To work on the Pendulum codebase, you'll want to clone the project locally

and install the required dependencies via `poetry `_.



.. code-block:: bash



    $ git clone [email protected]:sdispater/pendulum.git

    $ poetry install



Localization

------------



If you want to help with localization, there are two different cases: the locale already exists

or not.



If the locale does not exist you will need to create it by using the ``clock`` utility:



.. code-block:: bash



    ./clock locale create 



It will generate a directory in ``pendulum/locales`` named after your locale, with the following

structure:



.. code-block:: text



    /

        - custom.py

        - locale.py



The ``locale.py`` file must not be modified. It contains the translations provided by

the CLDR database.



The ``custom.py`` file is the one you want to modify. It contains the data needed

by Pendulum that are not provided by the CLDR database. You can take the `en `_

data as a reference to see which data is needed.



You should also add tests for the created or modified locale.