Typing stubs for python-dateutil

2.9.0.20260323 · active · verified Sat Mar 28

types-python-dateutil provides static typing stubs for the popular `python-dateutil` library. It allows type checkers like Mypy or Pyright to verify code that uses `python-dateutil`, catching potential type-related errors before runtime. This package is part of the typeshed project and aims to provide accurate annotations for `python-dateutil==2.9.*`. Updates are released frequently, often daily, directly from the typeshed repository. The current version is 2.9.0.20260323.

Warnings

gotcha The `types-python-dateutil` package provides stubs for a specific major/minor version range of `python-dateutil` (e.g., `2.9.*`). Using a significantly different version of the runtime `python-dateutil` library may lead to inaccurate type checking results or errors, as API changes in `python-dateutil` might not be reflected in the stubs for a different version range.
Fix: Always install `types-python-dateutil` that matches the major/minor version of your `python-dateutil` dependency. Pinning versions in your `requirements.txt` (e.g., `python-dateutil==2.9.0` and `types-python-dateutil==2.9.0.YYYYMMDD`) is recommended.
gotcha Type checkers (like Mypy) might sometimes fail to pick up installed stub packages, especially in complex environments or when using tools like `pre-commit` hooks. This can result in 'Missing stubs' errors even when `types-python-dateutil` is installed.
Fix: Ensure your type checker is correctly configured to find third-party stubs. For Mypy in `pre-commit`, you might need to explicitly add `types-python-dateutil` to `additional_dependencies` in your `.pre-commit-config.yaml`. For local runs, ensure `types-python-dateutil` is in your environment's dependencies (e.g., `dev-requirements.txt`).
gotcha While typeshed aims to release stub packages frequently (up to once a day), there can be a slight delay between a new `python-dateutil` release and the corresponding update to `types-python-dateutil`. During this period, very new features or breaking changes in the latest `python-dateutil` might not yet have accurate type annotations.
Fix: Be aware of this potential lag. If you encounter type checking errors or missing annotations for very new `python-dateutil` features, you may need to wait for the next `types-python-dateutil` release or temporarily ignore specific type checking issues. Contributing to typeshed is also an option if you identify missing annotations.
breaking Due to the nature of type stubs, any version bump of `types-python-dateutil` can introduce changes that might cause your code to fail type checking, even if the runtime behavior of `python-dateutil` has not changed. This often happens when stricter or more accurate types are introduced.
Fix: It is advisable to pin the version of `types-python-dateutil` in your project's dependencies to ensure consistent type checking results across builds and environments. Regularly review and update the pinned version to benefit from improved stub accuracy.
gotcha `types-python-dateutil` requires Python >=3.10. Using it with older Python versions might lead to installation issues or type checking inconsistencies if the underlying `python-dateutil` library behaves differently or relies on features not available in older Python versions.
Fix: Ensure your project uses Python 3.10 or newer. If you must support older Python versions, you might need to use an older `types-python-dateutil` version (if available) that is compatible with both your Python version and your `python-dateutil` version, or consider disabling type checking for `dateutil` imports in those environments.

Install

pip install types-python-dateutil Install stubs

Imports

parse
```
from dateutil.parser import parse
```

relativedelta

from dateutil.relativedelta import relativedelta

tz
```
from dateutil import tz
```
UTC
```
from dateutil.tz import UTC
```
As of python-dateutil 2.8.1, tz.UTC is preferred over tz.tzutc() for internal consistency and avoiding an unnecessary function call.

Quickstart

This quickstart demonstrates basic usage of `dateutil.parser.parse` and `dateutil.relativedelta` with type annotations. Installing `types-python-dateutil` provides these annotations, allowing static type checkers to ensure correct usage of `python-dateutil` functions and classes.

from datetime import datetime
from dateutil.parser import parse
from dateutil.relativedelta import relativedelta, MO

# Enable type checking in your editor or via a tool like Mypy
# E.g., run `mypy your_script.py`

def process_date_string(date_str: str) -> datetime:
    """Parses a date string and returns a datetime object."""
    return parse(date_str)

def calculate_future_date(start_date: datetime) -> datetime:
    """Calculates a future date using relativedelta."""
    # Add 1 month and move to the 1st Monday
    return start_date + relativedelta(months=1, weekday=MO(1))

current_time_str: str = "2024-03-28 10:30:00 UTC"
parsed_dt: datetime = process_date_string(current_time_str)
print(f"Parsed datetime: {parsed_dt}")

future_dt: datetime = calculate_future_date(parsed_dt)
print(f"Future datetime: {future_dt}")

# Example where type checker would catch an error (uncomment to test):
# def expects_string(s: str):
#     print(s)
# expects_string(123) # Mypy would report: Argument 's' to 'expects_string' has incompatible type "int"; expected "str"

view raw JSON →