---
myst:
  html_meta:
    description: >-
      API reference for the four main types (Instant, ZonedDateTime,
      OffsetDateTime, PlainDateTime), grouped into exact-time, local-time, and
      shared methods.
---

(api)=
# Main types

```{eval-rst}
.. currentmodule:: whenever
```


The `whenever` library provides four main date-time types, each
with its own purpose and behavior:

```{eval-rst}
.. toctree::
   :maxdepth: 1

   instant
   zoned_datetime
   offset_datetime
   plain_datetime
```

The available methods differ between these types based on whether they
represent {ref}`exact time or local time <exact-vs-local>`:

| type                          | represents exact time? | represents local time? |
|-------------------------------|:----------------------:|:----------------------:|
| {class}`Instant`              |         ✅            |         ❌ 
| {class}`ZonedDateTime`       |          ✅             |    ✅            |
| {class}`OffsetDateTime`      |         ✅             |    ✅            |
| {class}`PlainDateTime`        |         ❌            |        ✅             |



## Exact time methods

The exact time classes ({class}`Instant`, {class}`ZonedDateTime`,
and {class}`OffsetDateTime`) share several methods for working with
exact points in time:


|   | {class}`Instant` | {class}`ZonedDateTime` | {class}`OffsetDateTime`  |
|----|:--------:|:-----:|:------:|
| `now()`  | {meth}`🔗 <Instant.now>`  | {meth}`🔗 <ZonedDateTime.now>` | {meth}`🔗 <OffsetDateTime.now>` |
|    |   |   |   |
|  `timestamp()` [^1] | {meth}`🔗 <Instant.timestamp>`   | {meth}`🔗 <ZonedDateTime.timestamp>` | {meth}`🔗 <OffsetDateTime.timestamp>`  |
| `from_timestamp()` [^2]  | {meth}`🔗 <Instant.from_timestamp>` | {meth}`🔗 <ZonedDateTime.from_timestamp>` | {meth}`🔗 <OffsetDateTime.from_timestamp>`  |
|    |   |   |   |
|  `to_fixed_offset()`  | {meth}`🔗 <Instant.to_fixed_offset>` | {meth}`🔗 <ZonedDateTime.to_fixed_offset>`  | {meth}`🔗 <OffsetDateTime.to_fixed_offset>`   |
|  `to_tz()`  | {meth}`🔗 <Instant.to_tz>`  | {meth}`🔗 <ZonedDateTime.to_tz>` | {meth}`🔗 <OffsetDateTime.to_tz>`                          |
|  `to_system_tz()`  | {meth}`🔗 <Instant.to_system_tz>` | {meth}`🔗 <ZonedDateTime.to_system_tz>` | {meth}`🔗 <OffsetDateTime.to_system_tz>` |
|    |   |   |   |
|  `x > other_exact` [^3]  | {meth}`🔗 <Instant.__gt__>`    | {meth}`🔗 <ZonedDateTime.__gt__>`    | {meth}`🔗 <OffsetDateTime.__gt__>`   |
|  `x - other_exact`  | {meth}`🔗 <Instant.__sub__>`        | {meth}`🔗 <ZonedDateTime.__sub__>`        | {meth}`🔗 <OffsetDateTime.__sub__>`       |
|  `x == other_exact`  | {meth}`🔗 <Instant.__eq__>`        | {meth}`🔗 <ZonedDateTime.__eq__>`        | {meth}`🔗 <OffsetDateTime.__eq__>`       |
|  `exact_eq()`  | {meth}`🔗 <Instant.exact_eq>`       | {meth}`🔗 <ZonedDateTime.exact_eq>`       | {meth}`🔗 <OffsetDateTime.exact_eq>`      |
|    |   |   |   |
|  `x + TimeDelta`  | {meth}`🔗 <Instant.__add__>` | {meth}`🔗 <ZonedDateTime.__add__>`  | {meth}`🔗 <OffsetDateTime.__add__>` |


## Local time methods

The local time classes ({class}`PlainDateTime`, {class}`ZonedDateTime`,
and {class}`OffsetDateTime`) share several methods for working with
local date and time values:


|    | {class}`PlainDateTime`                                           | {class}`ZonedDateTime`                                           | {class}`OffsetDateTime`                                            |
|----|:--------:|:-----:|:------:|
| `year`, `month`, etc.  | {attr}`🔗 <PlainDateTime.year>`  | {attr}`🔗 <ZonedDateTime.year>`  | {attr}`🔗 <OffsetDateTime.year>`  |
| `hour`, `minute`, etc. | {attr}`🔗 <PlainDateTime.hour>` | {attr}`🔗 <ZonedDateTime.hour>` | {attr}`🔗 <OffsetDateTime.hour>` |
| `date()`                                      | {meth}`🔗 <PlainDateTime.date>`                                      | {meth}`🔗 <ZonedDateTime.date>`                                      | {meth}`🔗 <OffsetDateTime.date>`                                       |
| `time()`                                      | {meth}`🔗 <PlainDateTime.time>`                                      | {meth}`🔗 <ZonedDateTime.time>`                                      | {meth}`🔗 <OffsetDateTime.time>`                                       |
|    |   |   |
| `replace()` [^4]                              | {meth}`🔗 <PlainDateTime.replace>`                              | {meth}`🔗 <ZonedDateTime.replace>`                              | {meth}`🔗 <OffsetDateTime.replace>`                               |
| `add()`, `subtract()`      | {meth}`🔗 <PlainDateTime.add>`, {meth}`🔗 <PlainDateTime.subtract>`      | {meth}`🔗 <ZonedDateTime.add>`, {meth}`🔗 <ZonedDateTime.subtract>`      | {meth}`🔗 <OffsetDateTime.add>`, {meth}`🔗 <OffsetDateTime.subtract>`      |
| `since()`, `until()`      | {meth}`🔗 <PlainDateTime.since>`, {meth}`🔗 <PlainDateTime.until>`      | {meth}`🔗 <ZonedDateTime.since>`, {meth}`🔗 <ZonedDateTime.until>`      | {meth}`🔗 <OffsetDateTime.since>`, {meth}`🔗 <OffsetDateTime.until>`      |
| `round()`                                     | {meth}`🔗 <PlainDateTime.round>`                                     | {meth}`🔗 <ZonedDateTime.round>`                                     | {meth}`🔗 <OffsetDateTime.round>`                                      |
|    |   |   |
| `start_of()`, `end_of()`    | {meth}`🔗 <PlainDateTime.start_of>`, {meth}`🔗 <PlainDateTime.end_of>`    | {meth}`🔗 <ZonedDateTime.start_of>`, {meth}`🔗 <ZonedDateTime.end_of>`    | {meth}`🔗 <OffsetDateTime.start_of>`, {meth}`🔗 <OffsetDateTime.end_of>`    |
|    |   |   |
| `day_of_year()`              | {meth}`🔗 <PlainDateTime.day_of_year>`                                 | {meth}`🔗 <ZonedDateTime.day_of_year>`                                 | {meth}`🔗 <OffsetDateTime.day_of_year>`                                  |
| `days_in_month()`            | {meth}`🔗 <PlainDateTime.days_in_month>`                               | {meth}`🔗 <ZonedDateTime.days_in_month>`                               | {meth}`🔗 <OffsetDateTime.days_in_month>`                                |
| `days_in_year()`             | {meth}`🔗 <PlainDateTime.days_in_year>`                                | {meth}`🔗 <ZonedDateTime.days_in_year>`                                | {meth}`🔗 <OffsetDateTime.days_in_year>`                                 |
| `in_leap_year()`             | {meth}`🔗 <PlainDateTime.in_leap_year>`                                | {meth}`🔗 <ZonedDateTime.in_leap_year>`                                | {meth}`🔗 <OffsetDateTime.in_leap_year>`                                 |


:::{note}
Although {class}`Instant`'s debug representation is in
UTC, it does not have local time methods.
See the {ref}`FAQ <faq-instant-no-local>` for more details.
:::

## Other methods

Several other methods are unique to one or more classes:

| {class}`Instant`                           | {class}`ZonedDateTime`                  | {class}`OffsetDateTime`                | {class}`PlainDateTime`                                 |
|--------------------------------------------|-----------------------------------------|----------------------------------------|-------------------------------------------------------|
| {attr}`~Instant.MIN`, {attr}`~Instant.MAX` |                                         |                                        | {attr}`~PlainDateTime.MIN`, {attr}`~PlainDateTime.MAX` |
| {meth}`~Instant.from_utc`                  |                                         |                                        |                                                        |
| {attr}`~Instant.format_rfc2822`            |                                         | {meth}`~OffsetDateTime.format_rfc2822` |                                                        |
|                                            | {meth}`~ZonedDateTime.to_instant`       | {meth}`~OffsetDateTime.to_instant`     |                                                        |
|                                            | {meth}`~ZonedDateTime.to_plain`         | {meth}`~OffsetDateTime.to_plain`       |                                                        |
|                                            | {attr}`~ZonedDateTime.offset`           | {attr}`~OffsetDateTime.offset`         |                                                        |
|                                            |                                         |                                        | {meth}`x == other_plain <PlainDateTime.__eq__>`        |
|                                            |                                         |                                        | {meth}`x > other_plain <PlainDateTime.__gt__>`         |
|                                            |                                         |                                        | {meth}`x - other_plain <PlainDateTime.__sub__>`         |
|                                            |                                         |                                        | {meth}`~PlainDateTime.assume_utc`                      |
|                                            |                                         | {meth}`~OffsetDateTime.assume_tz`      | {meth}`~PlainDateTime.assume_tz`                       |
|                                            |                                         |                                        | {meth}`~PlainDateTime.assume_system_tz`                |
|                                            |                                         |                                        | {meth}`~PlainDateTime.assume_fixed_offset`             |
|                                            |                                         | {meth}`~OffsetDateTime.parse_strptime` *(deprecated)* | {meth}`~PlainDateTime.parse_strptime` *(deprecated)*                  |
|                                            | {attr}`~ZonedDateTime.tz`               |                                        |                                                        |
|                                            | {meth}`~ZonedDateTime.now_in_system_tz` |                                        |                                                        |
|                                            | {meth}`~ZonedDateTime.is_ambiguous`     |                                        |                                                        |
|                                            | {meth}`~ZonedDateTime.dst_offset`       |                                        |                                                        |
|                                            | {meth}`~ZonedDateTime.tz_abbrev`        |                                        |                                                        |
|                                            | {meth}`~ZonedDateTime.day_length`       |                                        |                                                        |
|                                            | {meth}`~ZonedDateTime.next_transition`  |                                        |                                                        |
|                                            | {meth}`~ZonedDateTime.prev_transition`  |                                        |                                                        |
|                                            | {meth}`~ZonedDateTime.start_of_day` *(deprecated)* |                                        |                                                        |


[^1]: `timestamp_millis()` and `timestamp_nanos()` methods are also
    available for millisecond and nanosecond precision.

[^2]: `from_timestamp_millis()` and `from_timestamp_nanos()` methods are
    also available for millisecond and nanosecond precision.

[^3]: The other comparison operators `<=`, `<`, and `>=` are also
    supported.

[^4]: `replace_date()` and `replace_time()` are also available for
    replacing only the date or time component.