README.rst
1dateutil - powerful extensions to datetime
2==========================================
3
4|pypi| |support| |licence|
5
6|gitter| |readthedocs|
7
8|travis| |appveyor| |coverage|
9
10.. |pypi| image:: https://img.shields.io/pypi/v/python-dateutil.svg?style=flat-square
11 :target: https://pypi.org/project/python-dateutil/
12 :alt: pypi version
13
14.. |support| image:: https://img.shields.io/pypi/pyversions/python-dateutil.svg?style=flat-square
15 :target: https://pypi.org/project/python-dateutil/
16 :alt: supported Python version
17
18.. |travis| image:: https://img.shields.io/travis/dateutil/dateutil/master.svg?style=flat-square&label=Travis%20Build
19 :target: https://travis-ci.org/dateutil/dateutil
20 :alt: travis build status
21
22.. |appveyor| image:: https://img.shields.io/appveyor/ci/dateutil/dateutil/master.svg?style=flat-square&logo=appveyor
23 :target: https://ci.appveyor.com/project/dateutil/dateutil
24 :alt: appveyor build status
25
26.. |coverage| image:: https://codecov.io/github/dateutil/dateutil/coverage.svg?branch=master
27 :target: https://codecov.io/github/dateutil/dateutil?branch=master
28 :alt: Code coverage
29
30.. |gitter| image:: https://badges.gitter.im/dateutil/dateutil.svg
31 :alt: Join the chat at https://gitter.im/dateutil/dateutil
32 :target: https://gitter.im/dateutil/dateutil
33
34.. |licence| image:: https://img.shields.io/pypi/l/python-dateutil.svg?style=flat-square
35 :target: https://pypi.org/project/python-dateutil/
36 :alt: licence
37
38.. |readthedocs| image:: https://img.shields.io/readthedocs/dateutil/latest.svg?style=flat-square&label=Read%20the%20Docs
39 :alt: Read the documentation at https://dateutil.readthedocs.io/en/latest/
40 :target: https://dateutil.readthedocs.io/en/latest/
41
42The `dateutil` module provides powerful extensions to
43the standard `datetime` module, available in Python.
44
45Installation
46============
47`dateutil` can be installed from PyPI using `pip` (note that the package name is
48different from the importable name)::
49
50 pip install python-dateutil
51
52Download
53========
54dateutil is available on PyPI
55https://pypi.org/project/python-dateutil/
56
57The documentation is hosted at:
58https://dateutil.readthedocs.io/en/stable/
59
60Code
61====
62The code and issue tracker are hosted on Github:
63https://github.com/dateutil/dateutil/
64
65Features
66========
67
68* Computing of relative deltas (next month, next year,
69 next monday, last week of month, etc);
70* Computing of relative deltas between two given
71 date and/or datetime objects;
72* Computing of dates based on very flexible recurrence rules,
73 using a superset of the `iCalendar <https://www.ietf.org/rfc/rfc2445.txt>`_
74 specification. Parsing of RFC strings is supported as well.
75* Generic parsing of dates in almost any string format;
76* Timezone (tzinfo) implementations for tzfile(5) format
77 files (/etc/localtime, /usr/share/zoneinfo, etc), TZ
78 environment string (in all known formats), iCalendar
79 format files, given ranges (with help from relative deltas),
80 local machine timezone, fixed offset timezone, UTC timezone,
81 and Windows registry-based time zones.
82* Internal up-to-date world timezone information based on
83 Olson's database.
84* Computing of Easter Sunday dates for any given year,
85 using Western, Orthodox or Julian algorithms;
86* A comprehensive test suite.
87
88Quick example
89=============
90Here's a snapshot, just to give an idea about the power of the
91package. For more examples, look at the documentation.
92
93Suppose you want to know how much time is left, in
94years/months/days/etc, before the next easter happening on a
95year with a Friday 13th in August, and you want to get today's
96date out of the "date" unix system command. Here is the code:
97
98.. doctest:: readmeexample
99
100 >>> from dateutil.relativedelta import *
101 >>> from dateutil.easter import *
102 >>> from dateutil.rrule import *
103 >>> from dateutil.parser import *
104 >>> from datetime import *
105 >>> now = parse("Sat Oct 11 17:13:46 UTC 2003")
106 >>> today = now.date()
107 >>> year = rrule(YEARLY,dtstart=now,bymonth=8,bymonthday=13,byweekday=FR)[0].year
108 >>> rdelta = relativedelta(easter(year), today)
109 >>> print("Today is: %s" % today)
110 Today is: 2003-10-11
111 >>> print("Year with next Aug 13th on a Friday is: %s" % year)
112 Year with next Aug 13th on a Friday is: 2004
113 >>> print("How far is the Easter of that year: %s" % rdelta)
114 How far is the Easter of that year: relativedelta(months=+6)
115 >>> print("And the Easter of that year is: %s" % (today+rdelta))
116 And the Easter of that year is: 2004-04-11
117
118Being exactly 6 months ahead was **really** a coincidence :)
119
120Contributing
121============
122
123We 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 ``CONTRIBUTING.md`` file in the repository.
124
125
126Author
127======
128The dateutil module was written by Gustavo Niemeyer <gustavo@niemeyer.net>
129in 2003.
130
131It is maintained by:
132
133* Gustavo Niemeyer <gustavo@niemeyer.net> 2003-2011
134* Tomi Pieviläinen <tomi.pievilainen@iki.fi> 2012-2014
135* Yaron de Leeuw <me@jarondl.net> 2014-2016
136* Paul Ganssle <paul@ganssle.io> 2015-
137
138Starting with version 2.4.1, all source and binary distributions will be signed
139by a PGP key that has, at the very least, been signed by the key which made the
140previous release. A table of release signing keys can be found below:
141
142=========== ============================
143Releases Signing key fingerprint
144=========== ============================
1452.4.1- `6B49 ACBA DCF6 BD1C A206 67AB CD54 FCE3 D964 BEFB`_ (|pgp_mirror|_)
146=========== ============================
147
148
149Contact
150=======
151Our mailing list is available at `dateutil@python.org <https://mail.python.org/mailman/listinfo/dateutil>`_. As it is hosted by the PSF, it is subject to the `PSF code of
152conduct <https://www.python.org/psf/codeofconduct/>`_.
153
154License
155=======
156
157All contributions after December 1, 2017 released under dual license - either `Apache 2.0 License <https://www.apache.org/licenses/LICENSE-2.0>`_ or the `BSD 3-Clause License <https://opensource.org/licenses/BSD-3-Clause>`_. Contributions before December 1, 2017 - except those those explicitly relicensed - are released only under the BSD 3-Clause License.
158
159
160.. _6B49 ACBA DCF6 BD1C A206 67AB CD54 FCE3 D964 BEFB:
161 https://pgp.mit.edu/pks/lookup?op=vindex&search=0xCD54FCE3D964BEFB
162
163.. |pgp_mirror| replace:: mirror
164.. _pgp_mirror: https://sks-keyservers.net/pks/lookup?op=vindex&search=0xCD54FCE3D964BEFB
165
