fuzzy-date

‎ ‎

Python module to convert various time strings into datetime objects, written in Rust.

Conversion

Date

import fuzzydate as fd

fd.to_date('2023-04-01')          # 2023-04-01
fd.to_date('20230401')            # 2023-04-01
fd.to_date('04/01/2023')          # 2023-04-01
fd.to_date('01.04.2023')          # 2023-04-01
fd.to_date('1st of April, 2023')  # 2023-04-01
fd.to_date('1 April 2023')        # 2023-04-01
fd.to_date('Sat April 1 2023')    # 2023-04-01

# Anything invalid raises a ValueError

fd.to_date('Sun April 1 2023')
# ValueError: Unable to convert "Sun April 1 2023" into date

Datetime

import fuzzydate as fd

fd.to_date('@1680307200')              # 2023-04-01 00:00:00+00:00
fd.to_date('2023-04-01 midnight')      # 2023-04-01 00:00:00+00:00
fd.to_date('2023-04-01 2pm')           # 2023-04-01 14:00:00+00:00
fd.to_date('2023-04-01 14:00')         # 2023-04-01 14:00:00+00:00
fd.to_date('2023-04-01 14:00:00.410')  # 2023-04-01 14:00:00.410000+00:00

# Anything invalid raises a ValueError

fd.to_date('2023-04-01 25:00')
# ValueError: Unable to convert "2023-04-01 25:00" into datetime

Relative time

import fuzzydate as fd

# If current time is April 1st 2023 12PM UTC...

fd.to_datetime('1 hour ago')         # 2023-04-01 11:00:00+00:00
fd.to_datetime('last week')          # 2023-03-20 12:00:00+00:00
fd.to_datetime('past 2 weeks')       # 2023-03-18 12:00:00+00:00
fd.to_datetime('-1 week')            # 2023-03-25 12:00:00+00:00
fd.to_datetime('tuesday next week')  # 2023-04-04 00:00:00+00:00
fd.to_datetime('last week midnight') # 2023-03-20 00:00:00+00:00
fd.to_datetime('-1d 2h 5min 10s')    # 2023-03-31 09:54:50+00:00
fd.to_datetime('tomorrow')           # 2023-04-02 00:00:00+00:00
fd.to_datetime('prev Monday')        # 2023-03-27 00:00:00+00:00
fd.to_datetime('prev June')          # 2022-06-01 00:00:00+00:00
fd.to_datetime('start of month')     # 2023-04-01 00:00:00+00:00
fd.to_datetime('last of the month')  # 2023-04-30 00:00:00+00:00
fd.to_datetime('end of year')        # 2023-12-31 00:00:00+00:00

# Anything invalid raises a ValueError

fd.to_datetime('next Summer')
# ValueError: Unable to convert "next Summer" into datetime

Relative range

Ending datetime is always exclusive.

import fuzzydate as fd

# If current time is April 1st 2023 12PM UTC...

fd.to_range('today')
# 2023-04-01 00:00:00+00:00, 2023-04-02 00:00:00+00:00

fd.to_range('last hour')
# 2023-04-01 11:00:00+00:00, 2023-04-01 12:00:00+00:00

fd.to_range('last 7 days')
# 2023-03-25 00:00:00+00:00, 2023-04-01 00:00:00+00:00

fd.to_range('prev 2 weeks')
# 2023-03-13 00:00:00+00:00, 2023-03-27 00:00:00+00:00

fd.to_range('last month')
# 2023-03-01 00:00:00+00:00, 2023-04-01 00:00:00+00:00

# Anything invalid raises a ValueError

fd.to_range('last month midnight')
# ValueError: Unable to convert "last month midnight" into datetime range

Time duration

Duration seconds

import fuzzydate as fd

fd.to_seconds('1h 4min') # 3840.0
fd.to_seconds('+2 days') # 172800.0
fd.to_seconds('-1 hour') # -3600.0
fd.to_seconds('1 week')  # 604800.0

# Anything other than an exact length of time raises a ValueError

fd.to_seconds('last week')
# ValueError: Unable to convert "last week" into seconds

# Because years and months have varying amount of seconds, using 
# them raises a ValueError

fd.to_seconds('1m 2w 30min')
# ValueError: Converting months into seconds is not supported

Duration string

import fuzzydate as fd

fd.to_duration(3840.0)                       # 1hr 4min
fd.to_duration(3840.0, units='long')         # 1 hour 4 minutes
fd.to_duration(3840.0, units='short')        # 1h 4min
fd.to_duration(3840.0, max='min', min='min') # 64min

Localization

import fuzzydate as fd

d = fd.FuzzyDate()

d.add_tokens({
    'måndag': fd.token.WDAY_MON,
    'dagar': fd.token.LONG_UNIT_DAY,
})

d.add_patterns({
    'nästa [wday]': fd.pattern.NEXT_WDAY,
})

assert fd.to_date('next Monday') == d.to_date('nästa Måndag')
assert fd.to_date('+5 days') == d.to_date('+5 dagar')
assert fd.to_seconds('+5 days') == d.to_seconds('+5 dagar')

d.units = {
    fd.unit.DAY: 'dag',
    fd.unit.DAYS: 'dagar',
}

assert d.to_duration(86400.0) == '1 dag'

Requirements

• Python >= 3.11

Installation

pip install fuzzy-date 

Syntax support

Special

• Date now, today, tomorrow, yesterday
• Time of day midnight

Relative

• Adjustment first, last, start, end, prev, past, this, next or +, -
• Units next week, next month, next year
• Weekdays next Mon, next Monday, Monday
• Months next Jan, next January, January
• Numeric (s)ec, min, (h)r, (d)ay, (w)eek, (m)onth, (y)ear
• Ranges first/last day of, first/last Monday of, start/end of month, start/end of week

Fixed

• Unix timestamp @1680307200
• Date
  • Numeric 2023-04-01, 20230401, 04/01/2023, 01.04.2023
  • Textual April 1st 2023, April 1 2023, 1 April 2023, 1. April 2023
  • Combined 01-April-2023, April-01-2023, 2023-April-01
• Day and month
  • Textual April 1st, April 1, 1 April, 1. April, 1st of April
  • With weekday Sat, 1 April, Sat, 1st of April, Sat, April 1st, Sat, April 1
• Week
  • Numeric 2023W13, 2023-W13
  • Textual Week 13, Week 13, 2023
• Month and year April, April 2023
• Year 2023
• Datetime Sat Apr 01 12:00:00 2023, 2023-04-01T12:00:00, 2023-04-01T12:00.410
• Time of day w/wo at, @, 14:00, 14:00:00, 14:00:00.410, 2pm, 2:00 pm

Interface

Conversion

fuzzydate.to_date(
    source: str,
    today: datetime.date = None,
    weekday_start_mon: bool = True,
) -> datetime.date

fuzzydate.to_datetime(
    source: str,
    now: datetime.datetime = None,
    weekday_start_mon: bool = True,
) -> datetime.datetime
    
fuzzydate.to_duration(
    seconds: float, 
    units: str = None, 
    max: str = 'w', 
    min: str = 's',
) -> str
    
fuzzydate.to_range(
    source: str,
    now: datetime.datetime = None,
    weekday_start_mon: bool = True,
) -> tuple[datetime.datetime, datetime.datetime]
    
fuzzydate.to_seconds(
    source: str,
) -> float

Constants

fuzzydate.patterns: dict[str, str]
fuzzydate.tokens: dict[str, int]

Custom configuration

d = fd.FuzzyDate()

# Read-write
d.units: dict[str, str]
d.units_long: dict[str, str]
d.units_short: dict[str, str]

d.add_patterns(
    tokens: dict[str, str],
) -> Self
    
d.add_tokens(
    tokens: dict[str, int],
) -> Self
    
d.set_first_weekday_sunday(
    use_sunday: bool,
) -> Self
    
d.to_date(
    source: str,
    today: datetime.date = None,
) -> datetime.date

d.to_datetime(
    source: str,
    now: datetime.datetime = None,
) -> datetime.datetime
    
d.to_duration(
    seconds: float, 
    units: str = None, 
    max: str = 'w', 
    min: str = 's',
) -> str
  
d.to_range(
    source: str,
    now: datetime.datetime = None,
) -> tuple[datetime.datetime, datetime.datetime]
      
d.to_seconds(
    source: str,
) -> float

Benchmarks

Benchmark is perhaps the wrong word here, as performance is (usually) less important than accuracy when it comes to parsing fuzzy date strings.

To get a sense of the accuracy for fuzzydate, we compare it with dateparser, the popular date parsing library for Python. Although it has a slightly different premise of extracting dates from HTML pages — which can be much more vague — one would likely still use it for the same use cases.

Summary

• Comparing dateparser 1.2.1 and fuzzy-date 0.5.4
• Testing 45 strings (26 fixed, 19 relative)
• No timezones included, as fuzzydate does not support them
• 8 tests get different results, 1 only works in dateparser, 11 only work in fuzzydate
• For identical 26 tests, mean execution time is 189% faster for fuzzydate

See benchmark.py for implementation.

Differences (9)

Current time is assumed to be 2024-01-25 15:22:28

Note that using a specific language or adding more settings can change the results for dateparser.

Unsupported (11)

Performance

For 26 test cases that both libraries supported, measuring the fastest run of 100 executions.

It's perhaps noteworthy that native datetime.fromisoformat() was still 197% faster than fuzzydate, when it could be used.

Background

This library was born out of the need to accept various user inputs for date range start and end times, to convert user time tracking entries into exact durations etc. All very much alike to what timelib does.

Other implementations are available, but I did not find one that would have worked for me - usually they were missing support for some key wording I needed, or handled user vagueness and timezones in a different way.

Also, I kinda wanted to learn Rust via some example project as well.

License

MIT