Handling warnings¶

whenever emits warnings when operations may produce incorrect results, for example due to DST transitions, missing context, or field-wise composition of calendar units. This is intentional: the operations are classic “footguns”, but forbidding them entirely would be too strict. Warnings are an ideal mechanism to ensure the potential issues don’t pass unnoticed.

All whenever warnings are subclasses of WheneverWarning, which is itself a subclass of Python’s built-in UserWarning. DST-related warnings are grouped under PotentialDstBugWarning. They fit into Python’s standard warnings infrastructure fully, giving you several levels of control.

UserWarning (stdlib)
└── WheneverWarning
    ├── CalendarUnitCompositionWarning
    ├── PotentialDstBugWarning
    │   ├── DaysAssumed24HoursWarning
    │   ├── NaiveArithmeticWarning
    │   └── StaleOffsetWarning
    └── WheneverDeprecationWarning

Turn warnings into errors¶

The most robust approach for production code is to turn whenever warnings into exceptions as early as possible — typically in your module’s setup or at the top of your application entry point:

import warnings
import whenever

warnings.filterwarnings("error", category=whenever.WheneverWarning)

If you only want to target DST-related warnings:

warnings.filterwarnings("error", category=whenever.PotentialDstBugWarning)

Any code that triggers a matching warning now raises an exception immediately, forcing you (or your CI) to address it. This is the same principle as PYTHONWARNINGS=error but scoped to whenever’s warning hierarchy only.

To target a specific warning type instead:

# Only error on timezone-unaware arithmetic (PlainDateTime):
warnings.filterwarnings("error", category=whenever.NaiveArithmeticWarning)

# Only error on potentially stale offset operations (OffsetDateTime):
warnings.filterwarnings("error", category=whenever.StaleOffsetWarning)

In pytest¶

When running tests, it’s highly recommended to turn whenever warnings into errors so tests catch potential issues. Add this to your pytest.ini (or the [tool.pytest.ini_options] table in pyproject.toml):

[pytest]
filterwarnings =
    error::whenever.WheneverWarning

Or to target only one module of your project (leaving third-party libraries unaffected):

[pytest]
filterwarnings =
    error::whenever.WheneverWarning:mymodule.*

Command-line filter not supported

Unfortunately, passing PYTHONWARNINGS=error::whenever.WheneverWarning on the command line does not work, due to a limitation in CPython: the command-line filter only accepts built-in warning classes by name, not third-party ones. Use pytest.ini, pyproject.toml, or a call to warnings.filterwarnings() in your code instead.

In a specific module¶

You can also apply a filter at the top of a module, so it applies to all code in that module without touching other modules:

# mymodule/scheduling.py
import warnings
import whenever

warnings.filterwarnings(
    "error",
    category=whenever.WheneverWarning,
    module=r"mymodule\.scheduling"  # or re.escape(__name__)
)

Suppress specific calls¶

Sometimes an operation is deliberately imprecise — and that’s fine, as long as the decision is conscious and documented. Each method that may emit a DST-related warning accepts a boolean keyword argument that suppresses it:

Keyword argument	Suppresses	Used on
`days_assumed_24h_ok=True`	`DaysAssumed24HoursWarning`	`TimeDelta` methods, `Instant` `add`/`subtract`
`stale_offset_ok=True`	`StaleOffsetWarning`	`OffsetDateTime` methods
`naive_arithmetic_ok=True`	`NaiveArithmeticWarning`	`PlainDateTime` methods
`cal_unit_composition_ok=True`	`CalendarUnitCompositionWarning`	`ItemizedDelta` and `ItemizedDateDelta` `add`/`subtract`

For example:

from whenever import PlainDateTime

# Naive arithmetic is acceptable here because <insert reason>
next_departure = scheduled.add(hours=1, naive_arithmetic_ok=True)

The keyword argument documents the decision at the call site while keeping the suppression limited to exactly one operation.

Note

These keyword arguments supersede the ignore_dst keyword argument (deprecated in 0.10).

Operators¶

The + and - operators always emit warnings when applicable, because operators cannot accept keyword arguments. Use the method equivalents instead:

dt + delta → dt.add(delta, ...)
dt - delta → dt.subtract(delta, ...)
dt_a - dt_b → dt_a.difference(dt_b) (for PlainDateTime, pass naive_arithmetic_ok=True)

For itemized-delta composition, operators emit CalendarUnitCompositionWarning when either operand contains nonzero calendar units. Exact-only composition does not warn. Use the method form if you want to pass cal_unit_composition_ok=True instead of relying on a global warning filter.

Alternatively, suppress operator warnings with Python’s standard warnings.filterwarnings().

Using Python’s warnings infrastructure¶

Since whenever warnings are standard Python warnings, you can also suppress them with warnings.catch_warnings:

import warnings
import whenever

with warnings.catch_warnings():
    warnings.simplefilter("ignore", whenever.StaleOffsetWarning)
    # ... all stale-offset warnings suppressed inside this block

This is useful when you want to blanket-suppress warnings for a block of code or for operators (which can’t take keyword arguments).

Limitation before Python 3.14

Before Python 3.14, warnings.catch_warnings is not context-safe: in concurrent code (threads or async tasks) the suppression filter may leak to other contexts, or other contexts may interfere with yours. This is a known CPython limitation addressed by the PYTHON_CONTEXT_AWARE_WARNINGS flag introduced in Python 3.14.

The per-method keyword arguments described above don’t have this limitation — they suppress the warning for exactly one call, regardless of concurrency.

Exploratory use and scripts¶

When hacking around or writing a quick script, you may simply want to silence all whenever warnings globally and move on:

import warnings
import whenever

warnings.filterwarnings("ignore", category=whenever.WheneverWarning)

This is fine for exploration. If you later promote the code to production, revisit the suppressed warnings and decide for each one whether to fix the underlying issue or suppress it explicitly with the appropriate keyword argument.

Choosing the right approach¶

Situation	Recommended approach
Production code	`filterwarnings("error", ...)` at startup
CI / test suite	`filterwarnings = error::whenever.WheneverWarning` in `pytest.ini`
One intentional imprecision	Per-method kwarg (e.g. `naive_arithmetic_ok=True`) + a comment
Suppress operator warnings	`warnings.catch_warnings()` block (Python ≥ 3.14 for concurrency safety)
Entire module intentionally imprecise	`filterwarnings("ignore", ..., module=r"mymodule\.*")`
Exploratory scripts	`filterwarnings("ignore", ...)` globally