datefinder

library1.0.0pypypi✓ verified 25d ago

Datefinder is a Python library designed to extract datetime objects from natural language text. It supports various date and time formats, including relative and absolute expressions. The current version is 1.0.0, and it follows an active release cadence, with a recent major update shifting its default parsing engine.

data

pip install datefinder

github ↗package ↗

INSTALL

IMPORT

SIG · DATEFINDER

datefinder

datapythonv1.0.0

Install

2.6s avg

Import

445ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.484s · 27.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.406s · 28MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

find_dates

✓ from datefinder import find_dates

find_dates_legacy

✓ from datefinder import find_dates_legacy

Use this for behavior compatible with datefinder < 1.0.0, which used the 'legacy' engine by default.

extract

✓ from datefinder import extract

For typed extraction of absolute, relative, and duration values.

This quickstart demonstrates how to use `find_dates` to extract datetime objects from a string. It iterates through the returned `DateMatch` objects, printing both the original substring found and the parsed `datetime` object. It also shows how to explicitly specify the 'legacy' engine for pre-1.0.0 behavior.

from datefinder import find_dates text = "I have a meeting on October 25th, 2024 at 3 PM and another one next Tuesday." print("Dates found:") for match in find_dates(text): print(f" Match: '{match.substring}' -> Datetime: {match.datetime}") # To use the legacy engine (pre-1.0.0 behavior) print("\nDates found (legacy engine):") for match in find_dates(text, engine='legacy'): print(f" Match: '{match.substring}' -> Datetime: {match.datetime}")

Debug

Known issues

breakingIn version 1.0.0, the default parsing engine for `find_dates` changed from 'legacy' to a new 'v2' engine. This may alter results or introduce breaking changes if your application relied on specific behaviors of the 'legacy' engine.

fix

If you need the pre-1.0.0 behavior, either use `find_dates(..., engine='legacy')` or import and use `find_dates_legacy` directly.

affects: >=1.0.0

gotchaThe `find_dates` function returns an iterable of `DateMatch` objects, not raw `datetime` objects directly. Each `DateMatch` object contains the extracted `datetime` object via its `.datetime` attribute, and the original matched string via `.substring`.

fix

Always iterate over the results and access the `.datetime` attribute, e.g., `for match in find_dates(text): date_obj = match.datetime`.

affects: All

breakingSupport for Python 2 was dropped in version 0.7.0. Older applications running on Python 2 will need to upgrade their Python version to use recent datefinder releases.

fix

Upgrade your Python environment to Python 3.9 or newer to use datefinder 1.0.0 and above.

affects: >=0.7.0

gotchaBy default, `datefinder` returns naive `datetime` objects (without timezone information) unless explicit timezone details are present in the input text. If timezone awareness is critical, you must handle it separately.

fix

Explicitly include timezone information in your input text for `datefinder` to parse it, or apply a default timezone to the resulting naive `datetime` objects using `pytz` or `zoneinfo` (Python 3.9+).

affects: All

gotchaThe `strict=True` parameter significantly restricts the types of dates and times `datefinder` will parse, often leading to fewer matches. This can be unexpected if not fully understood.

fix

Understand that `strict=True` aims for higher precision (fewer false positives) at the cost of recall (more false negatives). Test your inputs thoroughly with `strict=True` to ensure it meets your requirements.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'datefinder'

The 'datefinder' package is not installed in the Python environment being used, or there's a mismatch between the installation environment (e.g., terminal) and the execution environment (e.g., Jupyter Notebook).

fix

Install the package using pip: `pip install datefinder` or `!pip install datefinder` in a Jupyter Notebook cell.

IllegalMonthError

This error occurs when datefinder's underlying date parsing engine encounters a string that it interprets as an invalid month while iterating over the results of `find_dates`.

fix

Wrap the iteration over the `find_dates` generator in a `try-except IllegalMonthError` block to gracefully handle and skip problematic date strings.

AttributeError: 'list' object has no attribute 'strftime'

`datefinder.find_dates()` returns a generator of `datetime` objects. If this generator is converted to a list, and then `strftime` is called directly on the list object instead of on individual `datetime` objects within the list, this error occurs.

fix

Iterate through the list (or generator) of `datetime` objects and apply `.strftime()` to each individual `datetime` object.

AttributeError: module 'regex' has no attribute 'compile'

This error indicates an incompatibility or an outdated version of the 'regex' library, a dependency of 'datefinder', which is missing the `compile` attribute, or datefinder is trying to use an incompatible version of the regex module.

fix

Update both `datefinder` and its dependencies (especially `regex`) to their latest versions using `pip install --upgrade datefinder regex`. If the problem persists, consider reinstalling them in a fresh virtual environment.

Upgrade

Version history

1.0.0latest on PyPI · released Mar 25, 2026

Audit

Dependencies

python-dateutilrequiredRequired for robust date and time parsing, especially for relative dates and various formats.

regexrequiredUsed for advanced regular expression matching, which forms the core of date and time pattern recognition.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/akoumjian/datefinder ↗

packagehttps://pypi.org/project/datefinder/ ↗