README.rst
1Arrow: Better dates & times for Python
2======================================
3
4.. start-inclusion-marker-do-not-remove
5
6.. image:: https://github.com/arrow-py/arrow/workflows/tests/badge.svg?branch=master
7 :alt: Build Status
8 :target: https://github.com/arrow-py/arrow/actions?query=workflow%3Atests+branch%3Amaster
9
10.. image:: https://codecov.io/gh/arrow-py/arrow/branch/master/graph/badge.svg
11 :alt: Coverage
12 :target: https://codecov.io/gh/arrow-py/arrow
13
14.. image:: https://img.shields.io/pypi/v/arrow.svg
15 :alt: PyPI Version
16 :target: https://pypi.python.org/pypi/arrow
17
18.. image:: https://img.shields.io/pypi/pyversions/arrow.svg
19 :alt: Supported Python Versions
20 :target: https://pypi.python.org/pypi/arrow
21
22.. image:: https://img.shields.io/pypi/l/arrow.svg
23 :alt: License
24 :target: https://pypi.python.org/pypi/arrow
25
26.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
27 :alt: Code Style: Black
28 :target: https://github.com/psf/black
29
30
31**Arrow** is a Python library that offers a sensible and human-friendly approach to creating, manipulating, formatting and converting dates, times and timestamps. It implements and updates the datetime type, plugging gaps in functionality and providing an intelligent module API that supports many common creation scenarios. Simply put, it helps you work with dates and times with fewer imports and a lot less code.
32
33Arrow is named after the `arrow of time <https://en.wikipedia.org/wiki/Arrow_of_time>`_ and is heavily inspired by `moment.js <https://github.com/moment/moment>`_ and `requests <https://github.com/psf/requests>`_.
34
35Why use Arrow over built-in modules?
36------------------------------------
37
38Python's standard library and some other low-level modules have near-complete date, time and timezone functionality, but don't work very well from a usability perspective:
39
40- Too many modules: datetime, time, calendar, dateutil, pytz and more
41- Too many types: date, time, datetime, tzinfo, timedelta, relativedelta, etc.
42- Timezones and timestamp conversions are verbose and unpleasant
43- Timezone naivety is the norm
44- Gaps in functionality: ISO 8601 parsing, timespans, humanization
45
46Features
47--------
48
49- Fully-implemented, drop-in replacement for datetime
50- Support for Python 3.6+
51- Timezone-aware and UTC by default
52- Super-simple creation options for many common input scenarios
53- ``shift`` method with support for relative offsets, including weeks
54- Format and parse strings automatically
55- Wide support for the `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ standard
56- Timezone conversion
57- Support for ``dateutil``, ``pytz``, and ``ZoneInfo`` tzinfo objects
58- Generates time spans, ranges, floors and ceilings for time frames ranging from microsecond to year
59- Humanize dates and times with a growing list of contributed locales
60- Extensible for your own Arrow-derived types
61- Full support for PEP 484-style type hints
62
63Quick Start
64-----------
65
66Installation
67~~~~~~~~~~~~
68
69To install Arrow, use `pip <https://pip.pypa.io/en/stable/quickstart/>`_ or `pipenv <https://docs.pipenv.org>`_:
70
71.. code-block:: console
72
73 $ pip install -U arrow
74
75Example Usage
76~~~~~~~~~~~~~
77
78.. code-block:: python
79
80 >>> import arrow
81 >>> arrow.get('2013-05-11T21:23:58.970460+07:00')
82 <Arrow [2013-05-11T21:23:58.970460+07:00]>
83
84 >>> utc = arrow.utcnow()
85 >>> utc
86 <Arrow [2013-05-11T21:23:58.970460+00:00]>
87
88 >>> utc = utc.shift(hours=-1)
89 >>> utc
90 <Arrow [2013-05-11T20:23:58.970460+00:00]>
91
92 >>> local = utc.to('US/Pacific')
93 >>> local
94 <Arrow [2013-05-11T13:23:58.970460-07:00]>
95
96 >>> local.timestamp()
97 1368303838.970460
98
99 >>> local.format()
100 '2013-05-11 13:23:58 -07:00'
101
102 >>> local.format('YYYY-MM-DD HH:mm:ss ZZ')
103 '2013-05-11 13:23:58 -07:00'
104
105 >>> local.humanize()
106 'an hour ago'
107
108 >>> local.humanize(locale='ko-kr')
109 '한시간 전'
110
111.. end-inclusion-marker-do-not-remove
112
113Documentation
114-------------
115
116For full documentation, please visit `arrow.readthedocs.io <https://arrow.readthedocs.io>`_.
117
118Contributing
119------------
120
121Contributions are welcome for both code and localizations (adding and updating locales). Begin by gaining familiarity with the Arrow library and its features. Then, jump into contributing:
122
123#. Find an issue or feature to tackle on the `issue tracker <https://github.com/arrow-py/arrow/issues>`_. Issues marked with the `"good first issue" label <https://github.com/arrow-py/arrow/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_ may be a great place to start!
124#. Fork `this repository <https://github.com/arrow-py/arrow>`_ on GitHub and begin making changes in a branch.
125#. Add a few tests to ensure that the bug was fixed or the feature works as expected.
126#. Run the entire test suite and linting checks by running one of the following commands: ``tox && tox -e lint,docs`` (if you have `tox <https://tox.readthedocs.io>`_ installed) **OR** ``make build39 && make test && make lint`` (if you do not have Python 3.9 installed, replace ``build39`` with the latest Python version on your system).
127#. Submit a pull request and await feedback ��.
128
129If you have any questions along the way, feel free to ask them `here <https://github.com/arrow-py/arrow/discussions>`_.
130
131Support Arrow
132-------------
133
134`Open Collective <https://opencollective.com/>`_ is an online funding platform that provides tools to raise money and share your finances with full transparency. It is the platform of choice for individuals and companies to make one-time or recurring donations directly to the project. If you are interested in making a financial contribution, please visit the `Arrow collective <https://opencollective.com/arrow>`_.
135
