Metadata-Version: 2.4
Name: dateperiodparser
Version: 0.1.2
Summary: A comprehensive date and period parser
Project-URL: Homepage, https://github.com/example/dateperiodparser
Project-URL: Issues, https://github.com/example/dateperiodparser/issues
Author-email: Author <author@example.com>
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: dateparser>=1.1.8
Requires-Dist: python-dateutil>=2.8.2
Description-Content-Type: text/markdown

# 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:

```bash
pip install dateperiodparser
```

## Quick Start

```python
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.

```python
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.

```python
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.

```python
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".

```python
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.
