# whenever > A type-safe Python datetime library with DST-correct arithmetic and distinct instant, zoned, offset, and plain datetime types. ## Pages - [Welcome to Whenever](index.md): **Whenever** is a Python library for working with dates and times. - [The fundamentals of time](fundamentals/index.md): Time isn’t actually that hard once you understand the basic concepts. - [Guide](guide/index.md): This page gives quick overview of the key concepts - [The pitfalls of `datetime`](stdlib-pitfalls/index.md): Python’s `datetime` module first appeared in Python 2.3, released in 2003. - [Ambiguity](fundamentals/ambiguity.md): Time zones describe how the offset from UTC *changes* over time. - [Ambiguity in timezones](guide/ambiguity.md): The API for handling ambiguity is largely inspired by that of - [Arithmetic](fundamentals/arithmetic.md): Arithmetic answers questions like “how many hours passed between these two events?”, - [Arithmetic](guide/arithmetic.md): `whenever` supports differences, additions, and subtractions across all its - [Equality edge cases](stdlib-pitfalls/broken-equality.md): [PEP 495](https://peps.python.org/pep-0495/) introduced the `fold` attribute to - [Changelog](changelog.md): - Add LLM-friendly Markdown documentation, including `llms.txt` and - [Choosing the right type](guide/choosing-a-type.md): While the standard library has a single [`datetime`](https://docs.python.org/3/library/datetime.html... - [Comparison and equality](guide/comparison.md): All types support equality and comparison. - [Contributing](contributing.md): Contributions are welcome, but be sure to read the guidelines below first. - [Converting between types](guide/conversions.md): You can convert between exact types with the [`to_instant()`](../reference/zoned_datetime.md#wheneve... - [`datetime` inherits from `date`](stdlib-pitfalls/date-inheritance.md): You may be surprised to know that `datetime` is a subclass of `date`. - [`Date`](reference/date.md): A date without a time component. - [Main types](reference/datetime.md): The `whenever` library provides four main date-time types, each - [Delta types](reference/deltas.md): As we’ve seen [earlier](../guide/arithmetic.md#add-subtract-time), you can add and subtract - [Working with deltas](guide/deltas.md): This page gives a conceptual overview of the delta types in `whenever`. - [Deprecated components](reference/deprecated.md): Create a [`DateDelta`](#whenever.DateDelta) with the given number of years. - [Design philosophy](design.md): This page describes the guiding principles behind `whenever`’s API. - [Operators ignore DST](stdlib-pitfalls/dst-ignored.md): Arithmetic with `datetime` usually ignores daylight saving time (DST) transitions, - [Exact time vs local time](fundamentals/exact-vs-local.md): Many surprising behaviors in date-time code come from treating different kinds - [Examples](examples.md): This page contains small, practical examples of using `whenever`. - [Exceptions and warnings](reference/exceptions.md): Bases: [`UserWarning`](https://docs.python.org/3/library/exceptions.html#UserWarning) - [FAQ](faq.md): Most of the time, datetime handling isn’t the main bottleneck in Python - [`Instant`](reference/instant.md): A moment in time, independent of any timezone or calendar. - [ISO 8601](reference/iso8601.md): [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) is an international - [`IsoWeekDate`](reference/isoweekdate.md): An ISO 8601 week date—a year, week number, and weekday. - [`ItemizedDateDelta`](reference/itemized_date_delta.md): A date duration that preserves the exact fields it was created with. - [`ItemizedDelta`](reference/itemized_delta.md): A duration that preserves the exact fields it was created with. - [Miscellaneous](reference/misc.md): This section contains API documentation for miscellaneous functions and data - [`MonthDay`](reference/monthday.md): A month and day without a year component. - [One type for everything](stdlib-pitfalls/naive-aware.md): Python uses a single `datetime` type to represent two fundamentally different concepts: - [Inconsistent role of “naive”](stdlib-pitfalls/naive-meaning.md): In various parts of the standard library, “naive” datetimes are interpreted differently. - [`OffsetDateTime`](reference/offset_datetime.md): A datetime with a fixed UTC offset. - [Other types](reference/other-types.md): This section contains API documentation for choice and other types, - [Formatting and parsing](guide/parsing.md): `Whenever` supports formatting and parsing standardized formats - [Partial types](reference/partial-types.md): This section describes the “smaller” date & time types provided by - [Partial types](guide/partial-types.md): Aside from the datetimes themselves, `whenever` also provides - [Pattern format](reference/pattern-format.md): Custom format and parse patterns allow you to format datetime values into - [Performance](performance.md): `whenever` optimizes for three goals that are sometimes in tension: - [`PlainDateTime`](reference/plain_datetime.md): A date and time-of-day without any timezone information. - [Rounding](guide/rounding.md): The API for rounding is largely inspired by that of Temporal (JavaScript) - [Ambiguity passes silently](stdlib-pitfalls/silent-ambiguity.md): When time zone offsets change—most commonly due to daylight saving time—a local - [Standard library conversions](guide/stdlib-convert.md): Most classes have an equivalent in the Python standard library. - [Implicit system time zone](stdlib-pitfalls/system-timezone.md): In the standard library, - [The system timezone](guide/system-tz.md): The system timezone is the timezone that your operating system is set to. - [Testing](guide/testing.md): Sometimes you need to ‘fake’ the output of `.now()` functions, typically for testing. - [`Time`](reference/time.md): Time of day without a date component. - [`TimeDelta`](reference/time_delta.md): A duration consisting of a precise time: hours, minutes, (nano)seconds. - [`timedelta.seconds` footgun](stdlib-pitfalls/timedelta-seconds.md): After subtracting two datetimes, you get a [`timedelta`](https://docs.python.org/3/library/datetime.... - [`timezone` isn’t enough](stdlib-pitfalls/timezone-classes.md): Python offers multiple time zone-related classes, and choosing the right one is not obvious. - [Timezones](fundamentals/timezones.md): [Exact time and local time](exact-vs-local.md#exact-vs-local) are useful on their own, but most real... - [Handling warnings](guide/warnings.md): `whenever` emits warnings when operations may produce incorrect results, - [Why not pendulum?](why-not-pendulum.md): [**Pendulum**](https://pypi.org/project/pendulum/) - [`YearMonth`](reference/yearmonth.md): A year and month without a day component. - [`ZonedDateTime`](reference/zoned_datetime.md): A datetime associated with a timezone from the IANA database. --- For more comprehensive documentation, see [llms-full.txt](llms-full.txt)