datefind

A python module for locating dates within text. Use this package to search for dates and convert them to datetime objects.

Finds dates in many different formats.

• All numeric - 2024-01-01, 01/01/2024, 01012024, etc.
• Natural language - January 1st, 2024, March nineteenth, 2024, twenty fifth of January, Mar 15, 24, etc.
• Fuzzy dates - today, yesterday, tomorrow, last week, this week, next week, etc.
• Relative offsets - 3 days ago, in 2 weeks, 1 year from now, etc.
• Weekdays - Monday, next Friday, last Tuesday, etc.
• Quarters - Q1 2024, 2024 Q3, etc.

Installation

Requires Python 3.11 or higher.

pip install datefind

Usage

from datefind import find_dates

string = "2024-01-01 and 2024-01-02"

for date in find_dates(string, tz="America/New_York"):
    print(date)

>>> FoundDate(
        datetime=datetime.datetime(2024, 1, 1, 0, 0, tzinfo=zoneinfo.ZoneInfo(key='America/New_York')),
        match='2024-01-01',
        span=(0, 10)
    )
>>> FoundDate(
        datetime=datetime.datetime(2024, 1, 2, 0, 0, tzinfo=zoneinfo.ZoneInfo(key='America/New_York')),
        match='2024-01-02',
        span=(15, 25)
    )

find_dates

The find_dates() function is the main entry point for the datefind package. It takes a string of text and returns a generator of Date objects.

Arguments

• text - The text to search for dates.
• first - The first number to find in ambiguous dates. (one of month, day, year) Default is month
• tz - The timezone to use. Defaults to the local timezone.

For each date found, a FoundDate object is returned. The FoundDate object has the following properties:

• datetime - The datetime object.
• match - The matched portion of the text.
• span - The span of the matched text in the original text.

Contributing

See CONTRIBUTING.md for more information.