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