Dateparser

1.4.0 · active · verified Sat Mar 28

Dateparser is a Python library (v1.4.0) designed to parse dates from various formats, including natural language and localized strings, often found on web pages. It aims to simplify datetime string conversion, timezone handling, and ambiguous date resolution. The library has an active development cycle with minor versions released every few months, frequently adding new language support and parsing features.

Warnings

breaking Python 3.9 support was dropped in `dateparser` v1.3.0. Ensure your environment uses Python 3.10 or newer.
Fix: Upgrade to Python >=3.10.
breaking In v1.4.0, security fixes removed import-time loading of timezone offset data from pickle and replaced `eval()` use with strict boolean parsing for `no_word_spacing`. Users relying on custom deserialized data or specific locale metadata processing might experience changes.
Fix: Review any custom logic that interacted with locale metadata or expected specific deserialization behavior. Adapt to stricter parsing rules.
breaking In v1.0.0, `DateDataParser.get_date_data()` changed its return type from a `dict` to a `DateData` object. Additionally, providing wrong settings now raises `SettingValidationError` instead of being silently ignored.
Fix: Update code expecting a dictionary from `get_date_data()` to handle a `DateData` object. Validate settings passed to avoid `SettingValidationError`.
gotcha Dateparser returns naive `datetime` objects by default if the input string lacks timezone information. To ensure timezone-aware `datetime` objects, specify `TIMEZONE` and `RETURN_AS_TIMEZONE_AWARE=True` in settings.
Fix: Pass `settings={'TIMEZONE': 'UTC', 'RETURN_AS_TIMEZONE_AWARE': True}` (or your desired timezone) to `dateparser.parse()` for consistent timezone-aware results.
gotcha Ambiguous date formats (e.g., '03/11/2024') can lead to incorrect parsing (e.g., MM/DD/YYYY vs. DD/MM/YYYY). To resolve this, explicitly set the `DATE_ORDER` setting or provide known `languages` or `locales`.
Fix: Use `settings={'DATE_ORDER': 'DMY'}` (or 'MDY', 'YMD' as appropriate) or `languages=['en-US']` to guide the parser.
gotcha When parsing incomplete dates (e.g., 'March 15', '2024'), the library fills in missing components based on current date context. For consistent behavior, use `PREFER_DATES_FROM`, `PREFER_DAY_OF_MONTH`, or `PREFER_MONTH_OF_YEAR` settings.
Fix: Configure settings like `settings={'PREFER_DATES_FROM': 'past'}` or `{'PREFER_MONTH_OF_YEAR': 'last'}` to control how missing date parts are inferred.

Install

pip install dateparser Basic Installation
pip install dateparser[calendars] With Calendar Support (e.g., Hijri, Jalali)

Imports

parse
```
from dateparser import parse
```
DateDataParser
```
from dateparser.date import DateDataParser
```
For advanced use cases like caching detected languages and custom parsing behavior.

Quickstart

The most common way to parse dates is using the `dateparser.parse()` function. It automatically detects formats and languages, and can be configured with settings for more control, such as handling relative dates or specific timezones.

import dateparser
from datetime import datetime

# Basic parsing
date_obj1 = dateparser.parse('12/12/12')
print(f"'12/12/12' parsed as: {date_obj1}")

# Parsing a relative date
date_obj2 = dateparser.parse('2 days ago')
print(f"'2 days ago' parsed as: {date_obj2}")

# Parsing a date with specific language settings
date_obj3 = dateparser.parse('Martes 21 de Octubre de 2014', languages=['es'])
print(f"'Martes 21 de Octubre de 2014' (Spanish) parsed as: {date_obj3}")

# Parsing with timezone preference
date_obj4 = dateparser.parse('August 14, 2015 EST', settings={'TIMEZONE': 'America/New_York', 'RETURN_AS_TIMEZONE_AWARE': True})
print(f"'August 14, 2015 EST' with timezone preference: {date_obj4}")

view raw JSON →