# Arrow: better dates and times for Python

## What?

Arrow is a Python library that offers a sensible, 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 provides 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.

Arrow is heavily inspired by moment.js and requests.

## Why?

Python’s standard library and some other low-level modules have near-complete date, time and time zone functionality but don’t work very well from a usability perspective:

- Too many modules: datetime, time, calendar, dateutil, pytz and more
- Too many types: date, time, datetime, tzinfo, timedelta, relativedelta, etc.
- Time zones and timestamp conversions are verbose and unpleasant
- Time zone naivety is the norm
- Gaps in functionality: ISO-8601 parsing, time spans, humanization

## Features

- Fully implemented, drop-in replacement for datetime
- Supports Python 2.6, 2.7 and 3.3
- Time zone-aware & UTC by default
- Provides super-simple creation options for many common input scenarios
- Updated .replace method with support for relative offsets, including weeks
- Formats and parses strings, including ISO-8601-formatted strings automatically
- Timezone conversion
- Timestamp available as a property
- Generates time spans, ranges, floors and ceilings in time frames from year to microsecond
- Humanizes and supports a growing list of contributed locales
- Extensible for your own Arrow-derived types

## Quickstart

    $ pip install arrow

    >>> import arrow
    >>> utc = arrow.utcnow()
    >>> utc
    <Arrow [2013-05-11T21:23:58.970460+00:00]>

    >>> utc = utc.replace(hours=-1)
    >>> utc
    <Arrow [2013-05-11T20:23:58.970460+00:00]>

    >>> local = utc.to('US/Pacific')
    >>> local
    <Arrow [2013-05-11T13:23:58.970460-07:00]>

    >>> arrow.get('2013-05-11T21:23:58.970460+00:00')
    <Arrow [2013-05-11T21:23:58.970460+00:00]>

    >>> local.timestamp
    1368303838

    >>> local.format()
    '2013-05-11 13:23:58 -07:00'

    >>> local.format('YYYY-MM-DD HH:mm:ss ZZ')
    '2013-05-11 13:23:58 -07:00'

    >>> local.humanize()
    'an hour ago'

    >>> local.humanize(locale='ko_kr')
    '1시간 전'

## User’s Guide

### Creation

Get ‘now’ easily:

    >>> arrow.utcnow()
    <Arrow [2013-05-07T04:20:39.369271+00:00]>

    >>> arrow.now()
    <Arrow [2013-05-06T21:20:40.841085-07:00]>

    >>> arrow.now('US/Pacific')
    <Arrow [2013-05-06T21:20:44.761511-07:00]>

Create from timestamps (ints or floats, or strings that convert to a float):

    >>> arrow.get(1367900664)
    <Arrow [2013-05-07T04:24:24+00:00]>

    >>> arrow.get('1367900664')
    <Arrow [2013-05-07T04:24:24+00:00]>

    >>> arrow.get(1367900664.152325)
    <Arrow [2013-05-07T04:24:24.152325+00:00]>

    >>> arrow.get('1367900664.152325')
    <Arrow [2013-05-07T04:24:24.152325+00:00]>

Use a naive or timezone-aware datetime, or flexibly specify a time zone:

    >>> arrow.get(datetime.utcnow())
    <Arrow [2013-05-07T04:24:24.152325+00:00]>

    >>> arrow.get(datetime.now(), 'US/Pacific')
    <Arrow [2013-05-06T21:24:32.736373-07:00]>

    >>> from dateutil import tz
    >>> arrow.get(datetime.now(), tz.gettz('US/Pacific'))
    <Arrow [2013-05-06T21:24:41.129262-07:00]>

    >>> arrow.get(datetime.now(tz.gettz('US/Pacific')))
    <Arrow [2013-05-06T21:24:49.552236-07:00]>

Parse from a string:

    >>> arrow.get('2013-05-05 12:30:45', 'YYYY-MM-DD HH:mm:ss')
    <Arrow [2013-05-05T12:30:45+00:00]>

Search a date in a string:

    >>> arrow.get('June was born in May 1980', 'MMMM YYYY')
    <Arrow [1980-05-01T00:00:00+00:00]>

Many ISO-8601 compliant strings are recognized and parsed without a format string:

    >>> arrow.get('2013-09-30T15:34:00.000-07:00')
    <Arrow [2013-09-30T15:34:00-07:00]>

Arrow objects can be instantiated directly too, with the same arguments as a datetime:

    >>> arrow.get(2013, 5, 5)
    <Arrow [2013-05-05T00:00:00+00:00]>

    >>> arrow.Arrow(2013, 5, 5)
    <Arrow [2013-05-05T00:00:00+00:00]>

### Properties

Get a datetime or timestamp representation:

    >>> a = arrow.utcnow()
    >>> a.datetime
    datetime.datetime(2013, 5, 7, 4, 38, 15, 447644, tzinfo=tzutc())

    >>> a.timestamp
    1367901495

Get a naive datetime, and tzinfo:

    >>> a.naive
    datetime.datetime(2013, 5, 7, 4, 38, 15, 447644)

    >>> a.tzinfo
    tzutc()

Get any datetime value:

    >>> a.year
    2013

Call datetime functions that return properties:

    >>> a.date()
    datetime.date(2013, 5, 7)

    >>> a.time()
    datetime.time(4, 38, 15, 447644)

### Replace & shift

Get a new `Arrow` object, with altered attributes, just as you would with a datetime:

    >>> arw = arrow.utcnow()
    >>> arw
    <Arrow [2013-05-12T03:29:35.334214+00:00]>

    >>> arw.replace(hour=4, minute=40)
    <Arrow [2013-05-12T04:40:35.334214+00:00]>

Or, get one with attributes shifted forward or backward:

    >>> arw.replace(weeks=+3)
    <Arrow [2013-06-02T03:29:35.334214+00:00]>

### Format

    >>> arrow.utcnow().format('YYYY-MM-DD HH:mm:ss ZZ')
    '2013-05-07 05:23:16 -00:00'

### Convert

Convert to timezones by name or tzinfo:

    >>> utc = arrow.utcnow()
    >>> utc
    <Arrow [2013-05-07T05:24:11.823627+00:00]>

    >>> utc.to('US/Pacific')
    <Arrow [2013-05-06T22:24:11.823627-07:00]>

    >>> utc.to(tz.gettz('US/Pacific'))
    <Arrow [2013-05-06T22:24:11.823627-07:00]>

Or using shorthand:

    >>> utc.to('local')
    <Arrow [2013-05-06T22:24:11.823627-07:00]>

    >>> utc.to('local').to('utc')
    <Arrow [2013-05-07T05:24:11.823627+00:00]>

### Humanize

Humanize relative to now:

    >>> past = arrow.utcnow().replace(hours=-1)
    >>> past.humanize()
    'an hour ago'

Or another Arrow, or datetime:

    >>> present = arrow.utcnow()
    >>> future = present.replace(hours=2)
    >>> future.humanize(present)
    'in 2 hours'

Support for a growing number of locales (see locales.py for supported languages):

    >>> future = arrow.utcnow().replace(hours=1)
    >>> future.humanize(a, locale='ru')
    'через 2 час(а,ов)'

### Ranges & spans

Get the time span of any unit:

    >>> arrow.utcnow().span('hour')
    (<Arrow [2013-05-07T05:00:00+00:00]>, <Arrow [2013-05-07T05:59:59.999999+00:00]>)

Or just get the floor and ceiling:

    >>> arrow.utcnow().floor('hour')
    <Arrow [2013-05-07T05:00:00+00:00]>

    >>> arrow.utcnow().ceil('hour')
    <Arrow [2013-05-07T05:59:59.999999+00:00]>

You can also get a range of time spans:

    >>> start = datetime(2013, 5, 5, 12, 30)
    >>> end = datetime(2013, 5, 5, 17, 15)
    >>> for r in arrow.Arrow.span_range('hour', start, end):
    ...     print r
    ...
    (<Arrow [2013-05-05T12:00:00+00:00]>, <Arrow [2013-05-05T12:59:59.999999+00:00]>)
    (<Arrow [2013-05-05T13:00:00+00:00]>, <Arrow [2013-05-05T13:59:59.999999+00:00]>)
    (<Arrow [2013-05-05T14:00:00+00:00]>, <Arrow [2013-05-05T14:59:59.999999+00:00]>)
    (<Arrow [2013-05-05T15:00:00+00:00]>, <Arrow [2013-05-05T15:59:59.999999+00:00]>)
    (<Arrow [2013-05-05T16:00:00+00:00]>, <Arrow [2013-05-05T16:59:59.999999+00:00]>)

Or just iterate over a range of time:

    >>> start = datetime(2013, 5, 5, 12, 30)
    >>> end = datetime(2013, 5, 5, 17, 15)
    >>> for r in arrow.Arrow.range('hour', start, end):
    ...     print repr(r)
    ...
    <Arrow [2013-05-05T12:30:00+00:00]>
    <Arrow [2013-05-05T13:30:00+00:00]>
    <Arrow [2013-05-05T14:30:00+00:00]>
    <Arrow [2013-05-05T15:30:00+00:00]>
    <Arrow [2013-05-05T16:30:00+00:00]>

### Factories

Use factories to harness Arrow’s module API for a custom Arrow-derived type. First, derive your type:

    >>> class CustomArrow(arrow.Arrow):
    ...
    ...     def days_till_xmas(self):
    ...
    ...         xmas = arrow.Arrow(self.year, 12, 25)
    ...
    ...         if self > xmas:
    ...             xmas = xmas.replace(years=1)
    ...
    ...         return (xmas - self).days

Then get and use a factory for it:

    >>> factory = arrow.Factory(CustomArrow)
    >>> custom = factory.utcnow()
    >>> custom
    >>> <CustomArrow [2013-05-27T23:35:35.533160+00:00]>

    >>> custom.days_till_xmas()
    >>> 211

### Tokens

Use the following tokens in parsing and formatting. Note that they’re not the same as the tokens for strptime(3):

| Token | Output
--- | --- | ---
Year | YYYY | 2000, 2001, 2002 ... 2012, 2013
| YY | 00, 01, 02 ... 12, 13
Month | MMMM | January, February, March ... [1]
| MMM | Jan, Feb, Mar ... [1]
| MM | 01, 02, 03 ... 11, 12
| M | 1, 2, 3 ... 11, 12
Day of Year | DDDD | 001, 002, 003 ... 364, 365
| DDD | 1, 2, 3 ... 4, 5
Day of Month | DD | 01, 02, 03 ... 30, 31
| D | 1, 2, 3 ... 30, 31
| Do | 1st, 2nd, 3rd ... 30th, 31st
Day of Week | dddd | Monday, Tuesday, Wednesday ... [2]
| ddd | Mon, Tue, Wed ... [2]
| d | 1, 2, 3 ... 6, 7
Hour | HH | 00, 01, 02 ... 23, 24
| H | 0, 1, 2 ... 23, 24
| hh | 01, 02, 03 ... 11, 12
| h | 1, 2, 3 ... 11, 12
AM / PM | A | AM, PM, am, pm [1]
| a | am, pm [1]
Minute | mm | 00, 01, 02 ... 58, 59
| m | 0, 1, 2 ... 58, 59
Second | ss | 00, 01, 02 ... 58, 59
| s | 0, 1, 2 ... 58, 59
Sub-second | SSS | 000, 001, 002 ... 998, 999
| SS | 00, 01, 02 ... 98, 99
| S | 0, 1, 2 ... 8, 9
Timezone | ZZ | -07:00, -06:00 ... +06:00, +07:00
| Z | -0700, -0600 ... +0600, +0700
Timestamp | X | 1381685817

Footnotes

[1] | (1, 2, 3, 4) localization support for parsing and formatting

[2] | (1, 2) localization support only for formatting

## API Guide

### arrow.arrow

Provides the `Arrow` class, an enhanced `datetime` replacement.

class `arrow.arrow.``Arrow`(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None)

  An `Arrow` object.

  Implements the `datetime` interface, behaving as an aware `datetime` while implementing additional functionality.

  Parameters:

  - year – the calendar year.
  - month – the calendar month.
  - day – the calendar day.
  - hour – (optional) the hour. Defaults to 0.
  - minute – (optional) the minute, Defaults to 0.
  - second – (optional) the second, Defaults to 0.
  - microsecond – (optional) the microsecond. Defaults 0.
  - tzinfo – (optional) the `tzinfo` object. Defaults to `None`.

  If tzinfo is None, it is assumed to be UTC on creation.

  Usage:

      >>> import arrow
      >>> arrow.Arrow(2013, 5, 5, 12, 30, 45)
      <Arrow [2013-05-05T12:30:45+00:00]>

  classmethod `now`(tzinfo=None)

    Constructs an `Arrow` object, representing “now”.

    Parameters: | tzinfo – (optional) a `tzinfo` object. Defaults to local time.

  classmethod `utcnow`()

    Constructs an `Arrow` object, representing “now” in UTC time.

  classmethod `fromtimestamp`(timestamp, tzinfo=None)

    Constructs an `Arrow` object from a timestamp.

    Parameters:

    - timestamp – an `int` or `float` timestamp, or a `str` that converts to either.
    - tzinfo – (optional) a `tzinfo` object. Defaults to local time.

  classmethod `utcfromtimestamp`(timestamp)

    Constructs an `Arrow` object from a timestamp, in UTC time.

    Parameters: | timestamp – an `int` or `float` timestamp, or a `str` that converts to either.

  classmethod `fromdatetime`(dt, tzinfo=None)

    Constructs an `Arrow` object from a `datetime` and optional `tzinfo` object.

    Parameters:

    - dt – the `datetime`
    - tzinfo – (optional) a `tzinfo` object. Defaults to UTC.

  classmethod `fromdate`(date, tzinfo=None)

    Constructs an `Arrow` object from a `date` and optional `tzinfo` object. Time values are set to 0.

    Parameters:

    - date – the `date`
    - tzinfo – (optional) a `tzinfo` object. Defaults to UTC.

  classmethod `strptime`(date_str, fmt, tzinfo=None)

    Constructs an `Arrow` object from a date string and format, in the style of `datetime.strptime`.

    Parameters:

    - date_str – the date string.
    - fmt – the format string.
    - tzinfo – (optional) an optional `tzinfo`

  classmethod `range`(frame, start, end=None, tz=None, limit=None)

    Returns an array of `Arrow` objects, representing an iteration of time between two inputs.

    Parameters:

    - frame – the timeframe. Can be any `datetime` property (day, hour, minute...).
    - start – A datetime expression, the start of the range.
    - end – (optional) A datetime expression, the end of the range.
    - tz – (optional) A timezone expression. Defaults to UTC.
    - limit – (optional) A maximum number of tuples to return.

    NOTE: the end or limit must be provided. Call with end alone to return the entire range, with limit alone to return a maximum # of results from the start, and with both to cap a range at a maximum # of results.

    Supported frame values: year, quarter, month, week, day, hour, minute, second

    Recognized datetime expressions:

    > - An `Arrow` object.
    > - A `datetime` object.

    Recognized timezone expressions:

    > - A `tzinfo` object.
    > - A `str` describing a timezone, similar to ‘US/Pacific’, or ‘Europe/Berlin’.
    > - A `str` in ISO-8601 style, as in ‘+07:00’.
    > - A `str`, one of the following: ‘local’, ‘utc’, ‘UTC’.

    Usage:

        >>> start = datetime(2013, 5, 5, 12, 30)
        >>> end = datetime(2013, 5, 5, 17, 15)
        >>> for r in arrow.Arrow.range('hour', start, end):
        ...     print repr(r)
        ...
        <Arrow [2013-05-05T12:30:00+00:00]>
        <Arrow [2013-05-05T13:30:00+00:00]>
        <Arrow [2013-05-05T14:30:00+00:00]>
        <Arrow [2013-05-05T15:30:00+00:00]>
        <Arrow [2013-05-05T16:30:00+00:00]>

  classmethod `span_range`(frame, start, end, tz=None, limit=None)

    Returns an array of tuples, each `Arrow` objects, representing a series of timespans between two inputs.

    Parameters:

    - frame – the timeframe. Can be any `datetime` property (day, hour, minute...).
    - start – A datetime expression, the start of the range.
    - end – (optional) A datetime expression, the end of the range.
    - tz – (optional) A timezone expression. Defaults to UTC.
    - limit – (optional) A maximum number of tuples to return.

    NOTE: the end or limit must be provided. Call with end alone to return the entire range, with limit alone to return a maximum # of results from the start, and with both to cap a range at a maximum # of results.

    Supported frame values: year, quarter, month, week, day, hour, minute, second

    Recognized datetime expressions:

    > - An `Arrow` object.
    > - A `datetime` object.

    Recognized timezone expressions:

    > - A `tzinfo` object.
    > - A `str` describing a timezone, similar to ‘US/Pacific’, or ‘Europe/Berlin’.
    > - A `str` in ISO-8601 style, as in ‘+07:00’.
    > - A `str`, one of the following: ‘local’, ‘utc’, ‘UTC’.

    Usage:

        >>> start = datetime(2013, 5, 5, 12, 30)
        >>> end = datetime(2013, 5, 5, 17, 15)
        >>> for r in arrow.Arrow.span_range('hour', start, end):
        ...     print r
        ...
        (<Arrow [2013-05-05T12:00:00+00:00]>, <Arrow [2013-05-05T12:59:59.999999+00:00]>)
        (<Arrow [2013-05-05T13:00:00+00:00]>, <Arrow [2013-05-05T13:59:59.999999+00:00]>)
        (<Arrow [2013-05-05T14:00:00+00:00]>, <Arrow [2013-05-05T14:59:59.999999+00:00]>)
        (<Arrow [2013-05-05T15:00:00+00:00]>, <Arrow [2013-05-05T15:59:59.999999+00:00]>)
        (<Arrow [2013-05-05T16:00:00+00:00]>, <Arrow [2013-05-05T16:59:59.999999+00:00]>)

  `tzinfo`

    Gets the `tzinfo` of the `Arrow` object.

  `datetime`

    Returns a datetime representation of the `Arrow` object.

  `naive`

    Returns a naive datetime representation of the `Arrow` object.

  `timestamp`

    Returns a timestamp representation of the `Arrow` object.

  `float_timestamp`

    Returns a floating-point representation of the `Arrow` object.

  `clone`()

    Returns a new `Arrow` object, cloned from the current one.

    Usage:

        >>> arw = arrow.utcnow()
        >>> cloned = arw.clone()

  `replace`(**kwargs)

    Returns a new `Arrow` object with attributes updated according to inputs.

    Use single property names to set their value absolutely:

        >>> import arrow
        >>> arw = arrow.utcnow()
        >>> arw
        <Arrow [2013-05-11T22:27:34.787885+00:00]>
        >>> arw.replace(year=2014, month=6)
        <Arrow [2014-06-11T22:27:34.787885+00:00]>

    Use plural property names to shift their current value relatively:

        >>> arw.replace(years=1, months=-1)
        <Arrow [2014-04-11T22:27:34.787885+00:00]>

    You can also provide a timezone expression can also be replaced:

        >>> arw.replace(tzinfo=tz.tzlocal())
        <Arrow [2013-05-11T22:27:34.787885-07:00]>

    Recognized timezone expressions:

    > - A `tzinfo` object.
    > - A `str` describing a timezone, similar to ‘US/Pacific’, or ‘Europe/Berlin’.
    > - A `str` in ISO-8601 style, as in ‘+07:00’.
    > - A `str`, one of the following: ‘local’, ‘utc’, ‘UTC’.

  `to`(tz)

    Returns a new `Arrow` object, converted to the target timezone.

    Parameters: | tz – an expression representing a timezone.

    Recognized timezone expressions:

    > - A `tzinfo` object.
    > - A `str` describing a timezone, similar to ‘US/Pacific’, or ‘Europe/Berlin’.
    > - A `str` in ISO-8601 style, as in ‘+07:00’.
    > - A `str`, one of the following: ‘local’, ‘utc’, ‘UTC’.

    Usage:

        >>> utc = arrow.utcnow()
        >>> utc
        <Arrow [2013-05-09T03:49:12.311072+00:00]>

        >>> utc.to('US/Pacific')
        <Arrow [2013-05-08T20:49:12.311072-07:00]>

        >>> utc.to(tz.tzlocal())
        <Arrow [2013-05-08T20:49:12.311072-07:00]>

        >>> utc.to('-07:00')
        <Arrow [2013-05-08T20:49:12.311072-07:00]>

        >>> utc.to('local')
        <Arrow [2013-05-08T20:49:12.311072-07:00]>

        >>> utc.to('local').to('utc')
        <Arrow [2013-05-09T03:49:12.311072+00:00]>

  `span`(frame, count=1)

    Returns two new `Arrow` objects, representing the timespan of the `Arrow` object in a given timeframe.

    Parameters:

    - frame – the timeframe. Can be any `datetime` property (day, hour, minute...).
    - count – (optional) the number of frames to span.

    Supported frame values: year, quarter, month, week, day, hour, minute, second

    Usage:

        >>> arrow.utcnow()
        <Arrow [2013-05-09T03:32:36.186203+00:00]>

        >>> arrow.utcnow().span('hour')
        (<Arrow [2013-05-09T03:00:00+00:00]>, <Arrow [2013-05-09T03:59:59.999999+00:00]>)

        >>> arrow.utcnow().span('day')
        (<Arrow [2013-05-09T00:00:00+00:00]>, <Arrow [2013-05-09T23:59:59.999999+00:00]>)

        >>> arrow.utcnow().span('day', count=2)
        (<Arrow [2013-05-09T00:00:00+00:00]>, <Arrow [2013-05-10T23:59:59.999999+00:00]>)

  `floor`(frame)

    Returns a new `Arrow` object, representing the “floor” of the timespan of the `Arrow` object in a given timeframe. Equivalent to the first element in the 2-tuple returned by `span`.

    Parameters: | frame – the timeframe. Can be any `datetime` property (day, hour, minute...).

    Usage:

        >>> arrow.utcnow().floor('hour')
        <Arrow [2013-05-09T03:00:00+00:00]>

  `ceil`(frame)

    Returns a new `Arrow` object, representing the “ceiling” of the timespan of the `Arrow` object in a given timeframe. Equivalent to the second element in the 2-tuple returned by `span`.

    Parameters: | frame – the timeframe. Can be any `datetime` property (day, hour, minute...).

    Usage:

        >>> arrow.utcnow().ceil('hour')
        <Arrow [2013-05-09T03:59:59.999999+00:00]>

  `format`(fmt='YYYY-MM-DD HH:mm:ssZZ', locale='en_us')

    Returns a string representation of the `Arrow` object, formatted according to a format string.

    Parameters: | fmt – the format string.

    Usage:

        >>> arrow.utcnow().format('YYYY-MM-DD HH:mm:ss ZZ')
        '2013-05-09 03:56:47 -00:00'

        >>> arrow.utcnow().format('X')
        '1368071882'

        >>> arrow.utcnow().format('MMMM DD, YYYY')
        'May 09, 2013'

        >>> arrow.utcnow().format()
        '2013-05-09 03:56:47 -00:00'

  `humanize`(other=None, locale='en_us', only_distance=False)

    Returns a localized, humanized representation of a relative difference in time.

    Parameters:

    - other – (optional) an `Arrow` or `datetime` object. Defaults to now in the current `Arrow` object’s timezone.
    - locale – (optional) a `str` specifying a locale. Defaults to ‘en_us’.
    - only_difference – (optional) returns only time difference eg: “11 seconds” without “in” or “ago” part.

    Usage:

        >>> earlier = arrow.utcnow().replace(hours=-2)
        >>> earlier.humanize()
        '2 hours ago'

        >>> later = later = earlier.replace(hours=4)
        >>> later.humanize(earlier)
        'in 4 hours'

  `date`()

    Returns a `date` object with the same year, month and day.

  `time`()

    Returns a `time` object with the same hour, minute, second, microsecond.

  `timetz`()

    Returns a `time` object with the same hour, minute, second, microsecond and tzinfo.

  `astimezone`(tz)

    Returns a `datetime` object, adjusted to the specified tzinfo.

    Parameters: | tz – a `tzinfo` object.

  `utcoffset`()

    Returns a `timedelta` object representing the whole number of minutes difference from UTC time.

  `dst`()

    Returns the daylight savings time adjustment.

  `timetuple`()

    Returns a `time.struct_time`, in the current timezone.

  `utctimetuple`()

    Returns a `time.struct_time`, in UTC time.

  `toordinal`()

    Returns the proleptic Gregorian ordinal of the date.

  `weekday`()

    Returns the day of the week as an integer (0-6).

  `isoweekday`()

    Returns the ISO day of the week as an integer (1-7).

  `isocalendar`()

    Returns a 3-tuple, (ISO year, ISO week number, ISO weekday).

  `isoformat`(sep='T')

    Returns an ISO 8601 formatted representation of the date and time.

  `ctime`()

    Returns a ctime formatted representation of the date and time.

  `strftime`(format)

    Formats in the style of `datetime.strptime`.

    Parameters: | format – the format string.

  `for_json`()

    Serializes for the `for_json` protocol of simplejson.

### arrow.factory

Implements the `ArrowFactory` class, providing factory methods for common `Arrow` construction scenarios.

class `arrow.factory.``ArrowFactory`(type=<class 'arrow.arrow.Arrow'>)

  A factory for generating `Arrow` objects.

  Parameters: | type – (optional) the `Arrow`-based class to construct from. Defaults to `Arrow`.

  `get`(*args, **kwargs)

    Returns an `Arrow` object based on flexible inputs.

    Usage:

        >>> import arrow

    No inputs to get current UTC time:

        >>> arrow.get()
        <Arrow [2013-05-08T05:51:43.316458+00:00]>

    None to also get current UTC time:

        >>> arrow.get(None)
        <Arrow [2013-05-08T05:51:43.316458+00:00]>

    One `Arrow` object, to get a copy.

        >>> arw = arrow.utcnow()
        >>> arrow.get(arw)
        <Arrow [2013-10-23T15:21:54.354846+00:00]>

    One `str`, `float`, or `int`, convertible to a floating-point timestamp, to get that timestamp in UTC:

        >>> arrow.get(1367992474.293378)
        <Arrow [2013-05-08T05:54:34.293378+00:00]>

        >>> arrow.get(1367992474)
        <Arrow [2013-05-08T05:54:34+00:00]>

        >>> arrow.get('1367992474.293378')
        <Arrow [2013-05-08T05:54:34.293378+00:00]>

        >>> arrow.get('1367992474')
        <Arrow [2013-05-08T05:54:34+0struct_time0:00]>

    One ISO-8601-formatted `str`, to parse it:

        >>> arrow.get('2013-09-29T01:26:43.830580')
        <Arrow [2013-09-29T01:26:43.830580+00:00]>

    One `tzinfo`, to get the current time in that timezone:

        >>> arrow.get(tz.tzlocal())
        <Arrow [2013-05-07T22:57:28.484717-07:00]>

    One naive `datetime`, to get that datetime in UTC:

        >>> arrow.get(datetime(2013, 5, 5))
        <Arrow [2013-05-05T00:00:00+00:00]>

    One aware `datetime`, to get that datetime:

        >>> arrow.get(datetime(2013, 5, 5, tzinfo=tz.tzlocal()))
        <Arrow [2013-05-05T00:00:00-07:00]>

    One naive `date`, to get that date in UTC:

        >>> arrow.get(date(2013, 5, 5))
        <Arrow [2013-05-05T00:00:00+00:00]>

    Two arguments, a naive or aware `datetime`, and a timezone expression (as above):

        >>> arrow.get(datetime(2013, 5, 5), 'US/Pacific')
        <Arrow [2013-05-05T00:00:00-07:00]>

    Two arguments, a naive `date`, and a timezone expression (as above):

        >>> arrow.get(date(2013, 5, 5), 'US/Pacific')
        <Arrow [2013-05-05T00:00:00-07:00]>

    Two arguments, both `str`, to parse the first according to the format of the second:

        >>> arrow.get('2013-05-05 12:30:45', 'YYYY-MM-DD HH:mm:ss')
        <Arrow [2013-05-05T12:30:45+00:00]>

    Two arguments, first a `str` to parse and second a `list` of formats to try:

        >>> arrow.get('2013-05-05 12:30:45', ['MM/DD/YYYY', 'YYYY-MM-DD HH:mm:ss'])
        <Arrow [2013-05-05T12:30:45+00:00]>

    Three or more arguments, as for the constructor of a `datetime`:

        >>> arrow.get(2013, 5, 5, 12, 30, 45)
        <Arrow [2013-05-05T12:30:45+00:00]>

    One time.struct time::

          >>> arrow.get(gmtime(0))
          <Arrow [1970-01-01T00:00:00+00:00]>

  `utcnow`()

    Returns an `Arrow` object, representing “now” in UTC time.

    Usage:

        >>> import arrow
        >>> arrow.utcnow()
        <Arrow [2013-05-08T05:19:07.018993+00:00]>

  `now`(tz=None)

    Returns an `Arrow` object, representing “now”.

    Parameters: | tz – (optional) An expression representing a timezone. Defaults to local time.

    Recognized timezone expressions:

    > - A `tzinfo` object.
    > - A `str` describing a timezone, similar to ‘US/Pacific’, or ‘Europe/Berlin’.
    > - A `str` in ISO-8601 style, as in ‘+07:00’.
    > - A `str`, one of the following: ‘local’, ‘utc’, ‘UTC’.

    Usage:

        >>> import arrow
        >>> arrow.now()
        <Arrow [2013-05-07T22:19:11.363410-07:00]>

        >>> arrow.now('US/Pacific')
        <Arrow [2013-05-07T22:19:15.251821-07:00]>

        >>> arrow.now('+02:00')
        <Arrow [2013-05-08T07:19:25.618646+02:00]>

        >>> arrow.now('local')
        <Arrow [2013-05-07T22:19:39.130059-07:00]>

### arrow.api

Provides the default implementation of `ArrowFactory` methods for use as a module API.

`arrow.api.``get`(*args, **kwargs)

  Implements the default `ArrowFactory` `get` method.

`arrow.api.``utcnow`()

  Implements the default `ArrowFactory` `utcnow` method.

`arrow.api.``now`(tz=None)

  Implements the default `ArrowFactory` `now` method.

`arrow.api.``factory`(type)

  Returns an `ArrowFactory` for the specified `Arrow` or derived type.

  Parameters: | type – the type, `Arrow` or derived.

### arrow.locale

`arrow.locales.``get_locale`(name)

  Returns an appropriate `Locale` corresponding to an inpute locale name.

  Parameters: | name – the name of the locale.

class `arrow.locales.``Locale`

  Represents locale-specific data and functionality.

  `describe`(timeframe, delta=0, only_distance=False)

    Describes a delta within a timeframe in plain language.

    Parameters:

    - timeframe – a string representing a timeframe.
    - delta – a quantity representing a delta in a timeframe.
    - only_distance – return only distance eg: “11 seconds” without “in” or “ago” keywords

  `day_name`(day)

    Returns the day name for a specified day of the week.

    Parameters: | day – the `int` day of the week (1-7).

  `day_abbreviation`(day)

    Returns the day abbreviation for a specified day of the week.

    Parameters: | day – the `int` day of the week (1-7).

  `month_name`(month)

    Returns the month name for a specified month of the year.

    Parameters: | month – the `int` month of the year (1-12).

  `month_abbreviation`(month)

    Returns the month abbreviation for a specified month of the year.

    Parameters: | month – the `int` month of the year (1-12).

  `month_number`(name)

    Returns the month number for a month specified by name or abbreviation.

    Parameters: | name – the month name or abbreviation.

  `year_full`(year)

    Returns the year for specific locale if available

    Parameters: | name – the `int` year (4-digit)

  `year_abbreviation`(year)

    Returns the year for specific locale if available

    Parameters: | name – the `int` year (4-digit)

  `meridian`(hour, token)

    Returns the meridian indicator for a specified hour and format token.

    Parameters:

    - hour – the `int` hour of the day.
    - token – the format token.

  `ordinal_number`(n)

    Returns the ordinal format of a given integer

    Parameters: | n – an integer