README.rst 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124
  1. dateutil - powerful extensions to datetime
  2. ==========================================
  3. .. image:: https://img.shields.io/travis/dateutil/dateutil/master.svg?style=flat-square
  4. :target: https://travis-ci.org/dateutil/dateutil
  5. :alt: travis build status
  6. .. image:: https://img.shields.io/appveyor/ci/dateutil/dateutil/master.svg?style=flat-square
  7. :target: https://ci.appveyor.com/project/dateutil/dateutil
  8. :alt: appveyor build status
  9. .. image:: https://img.shields.io/pypi/dd/python-dateutil.svg?style=flat-square
  10. :target: https://pypi.python.org/pypi/python-dateutil/
  11. :alt: pypi downloads per day
  12. .. image:: https://img.shields.io/pypi/v/python-dateutil.svg?style=flat-square
  13. :target: https://pypi.python.org/pypi/python-dateutil/
  14. :alt: pypi version
  15. The `dateutil` module provides powerful extensions to
  16. the standard `datetime` module, available in Python.
  17. Download
  18. ========
  19. dateutil is available on PyPI
  20. https://pypi.python.org/pypi/python-dateutil/
  21. The documentation is hosted at:
  22. https://dateutil.readthedocs.org/
  23. Code
  24. ====
  25. https://github.com/dateutil/dateutil/
  26. Features
  27. ========
  28. * Computing of relative deltas (next month, next year,
  29. next monday, last week of month, etc);
  30. * Computing of relative deltas between two given
  31. date and/or datetime objects;
  32. * Computing of dates based on very flexible recurrence rules,
  33. using a superset of the `iCalendar <https://www.ietf.org/rfc/rfc2445.txt>`_
  34. specification. Parsing of RFC strings is supported as well.
  35. * Generic parsing of dates in almost any string format;
  36. * Timezone (tzinfo) implementations for tzfile(5) format
  37. files (/etc/localtime, /usr/share/zoneinfo, etc), TZ
  38. environment string (in all known formats), iCalendar
  39. format files, given ranges (with help from relative deltas),
  40. local machine timezone, fixed offset timezone, UTC timezone,
  41. and Windows registry-based time zones.
  42. * Internal up-to-date world timezone information based on
  43. Olson's database.
  44. * Computing of Easter Sunday dates for any given year,
  45. using Western, Orthodox or Julian algorithms;
  46. * More than 400 test cases.
  47. Quick example
  48. =============
  49. Here's a snapshot, just to give an idea about the power of the
  50. package. For more examples, look at the documentation.
  51. Suppose you want to know how much time is left, in
  52. years/months/days/etc, before the next easter happening on a
  53. year with a Friday 13th in August, and you want to get today's
  54. date out of the "date" unix system command. Here is the code:
  55. .. doctest:: readmeexample
  56. >>> from dateutil.relativedelta import *
  57. >>> from dateutil.easter import *
  58. >>> from dateutil.rrule import *
  59. >>> from dateutil.parser import *
  60. >>> from datetime import *
  61. >>> now = parse("Sat Oct 11 17:13:46 UTC 2003")
  62. >>> today = now.date()
  63. >>> year = rrule(YEARLY,dtstart=now,bymonth=8,bymonthday=13,byweekday=FR)[0].year
  64. >>> rdelta = relativedelta(easter(year), today)
  65. >>> print("Today is: %s" % today)
  66. Today is: 2003-10-11
  67. >>> print("Year with next Aug 13th on a Friday is: %s" % year)
  68. Year with next Aug 13th on a Friday is: 2004
  69. >>> print("How far is the Easter of that year: %s" % rdelta)
  70. How far is the Easter of that year: relativedelta(months=+6)
  71. >>> print("And the Easter of that year is: %s" % (today+rdelta))
  72. And the Easter of that year is: 2004-04-11
  73. Being exactly 6 months ahead was **really** a coincidence :)
  74. Author
  75. ======
  76. The dateutil module was written by Gustavo Niemeyer <gustavo@niemeyer.net>
  77. in 2003
  78. It is maintained by:
  79. * Gustavo Niemeyer <gustavo@niemeyer.net> 2003-2011
  80. * Tomi Pieviläinen <tomi.pievilainen@iki.fi> 2012-2014
  81. * Yaron de Leeuw <me@jarondl.net> 2014-
  82. Building and releasing
  83. ======================
  84. When you get the source, it does not contain the internal zoneinfo
  85. database. To get (and update) the database, run the updatezinfo.py script. Make sure
  86. that the zic command is in your path, and that you have network connectivity
  87. to get the latest timezone information from IANA. If you have downloaded
  88. the timezone data earlier, you can give the tarball as a parameter to
  89. updatezinfo.py.
  90. Testing
  91. =======
  92. dateutil has a comprehensive test suite, which can be run simply by running
  93. `python setup.py test [-q]` in the project root. Note that if you don't have the internal
  94. zoneinfo database, some tests will fail. Apart from that, all tests should pass.
  95. To easily test dateutil against all supported Python versions, you can use
  96. `tox <https://tox.readthedocs.org/en/latest/>`_.
  97. All github pull requests are automatically tested using travis.