{"id":1985,"library":"datefinder","title":"Datefinder","description":"Datefinder is a Python library designed to extract datetime objects from natural language text. It supports various date and time formats, including relative and absolute expressions. The current version is 1.0.0, and it follows an active release cadence, with a recent major update shifting its default parsing engine.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/akoumjian/datefinder","tags":["date","time","parsing","natural language","datetime extraction"],"install":[{"cmd":"pip install datefinder","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for robust date and time parsing, especially for relative dates and various formats.","package":"python-dateutil"},{"reason":"Used for advanced regular expression matching, which forms the core of date and time pattern recognition.","package":"regex"}],"imports":[{"symbol":"find_dates","correct":"from datefinder import find_dates"},{"note":"Use this for behavior compatible with datefinder < 1.0.0, which used the 'legacy' engine by default.","symbol":"find_dates_legacy","correct":"from datefinder import find_dates_legacy"},{"note":"For typed extraction of absolute, relative, and duration values.","symbol":"extract","correct":"from datefinder import extract"}],"quickstart":{"code":"from datefinder import find_dates\n\ntext = \"I have a meeting on October 25th, 2024 at 3 PM and another one next Tuesday.\"\n\nprint(\"Dates found:\")\nfor match in find_dates(text):\n    print(f\"  Match: '{match.substring}' -> Datetime: {match.datetime}\")\n\n# To use the legacy engine (pre-1.0.0 behavior)\nprint(\"\\nDates found (legacy engine):\")\nfor match in find_dates(text, engine='legacy'):\n    print(f\"  Match: '{match.substring}' -> Datetime: {match.datetime}\")","lang":"python","description":"This quickstart demonstrates how to use `find_dates` to extract datetime objects from a string. It iterates through the returned `DateMatch` objects, printing both the original substring found and the parsed `datetime` object. It also shows how to explicitly specify the 'legacy' engine for pre-1.0.0 behavior."},"warnings":[{"fix":"If you need the pre-1.0.0 behavior, either use `find_dates(..., engine='legacy')` or import and use `find_dates_legacy` directly.","message":"In version 1.0.0, the default parsing engine for `find_dates` changed from 'legacy' to a new 'v2' engine. This may alter results or introduce breaking changes if your application relied on specific behaviors of the 'legacy' engine.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always iterate over the results and access the `.datetime` attribute, e.g., `for match in find_dates(text): date_obj = match.datetime`.","message":"The `find_dates` function returns an iterable of `DateMatch` objects, not raw `datetime` objects directly. Each `DateMatch` object contains the extracted `datetime` object via its `.datetime` attribute, and the original matched string via `.substring`.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade your Python environment to Python 3.9 or newer to use datefinder 1.0.0 and above.","message":"Support for Python 2 was dropped in version 0.7.0. Older applications running on Python 2 will need to upgrade their Python version to use recent datefinder releases.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Explicitly include timezone information in your input text for `datefinder` to parse it, or apply a default timezone to the resulting naive `datetime` objects using `pytz` or `zoneinfo` (Python 3.9+).","message":"By default, `datefinder` returns naive `datetime` objects (without timezone information) unless explicit timezone details are present in the input text. If timezone awareness is critical, you must handle it separately.","severity":"gotcha","affected_versions":"All"},{"fix":"Understand that `strict=True` aims for higher precision (fewer false positives) at the cost of recall (more false negatives). Test your inputs thoroughly with `strict=True` to ensure it meets your requirements.","message":"The `strict=True` parameter significantly restricts the types of dates and times `datefinder` will parse, often leading to fewer matches. This can be unexpected if not fully understood.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}