Metadata-Version: 2.4
Name: twdate
Version: 1.1.0
Summary: A simple package to convert between the Gregorian calendar and the Taiwanese calendar.
License: MIT
License-File: LICENSE
Author: Anthony Sung
Author-email: sungpinyue@gmail.com
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: MIT License
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
Requires-Dist: click (>=8.3.1,<9.0.0)
Description-Content-Type: text/markdown

# twdate

<img src="https://img.shields.io/badge/Python-%3E%3D3.10-3776AB?style=for-the-badge&logo=python&logoColor=white" />
<img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" />

[中文版](https://github.com/yueswater/twcal/blob/main/README_zh-TW.md)

A simple Python package to convert between the Gregorian calendar and the Taiwanese (Minguo) calendar.

## Installation

```bash
pip install twdate
```

## Usage

### Create a Minguo date

```python
from twcal import TWDate

d = TWDate(115, 3, 20)  # 民國115年3月20日
```

### Convert between Gregorian and Minguo

```python
import datetime
from twcal import to_minguo, to_gregorian

# Gregorian -> Minguo
tw = to_minguo(datetime.date(2026, 3, 20))
# TWDate(year=115, month=3, day=20)

# Minguo -> Gregorian
gd = to_gregorian(tw)
# datetime.date(2026, 3, 20)
```

### Get today's date in Minguo format

```python
from twcal import today

d = today()
print(d)  # 民國115年3月20日
```

### Format as string

```python
d = TWDate(115, 3, 20)

d.to_string()        # '民國115年3月20日'
d.to_short_string()  # '1150320'
str(d)               # '民國115年3月20日'
```

### Parse from short string

```python
d = TWDate.from_short_string("1150320")
# TWDate(year=115, month=3, day=20)
```

### Pre-Minguo dates

```python
import datetime
from twcal import to_minguo

d = to_minguo(datetime.date(1911, 1, 1))
# TWDate(year=-1, month=1, day=1)

print(d)  # 民國前1年1月1日
```

### CLI

```bash
# Show today's date in Minguo format
twdate now

# Convert Gregorian to Minguo
twdate convert 2026-03-20

# Convert Minguo to Gregorian
twdate convert -g 115-03-20
```

### Comparison

```python
from twcal import TWDate

TWDate(115, 1, 1) > TWDate(114, 12, 31)   # True
TWDate(114, 1, 1) < TWDate(115, 1, 1)     # True
```

### Validation

```python
from twcal import TWDate

TWDate(0, 1, 1)    # ValueError: 民國0年不存在
TWDate(115, 2, 30) # ValueError: day is out of range for month
```

## License

This project is licensed under the [MIT License](LICENSE). You are free to use, modify, and distribute this software for any purpose, including commercial use.

