dateperiodparser 0.1.1

A comprehensive date and period parser

dateperiodparser

A python package for parsing natural language periods and dates into standardized date ranges. It is designed to handle a wide variety of date and period formats, including ISO dates, school years, quarters, seasons, multi-year ranges, relative dates, and much more, across varying languages (English, Dutch, etc.).

Installation

You can install the package via pip:

pip install dateperiodparser

Quick Start

from dateperiodparser import DatePeriodParser

parser = DatePeriodParser()

# Parse a specific phrase
results = parser.parse("school year 2025 - 2026")

for r in results:
    # r.start and r.end are datetime objects
    print(f"Start: {r.start.date()} -> End: {r.end.date()}")
    print(f"Matched by: {r.pattern}")

Features and Examples

The DatePeriodParser utilizes a series of prioritized matchers to detect common and custom date formats. When a text string is parsed, it evaluates the text and attempts to return a list of DateResult components representing the extracted (start, end) tuple pairs.

1. Simple Dates & ISO

The parser naturally handles basic dates, including ISO-8601 formatting, short date text, and separated days representing specific matching instances.

parser.parse("2024-01-15T10:30:00Z")
# Output: 2024-01-15 -> 2024-01-15 

parser.parse("March 2, 3, and 4, 2025")
# Output: 
# 2025-03-02 -> 2025-03-02
# 2025-03-03 -> 2025-03-03
# 2025-03-04 -> 2025-03-04

2. Academic and Financial Periods

dateperiodparser efficiently identifies quarters, semesters (half-years), and academic school years spanning multiple calendar years.

parser.parse("academiejaar 2024-2025") # Dutch: Academic year 2024-2025
# Output: 2024-09-01 -> 2025-06-30

parser.parse("Q3 2024")
# Output: 2024-07-01 -> 2024-09-30

parser.parse("second half 2024")
# Output: 2024-07-01 -> 2024-12-31

3. Date Ranges & Multi-year sequences

The parser is helpful for extracting bounds from continuous periods or enumerating multi-year intervals specified in natural text.

parser.parse("2022 to 2025")
# Output: 2022-01-01 -> 2025-12-31

parser.parse("2021, 2022, and 2023")
# Output: 
# 2021-01-01 -> 2021-12-31
# 2022-01-01 -> 2022-12-31
# 2023-01-01 -> 2023-12-31

parser.parse("from 7 February 2022 to 6 March 2022")
# Output: 2022-02-07 -> 2022-03-06

4. Seasons

The package contains dedicated handling for periods expressed as a "season".

parser.parse("spring 2022")
# Output: 2022-03-01 -> 2022-05-31

parser.parse("zomer 2024") # Dutch: summer 2024
# Output: 2024-06-01 -> 2024-08-31

Edge Cases and Fallbacks

If text represents single values, generic dates, or formats that are heavily intermixed with language variations, it drops back to general parsing mechanisms (including an internal dependency on the dateparser logic) to find the closest matching span of time based strictly on textual boundaries.