Metadata-Version: 2.5
Name: ethioqen
Version: 0.2.2
Summary: A package for Ethiopian date and time conversions
Project-URL: Bug Reports, https://github.com/beabzk/ethioqen/issues
Project-URL: Source, https://github.com/beabzk/ethioqen
Author-email: Beabfekad Zikie <beabzk@proton.me>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Localization
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ethioqen: Ethiopian Calendar, Time, and Unix Timestamp Conversion

> ⚠️ **Warning**: This library is in very early stages of development and should not be used in production. Contributions are crucial to make this production-ready.

[![PyPI version](https://badge.fury.io/py/ethioqen.svg)](https://badge.fury.io/py/ethioqen)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Upload Python Package](https://github.com/beabzk/ethioqen/actions/workflows/publish.yml/badge.svg?event=release)](https://github.com/beabzk/ethioqen/actions/workflows/publish.yml)

`ethioqen` is a Python library that provides accurate and efficient conversions between the Ethiopian calendar, the Gregorian calendar, Ethiopian local time (12-hour format), standard 24-hour local time, and Unix timestamps.

## Introduction

The Ethiopian calendar is a solar calendar used in Ethiopia and Eritrea. It differs significantly from the Gregorian calendar, which is the most widely used calendar system today.

**Key Differences:**

* **Year Offset:** The Ethiopian calendar is typically 7-8 years behind the Gregorian calendar.
* **Months:** It has 13 months: 12 months of 30 days each and a 13th month called *Pagume*, which has 5 days (6 days in a leap year).
* **New Year:** The Ethiopian New Year (*Enkutatash*) falls on September 11th (or 12th in a Gregorian leap year).
* **Leap Years:** Ethiopia follows a simple 4-year leap year cycle without the century exception found in the Gregorian calendar.

**Ethiopian Local Time:**

Ethiopian time uses a 12-hour clock that starts counting from dawn (around 6:00 AM standard time). This creates a 6-hour offset between Ethiopian and standard time:

* 12:00 AM Ethiopian = 6:00 AM standard time
* 1:00 AM Ethiopian = 7:00 AM standard time
* 12:00 PM Ethiopian = 6:00 PM standard time
* 6:00 PM Ethiopian = 12:00 AM standard time (next day)

## Installation

```bash
pip install ethioqen
```

## Development Setup

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).

```bash
uv sync --all-groups
```

## Usage Examples

### Calendar Conversions

```python
from ethioqen.calendar_conversion import (
    convert_ethiopian_to_gregorian,
    convert_gregorian_to_ethiopian,
)

# Convert from Ethiopian to Gregorian
greg_year, greg_month, greg_day = convert_ethiopian_to_gregorian(2016, 7, 6)
print(f"{greg_year}-{greg_month}-{greg_day}")  # Output: 2024-3-15

# Convert from Gregorian to Ethiopian
eth_year, eth_month, eth_day = convert_gregorian_to_ethiopian(2024, 3, 15)
print(f"{eth_year}-{eth_month}-{eth_day}")  # Output: 2016-7-6
```

### Time Conversions

```python
from ethioqen.time_conversion import (
    convert_to_ethiopian_time,
    convert_from_ethiopian_time,
)

# Convert standard time (14:30 / 2:30 PM) to Ethiopian time
eth_hour, eth_minute, is_day = convert_to_ethiopian_time(14, 30)
print(f"{eth_hour}:{eth_minute} {'AM' if is_day else 'PM'}")  # Output: 8:30 PM

# Convert Ethiopian time (8:30 PM) to standard time
std_hour, std_minute = convert_from_ethiopian_time(8, 30, is_am=False)
print(f"{std_hour:02d}:{std_minute:02d}")  # Output: 14:30
```

### Unix Timestamp Conversions

```python
from ethioqen.unix_time_conversion import ethiopian_to_unix, unix_to_ethiopian

# Convert Ethiopian date/time to Unix timestamp (UTC)
# 1:30 PM Ethiopian time
timestamp = ethiopian_to_unix(2016, 7, 6, eth_hour=1, minute=30, is_pm=True)
print(timestamp)  # Output: Unix timestamp

# Convert Unix timestamp to Ethiopian date/time (UTC)
eth_year, eth_month, eth_day, hour, minute, is_pm = unix_to_ethiopian(timestamp)
print(f"{eth_year}-{eth_month}-{eth_day} {hour}:{minute:02d} {'PM' if is_pm else 'AM'}")
# Output: 2016-7-6 1:30 PM
```

### Timezone Support

```python
from ethioqen.unix_time_conversion import ethiopian_to_unix, unix_to_ethiopian

# Convert with timezone offset (UTC+3 for Ethiopia)
# 8:30 AM Ethiopian time
timestamp = ethiopian_to_unix(
    2016, 7, 6, eth_hour=8, minute=30, is_pm=False, tz_offset=3
)
print(timestamp)  # Output: Unix timestamp adjusted for UTC+3

# Convert back with timezone offset
eth_date = unix_to_ethiopian(timestamp, tz_offset=3)
print(
    f"{eth_date[0]}-{eth_date[1]}-{eth_date[2]} {eth_date[3]}:{eth_date[4]:02d} {'PM' if eth_date[5] else 'AM'}"
)
# Output: Ethiopian date/time in UTC+3
```

## Contributing

We welcome contributions! Here's how you can help:

1. **Report Bugs**
   * Open an issue in the [GitHub issue tracker](https://github.com/beabzk/ethioqen/issues)
   * Include a clear description and steps to reproduce

2. **Submit Pull Requests**
   * Fork the repository
   * Create a new branch for your feature (`git checkout -b feature/amazing-feature`)
   * Make your changes
   * Write or update tests as needed
   * Update documentation if necessary
   * Submit a pull request

3. **Coding Style**
    * Follow PEP 8 guidelines (enforced with `ruff`: `uv run ruff check .` and `uv run ruff format --check .`)
    * Include docstrings for new functions/classes
    * Add type hints where possible

4. **Testing**
    * Run the test suite: `uv run pytest`
    * Add tests for new features
    * Ensure all tests pass before submitting (`uv run ruff check . && uv run ruff format --check . && uv run pytest`)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
