Typing Stubs for dateparser

1.4.0.20260408 · active · verified Sat Apr 11

types-dateparser is a type stub package that provides external type annotations for the `dateparser` library. It enables static type checkers (like MyPy or Pyright) to analyze code using `dateparser` for type correctness without affecting runtime behavior. The current version, `1.4.0.20260408`, indicates it aims to provide accurate annotations for `dateparser~=1.4.0`, with the last part reflecting the typeshed release date. Updates are frequent, often daily, reflecting typeshed's continuous integration and bug fixes.

Warnings

gotcha Do not attempt to import symbols directly from `types_dateparser`. This package is purely for static type analysis and does not contain runtime code. Importing from it will result in `ModuleNotFoundError` or incorrect behavior.
Fix: Always import from the `dateparser` package for runtime functionality: `import dateparser` or `from dateparser import parse`.
gotcha Ensure the `X.Y.Z` part of `types-dateparser`'s version aligns with the installed version of `dateparser`. For example, `types-dateparser==1.4.0.YYYYMMDD` is intended for `dateparser~=1.4.0`. Mismatched versions can lead to inaccurate type checking results, where the stubs describe an API different from your installed runtime library.
Fix: Pin the `types-dateparser` version to match your `dateparser` dependency's major/minor/patch versions (e.g., `pip install 'dateparser==1.4.0' 'types-dateparser==1.4.0.*'`).
gotcha Explicitly configuring `MYPYPATH` or similar environment variables for `types-dateparser` is usually unnecessary. Modern type checkers automatically discover installed stub packages in your Python environment. Manual configuration can sometimes lead to issues if paths are incorrect or conflict with automatic discovery.
Fix: Rely on your type checker's automatic stub discovery mechanism. Only use explicit path configurations if you are developing stubs or facing specific advanced scenarios.
breaking As `types-dateparser` reflects the API of `dateparser`, major or even minor breaking changes in `dateparser`'s API will eventually be mirrored in the stubs. This may cause type-checking errors in your project even if `dateparser`'s runtime code still functions due to its internal backward compatibility mechanisms.
Fix: Review `dateparser`'s release notes for breaking changes and update your code and type annotations accordingly. Update `types-dateparser` in conjunction with `dateparser` to maintain type accuracy.

Install

pip install types-dateparser Install package

Imports

parse
```
from dateparser import parse
```
The `types-dateparser` package provides static type hints for the `dateparser` library. It is not meant for direct import at runtime. Type checkers automatically discover and use these stubs when `dateparser` is imported.

Quickstart

This quickstart demonstrates the typical usage of the `dateparser` library, which is enhanced by the `types-dateparser` stubs for static type checking. The stubs themselves are not directly used in the runtime code.

import dateparser
from datetime import datetime

# types-dateparser provides type hints for the dateparser library.
# It is not imported directly for runtime functionality.

date_string = "today"
parsed_date: datetime | None = dateparser.parse(date_string)

if parsed_date:
    print(f"Parsed '{date_string}': {parsed_date}")
else:
    print(f"Could not parse '{date_string}'")

# Example with a specific format and language setting
french_date_string = "20 Février 2023"
parsed_french_date: datetime | None = dateparser.parse(
    french_date_string, languages=['fr']
)
if parsed_french_date:
    print(f"Parsed '{french_french_date_string}' (French): {parsed_french_date}")

view raw JSON →