parsedatetime

Warnings

• breaking The `parse()` method's return value changed significantly around version 2.0. It now consistently returns a tuple `(time_struct, parse_status)`. Code relying on direct `datetime` or `time_struct` return without checking `parse_status` or handling the tuple will break.
  Fix: Always expect a `(time_struct, parse_status)` tuple from `cal.parse()`. Check `parse_status` (0 for failure, 1 for date, 2 for time, 3 for datetime) before converting `time_struct` to a `datetime` object, e.g., `datetime(*time_struct[:6])`.
• deprecated The 'flag style' for instantiating `Calendar()` (e.g., `Calendar(parsedatetime.constants.getConstants())`) was deprecated in version 2.0 in favor of a 'context style'.
  Fix: Instantiate `Calendar()` directly without arguments for default behavior, or use `Calendar(version=parsedatetime.VERSION_CONTEXT_STYLE)` for explicit context-aware parsing if needed, though this is often the default behavior in newer versions.
• gotcha When parsing incomplete human-readable dates (e.g., "Jan 1st"), `parsedatetime` implicitly guesses the year based on the current date (`sourceTime`). This can lead to unexpected results if the inferred year doesn't match expectations, especially for dates far in the past or future.
  Fix: For critical date parsing, always provide a `sourceTime` argument to `cal.parse()` to set a clear reference point, or explicitly include the year in the input string. Example: `cal.parse("Jan 1st", sourceTime=datetime(2025, 6, 1))`.
• gotcha While v2.6 includes Python 2.7 compatibility, the library's development now primarily targets Python 3. Users on older Python 2.x environments may encounter unexpected issues or lack of support in future releases.
  Fix: Prefer using `parsedatetime` in a Python 3 environment. If Python 2.7 is necessary, ensure you are on `parsedatetime` version 2.6 and thoroughly test your parsing logic. Upgrade to Python 3 where possible.

Install

• pip install parsedatetime Latest stable version

Imports

• Calendar

  import parsedatetime
  cal = parsedatetime.Calendar()

  The direct import from `parsedatetime` is the current standard. Older examples or codebases might use `parsedatetime.parsedatetime`.

Quickstart

Initializes the Calendar object and demonstrates parsing a human-readable date/time string, converting the `time.struct_time` output to a standard `datetime` object, and using a `sourceTime` for relative parsing. The `parse()` method returns a tuple: `(time_struct, parse_status)`, where `parse_status` indicates success and the type of information parsed (e.g., date, time, or datetime).

from datetime import datetime
import parsedatetime

cal = parsedatetime.Calendar()

# Parse a human-readable string
time_struct, parse_status = cal.parse("tomorrow at 3pm")

# Convert the result to a Python datetime object
if parse_status != 0:
    dt_object = datetime(*time_struct[:6])
    print(f"Parsed 'tomorrow at 3pm' as: {dt_object}")

# Example with a specific starting point (sourceTime)
from datetime import datetime, timedelta
source_time = datetime(2026, 1, 1, 10, 0, 0) # Jan 1, 2026, 10:00 AM
time_struct_next, _ = cal.parse("next friday", source_time)
dt_object_next = datetime(*time_struct_next[:6])
print(f"Parsed 'next friday' from {source_time} as: {dt_object_next}")