https://github.com/craigtrim/fast-parse-time
A fast and efficient English NLP Parser for Time References in Text
https://github.com/craigtrim/fast-parse-time
date-parsing datetime-parser temporal-expressions text-to-date time-extraction
Last synced: about 1 month ago
JSON representation
A fast and efficient English NLP Parser for Time References in Text
- Host: GitHub
- URL: https://github.com/craigtrim/fast-parse-time
- Owner: craigtrim
- License: mit
- Created: 2022-08-11T05:09:21.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2026-02-18T04:15:01.000Z (about 2 months ago)
- Last Synced: 2026-02-18T04:52:36.048Z (about 2 months ago)
- Topics: date-parsing, datetime-parser, temporal-expressions, text-to-date, time-extraction
- Language: Python
- Homepage:
- Size: 2.25 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fast-parse-time
[](https://pypi.org/project/fast-parse-time/)
[](https://pypi.org/project/fast-parse-time/)
[](https://pepy.tech/project/fast-parse-time)
[](https://pepy.tech/project/fast-parse-time)
[](https://opensource.org/licenses/MIT)
[](https://github.com/craigtrim/fast-parse-time/tree/master/tests)
Extract dates and times from text. Fast, deterministic, zero cost.
## Why?
LLMs can parse dates, but they're slow, expensive, and non-deterministic. This library gives you:
- **Sub-millisecond performance** - Process thousands of documents per second
- **Zero API costs** - No per-request charges
- **Deterministic results** - Same input always produces same output
- **Simple API** - One function call, everything extracted
## Install
```bash
pip install fast-parse-time
```
## Usage
```python
from fast_parse_time import parse_dates
text = "Meeting on 04/08/2024 to discuss issues from 5 days ago"
result = parse_dates(text)
# Explicit dates found in text
print(result.explicit_dates)
# [ExplicitDate(text='04/08/2024', date_type='FULL_EXPLICIT_DATE')]
# Relative time expressions
print(result.relative_times)
# [RelativeTime(cardinality=5, frame='day', tense='past')]
# Convert to Python datetime
for time_ref in result.relative_times:
print(time_ref.to_datetime())
# datetime.datetime(2025, 11, 14, ...)
```
## What It Extracts
**Explicit dates:**
```python
"Event on 04/08/2024" → 04/08/2024 (full date)
"Meeting scheduled for 3/24" → 3/24 (month/day)
"Copyright 2024" → 2024 (year only)
"Ambiguous: 4/8" → 4/8 (flagged as ambiguous)
"Published March 15, 2024" → March 15, 2024 (written month)
"Filed in 2024" → 2024 (year in prose)
```
**Year ranges:**
```python
"Active 2014-2015" → 2014-2015 (year range)
"From 2010 to 2020" → From 2010 to 2020 (year range)
"Revenue grew 2019–2023" → 2019-2023 (en/em dash normalized)
"Contract 2023-24" → 2023-24 (abbreviated)
```
**Relative times:**
```python
"5 days ago" → 5 days (past)
"last couple of weeks" → 2 weeks (past)
"30 minutes ago" → 30 minutes (past)
"half an hour ago" → 1 hour (past)
"a few days ago" → 3 days (past)
```
## Examples
### Parse everything at once
```python
result = parse_dates("Report from 04/08/2024 covering issues from last week")
result.explicit_dates # ['04/08/2024']
result.relative_times # [RelativeTime(cardinality=1, frame='week', tense='past')]
```
### Just get dates
```python
from fast_parse_time import extract_explicit_dates
dates = extract_explicit_dates("Event on 04/08/2024 or maybe 3/24")
# {'04/08/2024': 'FULL_EXPLICIT_DATE', '3/24': 'MONTH_DAY'}
```
### Convert to datetime objects
```python
from fast_parse_time import resolve_to_datetime
datetimes = resolve_to_datetime("Show me data from 5 days ago")
# [datetime.datetime(2025, 11, 14, ...)]
```
## Features
- Multiple date formats: `04/08/2024`, `3/24`, `2024-06-05`, `March 15, 2024`
- Multiple delimiters: `/`, `-`, `.`
- Year ranges: `2014-2015`, `2010 to 2020`, `from 2018 through 2022`, `2023-24`
- Unicode normalization: en dash, em dash, and other hyphen variants accepted automatically
- Written months: `March 15, 2024`, `Mar 15, 2024`, `15 March 2024`
- Year-only in prose: `Copyright 2024`, `filed in 2019`
- Relative time expressions: "5 days ago", "last week", "couple of months ago"
- Informal expressions: "half an hour ago", "a few days ago", "several weeks ago"
- Named day and time-of-day references: "last Monday", "this morning", "yesterday"
- Ambiguity detection: Flags dates like `4/8` that could be April 8 or August 4
- Time frame support: seconds, minutes, hours, days, weeks, months, years
## Documentation
- [API Reference](https://github.com/craigtrim/fast-parse-time/blob/master/docs/API.md)
- [Functions](https://github.com/craigtrim/fast-parse-time/blob/master/docs/functions.md) - All functions with examples
- [Types](https://github.com/craigtrim/fast-parse-time/blob/master/docs/types.md) - Data classes and DateType enum
- [System Boundaries](https://github.com/craigtrim/fast-parse-time/blob/master/BOUNDARIES.md) - Design decisions and limitations
## Performance
Typical extraction takes < 1ms per document. No network calls, no model inference, pure Python.
## License
MIT - See [LICENSE](LICENSE) for details.
## Author
**Craig Trim** - [craigtrim@gmail.com](mailto:craigtrim@gmail.com)
---
[Report Issues](https://github.com/craigtrim/fast-parse-time/issues) | [API Docs](https://github.com/craigtrim/fast-parse-time/blob/master/docs/API.md) | [PyPI](https://pypi.org/project/fast-parse-time/)