This PR makes parse_date, parse_datetime, and parse_iso8601 consistently raise ParseError instead of returning None on parse failures. It removes duplicated strict parser entrypoints, adds shared parsing helpers, and improves parse error details for invalid calendar dates and ISO failures. The package exports now include ParseError, tests were updated to validate the exception-based contract and error metadata, and docs were updated to match the new behavior. It also hardens the parse_date docstring example so doctests are stable in CI. Validation run locally: uv run ruff check, uv run ty check, uv run pytest -q, and make doctest.

This pull request introduces robust error handling for date and datetime parsing in the dateutils library by replacing silent failures with explicit exceptions. The most significant change is the addition of a new ParseError exception, which is now raised when parsing fails, providing detailed context about the error. The documentation and tests have been updated to reflect and validate this new behavior.

Error handling and API changes

• Introduced the ParseError exception class for failed parsing operations, replacing previous behavior where parsing would return None for invalid inputs. This exception includes details such as the parser name, input value, reason, and attempted formats. (dateutils/dateutils.py, dateutils/__init__.py) [1] [2] [3]
• Updated parse_date, parse_datetime, and parse_iso8601 functions to raise ParseError on failure instead of returning None. This includes handling invalid calendar dates, unknown month names, and missing or mismatched formats. (dateutils/dateutils.py) [1] [2] [3] [4] [5] [6] [7]

Documentation updates

• Revised the README.md to document the new error handling approach, including examples of catching ParseError and its detailed error messages. (README.md) [1] [2] [3] [4]

Test suite improvements

• Refactored tests to expect ParseError instead of None for invalid date and datetime inputs. Added new tests to verify error details and edge cases. (tests/test_dateutils.py) [1] [2]

Internal refactoring

• Extracted and improved internal parsing helpers for date and datetime formats, ensuring consistent error handling and code clarity. (dateutils/dateutils.py) [1] [2] [3]

These changes make date and datetime parsing more reliable and user-friendly, as errors are now surfaced explicitly with actionable information.