# attotime Release 0.3.0

Arbitrary precision datetime library.

Keywords
datetime, decimal
BSD-3-Clause
Install
``` pip install attotime==0.3.0 ```

## Features

• Fractional nanosecond resolution using Python decimal module
• API as close to Python's native datetime implementation as possible
• Python 3 support

## attotimedelta

`attotimedelta` objects represent the difference between two dates or times. It wraps a native timedelta object, and stores fractional nanoseconds as a `Decimal`.

### class attotime.attotimedelta([days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks[, nanoseconds]]]]]]]])

All arguments are optional and default to 0. All arguments may be ints, longs, or floats, and may be positive or negative.

Only days, seconds, microseconds, and nanoseconds are stored internally. days, seconds, and microseconds are stored in a native timedelta object, nanoseconds are contained in a `Decimal`.

• `days` Between -999999999 and 999999999 inclusive.
• `seconds` Between 0 and 86399 inclusive.
• `microseconds` Between 0 and 999999 inclusive.
• `nanoseconds` A `Decimal` between 0 and 999 inclusive.

### Supported operations

• `td1 = td2 + td3` Sum of td2 and td3.
• `td1 = td2 - td3` Difference of td2 and td3.
• `td1 = i * td2` or `td1 = td2 * i` Delta multiplied by an integer, long, float, or `Decimal`.
• `td1 = td2 // i` Computes the floor, discarding the remainder.
• `+td1` Returns an `attotimedelta` with the same value.
• `-td1` Equivalent to `td1 * -1`.
• `abs(td1)` Equivalent to `+td1` when `td1.days >= 0`, `-td1` when `t1.days < 0`.
• `str(td1)` Returns a string in the form `[D day[s], ][H]H:MM:SS[.UUUUUU]`, where `D` is negative for `td1 < 0` and `UUUUUU` can be expanded for up to 16 place fixed point.
• `repr(td1)` Returns a string in the form `attotime.attotimedelta(D[, S[, U]])`, where `D` is negative for `td1 < 0`.

### Instance methods

#### attotimedelta.total_seconds()

Return the total number of seconds contained in the duration as a `Decimal`.

#### attotimedelta.total_nanoseconds()

Return the total number of nanoseconds contained in the duration as a `Decimal`.

## attodatetime

`attodatetime` is a single object wrapping a native date object and an `attotime` object for the purposes of storing date and time information with fractional nanoseconds stored as a `Decimal`.

### class attotime.attodatetime(year, month, day[, hour[, minute[, second[, microsecond[, nanosecond[, tzinfo]]]]]])

Year, month, and day are required. `tzinfo` may be `None`, or an instance of a tzinfo subclass. The nanosecond argument may be a float or `Decimal`. The remaining arguments may be ints or longs.

### Class methods

#### attodatetime.today()

Raises NotImplementedError

#### attodatetime.now([tz])

Raises NotImplementedError

#### attodatetime.utcnow()

Raises NotImplementedError

#### attodatetime.fromtimestamp(timestamp, [tz])

Raises NotImplementedError

#### attodatetime.utcfromtimestamp(timestamp)

Raises NotImplementedError

#### attodatetime.fromordinal(ordinal)

Return an `attodatetime` corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1. ValueError is raised unless 1 <= ordinal <= `datetime.max.toordinal()` (note native Python `datetime` range checking). The hour, minute, second and microsecond of the result are all 0, and `tzinfo` is `None`.

#### attodatetime.combine(date, time)

Return an `attodatetime` object whose date components are equal to the given date objectâ€™s, and whose time components and `tzinfo` attributes are equal to the given time objectâ€™s. If date is a `attodatetime` (or native Python `datetime`), its time components and `tzinfo` attributes are ignored.

#### attodatetime.strptime(date_string, format)

Raises NotImplementedError

• `year` Between Python native `datetime` `MINYEAR` and `MAXYEAR`, inclusive.
• `month` Between 1 and 12 inclusive.
• `day` Between 1 and the number of days in the given month of the given year.
• `hour` In `range(24)`.
• `minute` In `range(60)`.
• `second` In `range(60)`.
• `microsecond` In `range(1000000)`.
• `nanosecond` In `range(1000)`, as `Decimal`.
• `tzinfo` The object passed as the `tzinfo` argument to the `attodatetime` constructor, or `None` if none was passed.

### Supported operations

• `dt2 = dt1 + td` dt1 moved forward the duration of the `attotimedelta` if `attotimedelta.days > 0`, or backward if `attotimedelta.days < 0`.
• `dt2 = dt1 - td` dt1 moved backward the duration of the `attotimedelta` if `attotimedelta.days > 0`, or forward if `attotimedelta.days < 0`.
• `td = dt1 - dt2` The duration of time between dt1 and dt2, as an `attotimedelta`.
• `dt1 < dt2` dt1 is considered less than dt2 if dt1 precedes dt2 in time.
• `str(dt1)` Equivalent to `dt1.isoformat(separator=' ')`.
• `repr(dt1)` Returns a string in the form `attotime.attodatetime(Y, M, D, h, m, s, us, ns, [tz])`.

### Instance methods

#### attodatetime.date()

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

#### attodatetime.time()

Return an `attotime` object with the same hour, minute, second, microsecond, and nanosecond. `tzinfo` is `None`.

#### attodatetime.timetz()

Return an `attotime` object with the same hour, minute, second, microsecond, nanosecond, and `tzinfo` attributes.

#### attodatetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, nanosecond[, tzinfo]]]]]]]]])

Return an `attodatetime` object with the same attributes, except for those attributes given new values by whichever keyword arguments are specified. Note that `tzinfo=None` can be specified to create a naive `attodatetime` from an aware `attodatetime` with no conversion of date and time data.

#### attodatetime.astimezone(tz)

Raises NotImplementedError

#### attodatetime.utcoffset()

If `tzinfo` is `None`, returns `None`, else return `self.tzinfo.utcoffset(self)` as an `attotimedelta`.

#### attodatetime.dst()

If `tzinfo` is `None`, returns `None`, else return `self.tzinfo.dst(self)` as an `attotimedelta`.

#### attodatetime.tzname()

If `tzinfo` is `None`, returns `None`, else returns `self.tzinfo.tzname(self)`.

#### attodatetime.timetuple()

Return the result of datetime.timetuple() for a native Python `datetime` matching the `attodatetime`. Nanosecond precision is lost.

#### attodatetime.utctimetuple()

Return the result of datetime.utctimetuple() for a native Python `datetime` matching the `attodatetime`. Nanosecond precision is lost.

#### attodatetime.toordinal()

Return the proleptic Gregorian ordinal of the date. The same as `self.date().toordinal()`.

#### attodatetime.weekday()

Return the day of the week as an integer, where Monday is 0 and Sunday is 6. The same as `self.date().weekday()`.

#### attodatetime.isoweekday()

Return the day of the week as an integer, where Monday is 1 and Sunday is 7. The same as `self.date().isoweekday()`.

#### attodatetime.isocalendar()

Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same as `self.date().isocalendar()`.

#### attodatetime.isoformat([sep])

Return a string representing the date and time in ISO 8601 format, `YYYY-MM-DDTHH:MM:SS.mmmmmm` or, if microsecond is 0, `YYYY-MM-DDTHH:MM:SS`

If `utcoffset()` does not return `None`, a 6-character string is appended, giving the UTC offset in (signed) hours and minutes: `YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM` or, if microsecond is 0 `YYYY-MM-DDTHH:MM:SS+HH:MM`

The optional argument `sep` (default 'T') is a separator, placed between the date and time portions of the result.

The decimal second component may be expanded up to 16 place fixed point.

#### attodatetime.ctime()

Return the result of datetime.ctime() for a native Python `datetime` matching the `attodatetime`. Nanosecond precision is lost.

#### attodatetime.strftime(format)

Raises NotImplementedError

## attotime

`attotime` is an object wrapping a native time object along with fractional nanoseconds stored as a `Decimal`.

### class attotime.attotime([hour[, minute[, second[, microsecond[, nanosecond[, tzinfo]]]]]])

All arguments are optional. `tzinfo` may be `None`, or an instance of a tzinfo subclass. The nanosecond argument may be float or `Decimal`. The remaining arguments may be ints or longs.

• `hour` In `range(24)`.
• `minute` In `range(60)`.
• `second` In `range(60)`.
• `microsecond` In `range(1000000)`.
• `nanosecond` In `range(1000)`, as `Decimal`.
• `tzinfo` The object passed as the `tzinfo` argument to the `attotime` constructor, or `None` if none was passed.

### Supported operations

• `t1 < t2` t1 is considered less than t2 if t1 precedes t2 in time.
• `str(t1)` Equivalent to `t1.isoformat()`.
• `repr(t1)` Returns a string in the form `attotime.attotime(h, m, s, us, ns, [tz])`.

### Instance methods

#### attotime.replace([hour[, minute[, second[, microsecond[, nanosecond[, tzinfo]]]]]])

Return an `attotime` object with the same attributes, except for those attributes given new values by whichever keyword arguments are specified. Note that `tzinfo=None` can be specified to create a naive `attotime` from an aware `attotime` with no conversion of date and time data.

#### attotime.isoformat()

Return a string representing the time in ISO 8601 format, `HH:MM:SS.mmmmmm` or, if microsecond is 0, `HH:MM:SS`

If `utcoffset()` does not return `None`, a 6-character string is appended, giving the UTC offset in (signed) hours and minutes: `HH:MM:SS.mmmmmm+HH:MM` or, if microsecond is 0 `HH:MM:SS+HH:MM`

The decimal second component may be expanded up to 16 place fixed point.

#### attotime.strftime(formatstr)

Raises NotImplementedError

#### attotime.utcoffset()

If `tzinfo` is `None`, returns `None`, else return `self.tzinfo.utcoffset(self)` as an `attotimedelta`.

#### attotime.dst()

If `tzinfo` is `None`, returns `None`, else return `self.tzinfo.dst(self)` as an `attotimedelta`.

#### attotime.tzname()

If `tzinfo` is `None`, returns `None`, else returns `self.tzinfo.tzname(self)`.

## Tests

To run the unit tests, navigate to the source directory and run the tests for the python version being worked on (python2, python3):

```\$ python2 -m unittest discover attotime/tests/
```

or:

```\$ python3 -m unittest discover attotime/tests/
```

## Contributing

attotime is an open source project hosted on Bitbucket.

Any and all bugs are welcome on our issue tracker. Of particular interest are places where the attotime implementation incorrectly deviates from native Python behavior. Pull requests containing unit tests or fixed bugs are always welcome!