Skip to main content

Extract datetimes, datetime ranges, and datetime lists from natural language text

Project description

timefhuman

PyPi Downloads per Month Coverage Status

Extract datetimes, datetime ranges, and datetime lists from natural language text. Supports Python3+^1.

✨ Try the demo or code online. No installation needed. ✨


Getting Started

Install with pip using

$ pip install timefhuman

Then, find natural language dates and times in any text.

# All these tests assume the current date is August 4, 2018 at 2 PM
>>> from timefhuman import timefhuman

>>> timefhuman("How does 5p mon sound? Or maybe 4p tu?")
[datetime.datetime(2018, 8, 6, 17, 0), datetime.datetime(2018, 8, 7, 16, 0)]

The text can contain not only datetimes but also ranges of datetimes or lists of datetimes.

>>> timefhuman('3p-4p')  # time range
[(datetime.datetime(2018, 8, 4, 15, 0), datetime.datetime(2018, 8, 4, 16, 0))]

>>> timefhuman('7/17 4PM to 7/17 5PM')  # range of datetimes
[(datetime.datetime(2018, 7, 17, 16, 0), datetime.datetime(2018, 7, 17, 17, 0))]

>>> timefhuman('Monday 3 pm or Tu noon')  # list of datetimes
[[datetime.datetime(2018, 8, 6, 15, 0), datetime.datetime(2018, 8, 7, 12, 0)]]

>>> timefhuman('7/17 4-5 or 5-6 PM')  # list of ranges of datetimes!
[[(datetime.datetime(2018, 7, 17, 16, 0), datetime.datetime(2018, 7, 17, 17, 0)),
  (datetime.datetime(2018, 7, 17, 17, 0), datetime.datetime(2018, 7, 17, 18, 0))]]

Durations are also supported.

>>> timefhuman('30 minutes')  # duration
[datetime.datetime(2018, 8, 4, 14, 30)]

>>> timefhuman('30-40 mins')  # range of durations
[(datetime.datetime(2018, 8, 4, 14, 30), datetime.datetime(2018, 8, 4, 14, 40))]

>>> timefhuman('30 or 40m')  # list of durations
[[datetime.datetime(2018, 8, 4, 14, 30), datetime.datetime(2018, 8, 4, 14, 40)]]

When possible, timefhuman will infer any missing information, using context from other datetimes.

>>> timefhuman('3-4p')  # infer "PM" for "3"
[(datetime.datetime(2018, 8, 4, 15, 0), datetime.datetime(2018, 8, 4, 16, 0))]

>>> timefhuman('7/17 4 or 5 PM')  # infer "PM" for "4" and infer "7/17" for "5 PM"
[[datetime.datetime(2018, 7, 17, 16, 0), datetime.datetime(2018, 7, 17, 17, 0)]]

>>> timefhuman('7/17, 7/18, 7/19 at 9')  # infer "9a" for "7/17", "7/18"
[[datetime.datetime(2018, 7, 17, 9, 0), datetime.datetime(2018, 7, 18, 9, 0),
  datetime.datetime(2018, 7, 19, 9, 0)]]

>>> timefhuman('3p -4p PDT')  # infer timezone "PDT" for "3p"
[(datetime.datetime(2018, 8, 4, 15, 0, tzinfo=<DstTzInfo 'US/Pacific' ...>),
  datetime.datetime(2018, 8, 4, 16, 0, tzinfo=<DstTzInfo 'US/Pacific' ...>))]

You can also use natural language descriptions of dates and times.

>>> timefhuman('next Monday')
[datetime.datetime(2018, 8, 6, 0, 0)]

>>> timefhuman('next next Monday')
[datetime.datetime(2018, 8, 13, 0, 0)]

>>> timefhuman('last Wednesday of December')
[datetime.datetime(2018, 12, 26, 0, 0)]

>>> timefhuman('afternoon')
[datetime.datetime(2018, 8, 4, 15, 0)]

>>> timefhuman('1 month ago')
[datetime.datetime(2018, 7, 5, 14, 0)]

See more examples in tests/test_e2e.py.

Advanced Usage

For more configuration options, simply create a tfhConfig object.

from timefhuman import tfhConfig
config = tfhConfig()

Return matched text: You can additionally grab the matched text from the input string, as well as the string indices of the matched substring. This is useful for modifying the input string, for example.

>>> config = tfhConfig(return_matched_text=True, now=datetime.datetime(2025, 2, 23))

>>> timefhuman('We could maybe do 3 PM, if you still have time', config=config)
[('3 PM', (18, 22), datetime.datetime(2025, 2, 23, 15, 0))]

Change 'Now': You can configure the default date that timefhuman uses to fill in missing information. This would be useful if you're extracting dates from an email sent a year ago.

>>> config = tfhConfig(now=datetime.datetime(2018, 8, 4, 0, 0))

>>> timefhuman('upcoming Monday noon', config=config)
[datetime.datetime(2018, 8, 6, 12, 0)]

You can also set a default timezone, by again using the config's now.

>>> config = tfhConfig(
...     now=datetime.datetime(2018, 8, 4, tzinfo=pytz.timezone('US/Pacific'))
... )

>>> timefhuman('Wed', config=config)
[datetime.datetime(2018, 8, 8, 0, 0, tzinfo=<DstTzInfo 'US/Pacific' ...>)]

>>> timefhuman('Wed EST', config=config)  # EST timezone in the input takes precedence
[datetime.datetime(2018, 8, 8, 0, 0, tzinfo=<DstTzInfo 'US/Michigan' ...>)]

Use explicit information only: Say you only want to extract dates OR times OR timedeltas. You don't want the library to infer information. You can disable most inference by setting infer_datetimes=False. Instead of always returning a datetime, timefhuman will be able to return date, time, or timedelta objects depending on what's provided.

>>> config = tfhConfig(infer_datetimes=False)

>>> timefhuman('3 PM', config=config)  # time
[datetime.time(15, 0)]

>>> timefhuman('12/18/18', config=config)  # date
[datetime.date(2018, 12, 18)]

>>> timefhuman('30 minutes', config=config)  # duration
[datetime.timedelta(seconds=1800)]

Past datetimes: By default, datetimes are assumed to occur in the future, so if "3pm" today has already passed, the returned datetime will be for tomorrow. However, if datetimes are assumed to have occurred in the past (e.g., from an old letter, talking about past events), you can configure the direction.

>>> from timefhuman import Direction
>>> config = tfhConfig(direction=Direction.previous, now=datetime.datetime(2018, 8, 4, 14))

>>> timefhuman('3PM')  # the default
[datetime.datetime(2018, 8, 4, 15, 0)]

>>> timefhuman('3PM', config=config)  # changing direction
[datetime.datetime(2018, 8, 3, 15, 0)]

Change global defaults: You can also modify the default configuration used by timefhuman, if you don't want to manually pass in configs everywhere.

>>> from timefhuman import DEFAULT_CONFIG
>>> DEFAULT_CONFIG.now = datetime.datetime(2025, 2, 23, 12, 0, 0)

>>> timefhuman('3PM')
[datetime.datetime(2025, 2, 23, 15, 0)]

Here is the full set of supported configuration options:

@dataclass
class tfhConfig:
    # Default to the next valid datetime or the previous one
    direction: Direction = Direction.next
    
    # Always produce datetime objects. If no date, use the current date. If no time,
    # use midnight. If timedelta, add it to the current datetime. Still allows ranges
    # (tuples) of datetimes and lists of datetimes.
    infer_datetimes: bool = True
    
    # The 'current' datetime, used if infer_datetimes is True
    now: datetime | None = None
    
    # Return the matched text from the input string
    return_matched_text: bool = False

Development

Install the development version.

$ pip install -e .\[test\]  # for zsh

To run tests and simultaneously generate a coverage report, use the following commands:

$ py.test --cov --cov-report=html
$ open htmlcov/index.html

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

timefhuman-0.1.4.tar.gz (22.2 kB view details)

Uploaded Source

Built Distribution

timefhuman-0.1.4-py3-none-any.whl (18.1 kB view details)

Uploaded Python 3

File details

Details for the file timefhuman-0.1.4.tar.gz.

File metadata

  • Download URL: timefhuman-0.1.4.tar.gz
  • Upload date:
  • Size: 22.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for timefhuman-0.1.4.tar.gz
Algorithm Hash digest
SHA256 9ffb9401274abcc24af3ab5bba1ae8b77b6ac6bb0b89f6dfe23941710534529d
MD5 5aba923181e5ac51244dfde001a7c46f
BLAKE2b-256 5b5a1e07c36012c98c996b4e7233592c44d68c3205ad870a08f5bba81ab89eff

See more details on using hashes here.

File details

Details for the file timefhuman-0.1.4-py3-none-any.whl.

File metadata

  • Download URL: timefhuman-0.1.4-py3-none-any.whl
  • Upload date:
  • Size: 18.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for timefhuman-0.1.4-py3-none-any.whl
Algorithm Hash digest
SHA256 8667d5568b918fa53e34501f954b4d98e5180aece65c9761ffa71e440323d2ef
MD5 f3f10124afc21c4cbef8ab98ebd5d8b3
BLAKE2b-256 723d6ad20540474e23fcfe9a7fe1066504a830b30f29736fffaa51a7b67d2a10

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page