Repository files navigation

Python datetimes made easy.

Supports Python3.9 and newer.

>>>importpendulum>>>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.hours23>>>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'

• Official Website
• Documentation
• Issue Tracker

Nativedatetime instances are enough for basic cases but when you face more complex use-casesthey 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 stilldatetime but better.

Unlike other datetime libraries for Python, Pendulum is a drop-in replacementfor the standarddatetime class (it inherits from it), so, basically, you can replace all yourdatetimeinstances byDateTime instances in your code (exceptions exist for libraries that checkthe type of the objects by using thetype function likesqlite3 orPyMySQL for instance).

It also removes the notion of naive datetimes: eachPendulum instance is timezone-awareand by default inUTC for ease of use.

Pendulum also improves the standardtimedelta class by providing more intuitive methods and properties.

Even though theDateTime class is a subclass ofdatetime there are some rare cases whereit can't replace the native class directly. Here is a list (non-exhaustive) of the reported cases witha possible solution, if any:

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

frompendulumimportDateTimefromsqlite3importregister_adapterregister_adapter(DateTime,lambdaval:val.isoformat(' '))

• mysqlclient (formerMySQLdb) andPyMySQL will use thetype() function to determine the type of the object by default. To work around it you can register a new adapter:

importMySQLdb.convertersimportpymysql.convertersfrompendulumimportDateTimeMySQLdb.converters.conversions[DateTime]=MySQLdb.converters.DateTime2literalpymysql.converters.conversions[DateTime]=pymysql.converters.escape_datetime

• django will use theisoformat() method to store datetimes in the database. However sincependulum is always timezone aware the offset information will always be returned byisoformat() raising an error, at least for MySQL databases. To work around it you can either create your ownDateTimeField or use the previous workaround forMySQLdb:

fromdjango.db.modelsimportDateTimeFieldasBaseDateTimeFieldfrompendulumimportDateTimeclassDateTimeField(BaseDateTimeField):defvalue_to_string(self,obj):val=self.value_from_object(obj)ifisinstance(value,DateTime):returnvalue.to_datetime_string()return''ifvalisNoneelseval.isoformat()

Contributions are welcome, especially with localization.

To work on the Pendulum codebase, you'll want to clone the project locallyand install the required dependencies viapoetry.

$ git clone git@github.com:sdispater/pendulum.git$ poetry install

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

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

./clock locale create<your-locale>

It will generate a directory inpendulum/locales named after your locale, with the followingstructure:

<your-locale>/    - custom.py    - locale.py

Thelocale.py file must not be modified. It contains the translations provided bythe CLDR database.

Thecustom.py file is the one you want to modify. It contains the data neededby Pendulum that are not provided by the CLDR database. You can take theendata as a reference to see which data is needed.

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