{"id":915,"library":"parsedatetime","title":"parsedatetime","description":"parsedatetime is a Python module that can parse human-readable date/time strings like \"tomorrow at 3pm\" or \"next Tuesday\". It is currently at version 2.6 and primarily targets Python 3, with v2.6 maintaining Python 2.7 compatibility. Releases occur periodically, with significant updates and bug fixes.","status":"active","version":"2.6","language":"python","source_language":"en","source_url":"https://github.com/bear/parsedatetime","tags":["date parsing","time parsing","natural language processing","datetime"],"install":[{"cmd":"pip install parsedatetime","lang":"bash","label":"Latest stable version"}],"dependencies":[{"reason":"Used for advanced locale-aware parsing and robust testing, but is an optional runtime dependency for basic functionality.","package":"pyicu","optional":true},{"reason":"Required for timezone-aware operations, as demonstrated in quickstart examples.","package":"pytz","optional":true}],"imports":[{"note":"The direct import from `parsedatetime` is the current standard. Older examples or codebases might use `parsedatetime.parsedatetime`.","wrong":"import parsedatetime.parsedatetime as pdt\ncal = pdt.Calendar()","symbol":"Calendar","correct":"import parsedatetime\ncal = parsedatetime.Calendar()"}],"quickstart":{"code":"from datetime import datetime\nimport parsedatetime\n\ncal = parsedatetime.Calendar()\n\n# Parse a human-readable string\ntime_struct, parse_status = cal.parse(\"tomorrow at 3pm\")\n\n# Convert the result to a Python datetime object\nif parse_status != 0:\n    dt_object = datetime(*time_struct[:6])\n    print(f\"Parsed 'tomorrow at 3pm' as: {dt_object}\")\n\n# Example with a specific starting point (sourceTime)\nfrom datetime import datetime, timedelta\nsource_time = datetime(2026, 1, 1, 10, 0, 0) # Jan 1, 2026, 10:00 AM\ntime_struct_next, _ = cal.parse(\"next friday\", source_time)\ndt_object_next = datetime(*time_struct_next[:6])\nprint(f\"Parsed 'next friday' from {source_time} as: {dt_object_next}\")","lang":"python","description":"Initializes the Calendar object and demonstrates parsing a human-readable date/time string, converting the `time.struct_time` output to a standard `datetime` object, and using a `sourceTime` for relative parsing. The `parse()` method returns a tuple: `(time_struct, parse_status)`, where `parse_status` indicates success and the type of information parsed (e.g., date, time, or datetime)."},"warnings":[{"fix":"Always expect a `(time_struct, parse_status)` tuple from `cal.parse()`. Check `parse_status` (0 for failure, 1 for date, 2 for time, 3 for datetime) before converting `time_struct` to a `datetime` object, e.g., `datetime(*time_struct[:6])`.","message":"The `parse()` method's return value changed significantly around version 2.0. It now consistently returns a tuple `(time_struct, parse_status)`. Code relying on direct `datetime` or `time_struct` return without checking `parse_status` or handling the tuple will break.","severity":"breaking","affected_versions":">=2.0"},{"fix":"Instantiate `Calendar()` directly without arguments for default behavior, or use `Calendar(version=parsedatetime.VERSION_CONTEXT_STYLE)` for explicit context-aware parsing if needed, though this is often the default behavior in newer versions.","message":"The 'flag style' for instantiating `Calendar()` (e.g., `Calendar(parsedatetime.constants.getConstants())`) was deprecated in version 2.0 in favor of a 'context style'.","severity":"deprecated","affected_versions":">=2.0"},{"fix":"For critical date parsing, always provide a `sourceTime` argument to `cal.parse()` to set a clear reference point, or explicitly include the year in the input string. Example: `cal.parse(\"Jan 1st\", sourceTime=datetime(2025, 6, 1))`.","message":"When parsing incomplete human-readable dates (e.g., \"Jan 1st\"), `parsedatetime` implicitly guesses the year based on the current date (`sourceTime`). This can lead to unexpected results if the inferred year doesn't match expectations, especially for dates far in the past or future.","severity":"gotcha","affected_versions":"All"},{"fix":"Prefer using `parsedatetime` in a Python 3 environment. If Python 2.7 is necessary, ensure you are on `parsedatetime` version 2.6 and thoroughly test your parsing logic. Upgrade to Python 3 where possible.","message":"While v2.6 includes Python 2.7 compatibility, the library's development now primarily targets Python 3. Users on older Python 2.x environments may encounter unexpected issues or lack of support in future releases.","severity":"gotcha","affected_versions":"Potentially problematic on Python 2.x, especially <2.7"}],"env_vars":null,"search_vec":"'2.6':27 '2.7':37 '3':32 '3pm':18 'bug':46 'compat':38 'current':24 'date':48 'date/time':13 'datetim':55 'fix':47 'human':11 'human-read':10 'languag':53 'like':15 'maintain':35 'modul':6 'natur':52 'next':20 'occur':40 'pars':9,49,51 'parsedatetim':1,2 'period':41 'primarili':29 'process':54 'python':5,31,36 'readabl':12 'releas':39 'signific':43 'string':14 'target':30 'time':50 'tomorrow':16 'tuesday':21 'updat':44 'v2.6':34 'version':26","created_at":"2026-03-29T06:07:31.334725+00:00","updated_at":"2026-04-16T19:07:43.656048+00:00","problems":[{"fix":"First, create an instance of `parsedatetime.Calendar()` and then call its `parseDT` method:\n```python\nimport parsedatetime as pdt\nimport datetime\n\ncal = pdt.Calendar()\nresult, parse_status = cal.parseDT('tomorrow', datetime.datetime.now())\nprint(result)\n```","cause":"The `parseDT` method is an instance method of the `Calendar` class and must be called on an instantiated `Calendar` object, not directly on the `parsedatetime` module.","error":"AttributeError: module 'parsedatetime' has no attribute 'parseDT'"},{"fix":"Unpack the tuple into separate variables for the datetime object and the parse status, or access the datetime object using its index `[0]`:\n```python\nimport parsedatetime as pdt\nimport datetime\n\ncal = pdt.Calendar()\n\n# Option 1: Unpack the tuple\ndt_obj, parse_status = cal.parseDT('next Tuesday', datetime.datetime.now())\nprint(dt_obj.year, dt_obj.month, dt_obj.day)\n\n# Option 2: Access by index\ndt_obj = cal.parseDT('next Tuesday', datetime.datetime.now())[0]\nprint(dt_obj.year, dt_obj.month, dt_obj.day)\n```","cause":"The `parseDT` method returns a tuple `(datetime_object, parse_status)`, but the user attempted to access datetime attributes (like 'year', 'month', 'day') directly on this tuple instead of on the datetime object within it.","error":"AttributeError: 'tuple' object has no attribute 'year'"},{"fix":"Install the package using pip in your terminal:\n```bash\npip install parsedatetime\n```","cause":"The `parsedatetime` package is not installed in the Python environment being used, or the environment's `PYTHONPATH` does not include the installation location.","error":"ModuleNotFoundError: No module named 'parsedatetime'"},{"fix":"Ensure that a valid `datetime.datetime` object (e.g., `datetime.datetime.now()`) is always provided for the `sourceTime` argument when calling `parseDT`:\n```python\nimport parsedatetime as pdt\nimport datetime\n\ncal = pdt.Calendar()\n\n# Correct: Pass a datetime object as sourceTime\ndt_obj, parse_status = cal.parseDT('tomorrow', datetime.datetime.now())\nprint(dt_obj)\n\n# Incorrect (would cause the error):\n# dt_obj, parse_status = cal.parseDT('tomorrow', None)\n```","cause":"This error typically occurs when `None` is passed as the `sourceTime` (reference date/time) argument to `parseDT`, but the method expects a valid `datetime.datetime` object to calculate relative dates.","error":"TypeError: unsupported operand type(s) for -: 'NoneType' and 'datetime.timedelta'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.6","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/bear/parsedatetime","docs":null,"changelog":null,"pypi":"https://pypi.org/project/parsedatetime/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}