blob: e70120d75348c7d874a174317f4079b5b18eb6b9 [file] [log] [blame]
dateutil - powerful extensions to datetime
|pypi| |support| |licence|
|gitter| |readthedocs|
|travis| |appveyor| |coverage|
.. |pypi| image::
:alt: pypi version
.. |support| image::
:alt: supported Python version
.. |travis| image::
:alt: travis build status
.. |appveyor| image::
:alt: appveyor build status
.. |coverage| image::
:alt: Code coverage
.. |gitter| image::
:alt: Join the chat at
.. |licence| image::
:alt: licence
.. |readthedocs| image::
:alt: Read the documentation at
The `dateutil` module provides powerful extensions to
the standard `datetime` module, available in Python.
`dateutil` can be installed from PyPI using `pip` (note that the package name is
different from the importable name)::
pip install python-dateutil
dateutil is available on PyPI
The documentation is hosted at:
The code and issue tracker are hosted on Github:
* Computing of relative deltas (next month, next year,
next monday, last week of month, etc);
* Computing of relative deltas between two given
date and/or datetime objects;
* Computing of dates based on very flexible recurrence rules,
using a superset of the `iCalendar <>`_
specification. Parsing of RFC strings is supported as well.
* Generic parsing of dates in almost any string format;
* Timezone (tzinfo) implementations for tzfile(5) format
files (/etc/localtime, /usr/share/zoneinfo, etc), TZ
environment string (in all known formats), iCalendar
format files, given ranges (with help from relative deltas),
local machine timezone, fixed offset timezone, UTC timezone,
and Windows registry-based time zones.
* Internal up-to-date world timezone information based on
Olson's database.
* Computing of Easter Sunday dates for any given year,
using Western, Orthodox or Julian algorithms;
* A comprehensive test suite.
Quick example
Here's a snapshot, just to give an idea about the power of the
package. For more examples, look at the documentation.
Suppose you want to know how much time is left, in
years/months/days/etc, before the next easter happening on a
year with a Friday 13th in August, and you want to get today's
date out of the "date" unix system command. Here is the code:
.. doctest:: readmeexample
>>> from dateutil.relativedelta import *
>>> from dateutil.easter import *
>>> from dateutil.rrule import *
>>> from dateutil.parser import *
>>> from datetime import *
>>> now = parse("Sat Oct 11 17:13:46 UTC 2003")
>>> today =
>>> year = rrule(YEARLY,dtstart=now,bymonth=8,bymonthday=13,byweekday=FR)[0].year
>>> rdelta = relativedelta(easter(year), today)
>>> print("Today is: %s" % today)
Today is: 2003-10-11
>>> print("Year with next Aug 13th on a Friday is: %s" % year)
Year with next Aug 13th on a Friday is: 2004
>>> print("How far is the Easter of that year: %s" % rdelta)
How far is the Easter of that year: relativedelta(months=+6)
>>> print("And the Easter of that year is: %s" % (today+rdelta))
And the Easter of that year is: 2004-04-11
Being exactly 6 months ahead was **really** a coincidence :)
We welcome many types of contributions - bug reports, pull requests (code, infrastructure or documentation fixes). For more information about how to contribute to the project, see the ```` file in the repository.
The dateutil module was written by Gustavo Niemeyer <>
in 2003.
It is maintained by:
* Gustavo Niemeyer <> 2003-2011
* Tomi Pieviläinen <> 2012-2014
* Yaron de Leeuw <> 2014-2016
* Paul Ganssle <> 2015-
Starting with version 2.4.1, all source and binary distributions will be signed
by a PGP key that has, at the very least, been signed by the key which made the
previous release. A table of release signing keys can be found below:
=========== ============================
Releases Signing key fingerprint
=========== ============================
2.4.1- `6B49 ACBA DCF6 BD1C A206 67AB CD54 FCE3 D964 BEFB`_ (|pgp_mirror|_)
=========== ============================
Our mailing list is available at ` <>`_. As it is hosted by the PSF, it is subject to the `PSF code of
conduct <>`_.
All contributions after December 1, 2017 released under dual license - either `Apache 2.0 License <>`_ or the `BSD 3-Clause License <>`_. Contributions before December 1, 2017 - except those those explicitly relicensed - are released only under the BSD 3-Clause License.
.. _6B49 ACBA DCF6 BD1C A206 67AB CD54 FCE3 D964 BEFB:
.. |pgp_mirror| replace:: mirror
.. _pgp_mirror: