Metadata-Version: 2.4
Name: human-date-parser
Version: 0.1.2
Summary: Convert natural language date strings into Python datetime objects.
Home-page: https://github.com/Dheerendra-123/Human_Date_Parser_PY_Library.git
Author: Dheerendra Vikram Dixit
Author-email: dheerendradixit321@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7, <4
Description-Content-Type: text/markdown
Requires-Dist: dateparser>=1.1.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

human-date-parser
A lightweight and intuitive Python library designed to effortlessly convert natural language date expressions into precise Python datetime objects. Simplify date parsing in your applications by understanding human-friendly inputs like "today," "next Monday," or "in 3 days."

Features
Effortless Parsing: Convert common natural language date phrases into datetime objects.

Relative Date Handling: Accurately interpret "today," "tomorrow," "yesterday," and relative terms like "in X days/weeks/months/years" or "X days/weeks/months/years ago."

Weekday Recognition: Understand "next Monday," "last Friday," and similar weekday references.

Complex Expressions: Handle combinations like "in 2 weeks and 3 days."

Robust Error Handling: Returns None for unparsable input, allowing for graceful error management.

Installation
You can install human-date-parser directly from your terminal:

pip install human-date-parser

If you are developing the library locally, you can install it in editable mode:

pip install -e .

Usage
The primary function of the library is parse(), which takes a string representing a natural language date and returns a datetime.datetime object. All parsed dates will have their time components set to 00:00:00 (midnight) unless specified otherwise in the natural language input (though this library primarily focuses on date parsing, not time).

Code Examples
Let's explore how to use parse() with various natural language inputs.

from human_date_parser import parse_date
import datetime

# For consistent examples, we'll assume the current date is July 12, 2025.
# In a real application, parse_date will use the actual current date.

📅 Basic Dates
Easily parse common, absolute date references.

print(parse("today"))        # -> datetime.datetime(2025, 7, 12, 0, 0)
print(parse("tomorrow"))     # -> datetime.datetime(2025, 7, 13, 0, 0)
print(parse("yesterday"))    # -> datetime.datetime(2025, 7, 11, 0, 0)

⏳ Relative Future
Calculate dates relative to the current day, looking forward.

print(parse("in 3 days"))     # -> datetime.datetime(2025, 7, 15, 0, 0)
print(parse("in 1 week"))     # -> datetime.datetime(2025, 7, 19, 0, 0)
print(parse("in 2 months"))   # -> datetime.datetime(2025, 9, 12, 0, 0)

⌛ Relative Past
Calculate dates relative to the current day, looking backward.

print(parse("2 days ago"))    # -> datetime.datetime(2025, 7, 10, 0, 0)
print(parse("3 weeks ago"))   # -> datetime.datetime(2025, 6, 21, 0, 0)
print(parse("1 year ago"))    # -> datetime.datetime(2024, 7, 12, 0, 0)

🗓️ Weekdays
Determine the date of the next or last occurrence of a specific weekday.

print(parse("next Monday"))   # → Next upcoming Monday (e.g., datetime.datetime(2025, 7, 14, 0, 0))
print(parse("last Friday"))   # → Previous Friday (e.g., datetime.datetime(2025, 7, 11, 0, 0))

🧠 Complex Natural Language
The parser can combine multiple relative terms for more nuanced date calculations.

print(parse("in 2 weeks and 3 days"))   # → Adds both weeks and days (e.g., datetime.datetime(2025, 7, 29, 0, 0))
print(parse("next year"))               # → Approx. one year ahead (e.g., datetime.datetime(2026, 7, 12, 0, 0))
print(parse("last month"))              # → One month before today (e.g., datetime.datetime(2025, 6, 12, 0, 0))

⚠️ Invalid Input Handling
For inputs that cannot be parsed into a valid date, the function gracefully returns None.

result = parse("not a date")
if result is None:
    print("Could not parse date.")
# Output: Could not parse date.

🧪 Example in Real Use
Here's a practical example of how you might use human-date-parser to set a reminder.

# Schedule a reminder 5 days from now
reminder_date = parse("in 5 days")

if reminder_date:
    print("Reminder set for:", reminder_date.strftime("%Y-%m-%d"))
# Output (assuming today is July 12, 2025): Reminder set for: 2025-07-17
else:
    print("Failed to set reminder. Please check the date input.")

Contributing
Contributions are welcome! If you have suggestions for new features, improvements, or bug fixes, please open an issue or submit a pull request on the project's GitHub repository.

License
This project is licensed under the MIT License - see the LICENSE file for details.
