Metadata-Version: 2.1
Name: hijri-datetime
Version: 0.2.3.post0
Summary: Pythonic Hijri datetime — handle full & partial dates, ranges, and seamless Gregorian & Jalali conversion.
Author-email: "m.lotfi" <m.lotfi@email.com>
Maintainer-email: "m.lotfi" <m.lotfi@email.com>
License: GPL version 3
Project-URL: Homepage, https://github.com/mlotfic/hijri-datetime
Project-URL: Documentation, https://github.com/mlotfic/hijri-datetime#readme
Project-URL: Repository, https://github.com/mlotfic/hijri-datetime.git
Project-URL: Bug Tracker, https://github.com/mlotfic/hijri-datetime/issues
Project-URL: Changelog, https://github.com/mlotfic/hijri-datetime/blob/main/CHANGELOG.md
Project-URL: Source Code, https://github.com/mlotfic/hijri-datetime
Project-URL: Download, https://pypi.org/project/hijri-datetime/
Keywords: python,package,modules,portable,hijri,islamic,calendar,datetime,gregorian,jalali,conversion
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jdatetime>=3.0.0
Requires-Dist: requests>=2.20.0
Requires-Dist: numpy>=1.18.0
Requires-Dist: pandas>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: pre-commit>=2.0; extra == "dev"
Requires-Dist: tox>=3.0; extra == "dev"
Requires-Dist: build>=0.10; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: setuptools_scm>=6.2; extra == "dev"
Requires-Dist: setuptools>=45; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: sphinx>=4.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov>=2.0; extra == "test"
Requires-Dist: pytest-mock>=3.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: myst-parser>=0.17.0; extra == "docs"
Provides-Extra: lint
Requires-Dist: black>=22.0; extra == "lint"
Requires-Dist: flake8>=4.0; extra == "lint"
Requires-Dist: mypy>=0.900; extra == "lint"
Requires-Dist: isort>=5.0; extra == "lint"
Provides-Extra: all
Requires-Dist: pytest>=6.0; extra == "all"
Requires-Dist: pytest-cov>=2.0; extra == "all"
Requires-Dist: pytest-mock>=3.0; extra == "all"
Requires-Dist: black>=22.0; extra == "all"
Requires-Dist: flake8>=4.0; extra == "all"
Requires-Dist: mypy>=0.900; extra == "all"
Requires-Dist: isort>=5.0; extra == "all"
Requires-Dist: pre-commit>=2.0; extra == "all"
Requires-Dist: tox>=3.0; extra == "all"
Requires-Dist: build>=0.10; extra == "all"
Requires-Dist: twine>=4.0; extra == "all"
Requires-Dist: setuptools_scm>=6.2; extra == "all"
Requires-Dist: setuptools>=45; extra == "all"
Requires-Dist: wheel; extra == "all"
Requires-Dist: sphinx>=4.0; extra == "all"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "all"
Requires-Dist: myst-parser>=0.17.0; extra == "all"

# hijri-datetime

# 💡💡💡💡💡💡 **this not working yet** 💡💡💡💡

📅 **Hijri (Islamic) calendar datetime library for Python**  
A drop-in replacement for Python's built-in `datetime` module, supporting Hijri date arithmetic, formatting, conversion, partial dates, and integration with `jdatetime`.

---

## Features

- **HijriDate / HijriDateTime classes**  
  Drop-in replacement for `datetime.date` and `datetime.datetime`.

- **Partial Dates & Ranges**  
  Handle missing months or days gracefully:
  - `HijriDate(1446)` → represents the full year.
  - `HijriDate(1446, 2)` → represents all days of month 2.
  - Arithmetic supports ranges and comparisons.

- **Gregorian ↔ Hijri Conversion**  
  - Vectorized conversion using preloaded dataset (from [Aladhan API](https://aladhan.com/islamic-calendar-api)).
  - Accurate conversion for historical and future dates.
  
- **Integration with jdatetime**  
  Convert Hijri dates to Jalali calendar easily:
  ```python
  import jdatetime
  jd = hijri_date.to_jdatetime()
  ````

* **Full datetime API support**
  Methods like `.year`, `.month`, `.day`, `.weekday()`, `.isoweekday()`, `.strftime()`, `.fromisoformat()`, `.today()`, `.now()`.

* **Calendar module compatibility**
  Leap year checks, month lengths, weekdays, etc.

* **Vectorized / Bulk Conversion Support**
  Efficient for millions of rows with pandas/numpy.

---

## Installation

```bash
pip install hijri-datetime
```

---

## Quick Start

```python
from hijri_datetime import HijriDate, HijriDateTime

# Create Hijri dates
d1 = HijriDate(1446, 2, 15)  # Full date
d2 = HijriDate(1446, 2)      # Day missing → treat as range
d3 = HijriDate(1446)         # Month & day missing → full year range

# Convert to Gregorian
print(d1.to_gregorian())             # datetime.date(2025, 9, 9)
print(d2.to_gregorian_range())       # [datetime.date(2025,9,1), datetime.date(2025,9,30)]
print(d3.to_gregorian_range())       # full year range

# Date arithmetic
print(d1 + 10)   # Add 10 days
print(d1 - 5)    # Subtract 5 days

# jdatetime conversion
import jdatetime
jd = d1.to_jdatetime()
print(jd)        # jdatetime.date(...)
```

---

## Partial Dates & Ranges

- `HijriDate(1446)` → represents the whole year.
- `HijriDate(1446, 2)` → represents all days of month 2.
- Conversion to Gregorian returns ranges:

* **Year only**

  ```python
  d = HijriDate(1446)
  start, end = d.to_gregorian_range()
  print(start, end)  # 2024-07-18 2025-07-06 (example)
  ```

* **Year and Month only**

  ```python
  d = HijriDate(1446, 2)
  start, end = d.to_gregorian_range()
  print(start, end)  # 2025-09-01 2025-09-30 (example)
  ```

---

## Gregorian ↔ Hijri Conversion

```python
from hijri_datetime import HijriConverter

converter = HijriConverter()

# Hijri → Gregorian
greg = converter.hijri_to_gregorian(1446, 2, 15)
print(greg)  # datetime.date(2025, 9, 9)

# Gregorian → Hijri
hijri = converter.gregorian_to_hijri(greg)
print(hijri)  # HijriDate(1446, 2, 15)
```

---

## jdatetime Integration

```python
from hijri_datetime import HijriDate

d = HijriDate(1446, 2, 15)
jd = d.to_jdatetime()
print(jd)  # jdatetime.date(2025, 6, 16) example
```

---

## Pandas / Vectorized Example

```python
import pandas as pd
from hijri_datetime import HijriDate

dates = pd.Series([HijriDate(1446, 1, 1), HijriDate(1446, 2, 10)])
greg_dates = dates.apply(lambda x: x.to_gregorian())
print(greg_dates)
```

---

## Roadmap

* [ ] Full `calendar` module API compatibility
* [ ] Timezone-aware Hijri datetime
* [ ] Support for Umm al-Qura, tabular, and other Hijri variants
* [ ] Improved bulk conversion performance
* [ ] PyPI release with automated dataset update from Aladhan API

---

## Contributing

Pull requests are welcome! Please open an issue first to discuss major changes.
Could you make sure tests pass before submitting PRs?

---

## License

GNU License © 2025
