🧙‍♂️ Agewizard: The Absolute Age & DOB Powerhouse for Python

Agewizard is a premium, developer-first Python library designed to handle all aspects of age calculation, date of birth (DOB) analysis, and life-stage classification. Built with a focus on strict validation, global compatibility, and magic-like simplicity, it provides the most comprehensive toolset for modern Python applications.

Whether you're building a simple registration form with 18+ verification or a complex fintech app requiring precise date metrics, Agewizard ensures your logic is bulletproof and your code remains clean.

---

🚀 Key Value Propositions

• Total Reliability: Strict internal validation catches "fake dates" (like month 13 or Feb 30) before they reach your database.
• Global Ready: Native support for any date format (DD-MM-YYYY, MM.DD.YYYY, YYYY/MM/DD).
• Developer Experience: A fluent API that follows the Zen of Python—it just works.
• Micro-Services Ready: Zero external dependencies. Just pure Python power.

---

🛠 Installation

Install the latest version directly from PyPI:

pip install -U agewizard

---

📖 Comprehensive Feature Guide

1. Robust Date Parsing & Strict Validation

Most libraries crash when they see an invalid date. Agewizard validates everything. It automatically normalizes separators (-, ., /, or spaces).

from agewizard import Age

# --- Example: Catching Invalid Input ---
try:
    # Agewizard knows February doesn't have 30 days
    user = Age("2021-02-30") 
except ValueError as e:
    print(f"Wizard Alert: {e}") # Output: Invalid date components in '2021-02-30': day is out of range for month

---

2. Global Format Support (Locales)

Handle users from any country by specifying their preferred date format.

# UK/London Format (Day First)
uk_person = Age("31-12-1995", date_format="DD-MM-YYYY")

# US/New York Format (Month First)
us_person = Age("12.31.1995", date_format="MM.DD.YYYY")

# Standard Format (Auto-detected if it looks like YYYY-MM-DD or DD-MM-YYYY)
standard_person = Age("1995-15-05") # Automatically handles it

---

3. One-Line Age Verification (18+/21+)

Built-in methods for the most common use case in web development: account eligibility.

person = Age("2010-01-01")

# The "One-Word" Verification
if person.is_adult():
    print("Welcome home!")
else:
    print(f"Denied! Come back in {18 - person.years} years.")

# Custom thresholds (e.g., for Alcohol/Tobacco laws or Senior discounts)
print(person.is_adult(min_age=21)) # False
print(person.is_over(65))         # False

---

4. Deep Metrics (Days, Weeks, Months)

Go beyond just years. Get the exact weight of a person's life in various units.

p = Age("1990-05-15")

print(f"Life in Days: {p.days}")      # Total days since birth
print(f"Life in Weeks: {p.weeks}")    # Total weeks since birth
print(f"Life in Months: {p.months}")  # Total months since birth
print(f"Human Format: {p.readable}") # Output: "34 years, 7 months, 24 days"

---

5. Zodiac & Magic Insights

Add personality to your app with automatic star sign detection.

p = Age("1985-08-23")

print(f"Star Sign: {p.zodiac}") # Output: Virgo
print(f"Next Birthday Weekday: {p.next_birthday_weekday}") # What day is the party?
print(f"Days to B-Day: {p.next_birthday_days}") # The countdown

---

6. Life Stage Classification

Agewizard can automatically categorize a person based on their age.

Age Range	Category
0 - 2	Infant
3 - 12	Child
13 - 19	Teen
20 - 64	Adult
65+	Senior

print(Age("2022-01-01").category) # Infant
print(Age("2005-01-01").category) # Teen

---

🖥 Production Examples

Interactive Form with Error Recovery

from agewizard import Age

def register_user():
    print("=== Welcome to the Magic Portal ===")
    dob_input = input("Enter your Birthday (DD-MM-YYYY): ")
    
    try:
        user = Age(dob_input, date_format="DD-MM-YYYY")
        
        if not user.is_adult():
            print(f"❌ Error: You are a {user.category}. This portal is for Adults only.")
            return

        print(f"✅ Success! You are {user.years} years old.")
        print(f"Fun Fact: You were born on a {user.birth_date.strftime('%A')}.")
        print(f"Your star sign is: {user.zodiac} 🌌")
        
    except ValueError as e:
        print(f"💥 Invalid Input: {e}")

if __name__ == "__main__":
    register_user()

---

Comparing Two Dates

from agewizard import compare_ages

# Who is older?
story = compare_ages("1990-01-01", "1995-05-15")
print(story) # "Person 1 is older by approx 5 years (1960 days)."

---

💎 The API Reference

Age Class

Attribute	Description
.years	Age in full solar years.
.days	Total days lived.
.months	Total months lived.
.zodiac	Star sign based on birth date.
.readable	Human-readable string (Y years, M months, D days).
.is_today	Boolean. True if today is the user's birth anniversary.
.category	Life stage string (e.g., "Adult").
.next_birthday_days	Countdown to the next birthday.

Utility Functions

• calculate_age(dob, date_format=None)
• zodiac_sign(dob, date_format=None)
• is_leap_year(year_or_dob)
• age_hijri(dob) (Approximate lunar age)

---

👨‍💻 Author & Community

Kamran Hussain
A dedicated software engineer focused on building tools that simplify complex logic for everyone.

• GitHub: @KamranProjects
• Email: contact.kamrankami@gmail.com
• Repo: https://github.com/KamranProjects/agewizard

---

📜 License

Agewizard is open-source software licensed under the MIT License.