refactor: modernize lunardate package

.github/workflows/python-package.yml

@@ -1,13 +1,13 @@
 # This workflow will install Python dependencies, run tests and lint with a variety of Python versions
 # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
 
-name: Python package
+name: CI
 
 on:
   push:
-    branches: [ "master" ]
+    branches: [ "main", "master" ]
   pull_request:
-    branches: [ "master" ]
+    branches: [ "main", "master" ]
 
 jobs:
   build:
@@ -16,25 +16,24 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-    - name: Lint with flake8
+        python -m pip install -e ".[dev]"
+    - name: Lint with ruff
       run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+        ruff check .
+    - name: Type check with mypy
+      run: |
+        mypy src/
     - name: Test with pytest
       run: |
-        python lunardate.py -v
+        pytest --tb=short -q

.gitignore

@@ -1,4 +1,27 @@
-*.pyc
+__pycache__/
+*.py[cod]
+*.pyd
 *.swp
-build
-dist
+*.swo
+
+*.egg
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+build/
+dist/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+.venv/
+venv/
+
+.DS_Store
+.vscode/
+context_portal/

LICENSE.txt

@@ -1,3 +1,6 @@
+This project is licensed under the GNU General Public License v3.0 only.
+See NOTICE.md for attribution and upstream sources.
+
                     GNU GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 

NOTICE.md

@@ -0,0 +1,11 @@
+Attribution Notice
+==================
+
+This project is a modernization of the original `python-lunardate` library by
+LI Daobing (lidaobing@gmail.com), licensed under GPL-3.0-only.
+
+Upstream repository:
+https://github.com/lidaobing/python-lunardate
+
+The conversion data and algorithms are derived from the C program `lunar`:
+http://packages.qa.debian.org/l/lunar.html

README.md

@@ -4,92 +4,90 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/lunardate)](https://pypi.org/project/lunardate/)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/lunardate)](https://pypistats.org/packages/lunardate)
 
-
 Chinese Calendar: http://en.wikipedia.org/wiki/Chinese_calendar
 
 ## Install
 
-```
+```bash
 pip install lunardate
 ```
 
-## Usage
+## Quick Start
+
+```python
+import datetime
+
+from lunardate import LunarDate
+
+lunar = LunarDate.from_solar_date(1976, 10, 1)
+assert repr(lunar) == "LunarDate(1976, 8, 8, True)"
 
+solar = lunar.to_solar_date()
+assert solar == datetime.date(1976, 10, 1)
+
+today = LunarDate.today()
 ```
-        >>> from lunardate import LunarDate
-        >>> LunarDate.fromSolarDate(1976, 10, 1)
-        LunarDate(1976, 8, 8, 1)
-        >>> LunarDate(1976, 8, 8, 1).toSolarDate()
-        datetime.date(1976, 10, 1)
-        >>> LunarDate(1976, 8, 8, 1).year
-        1976
-        >>> LunarDate(1976, 8, 8, 1).month
-        8
-        >>> LunarDate(1976, 8, 8, 1).day
-        8
-        >>> LunarDate(1976, 8, 8, 1).isLeapMonth
-        True
-
-        >>> today = LunarDate.today()
-        >>> type(today).__name__
-        'LunarDate'
-
-        >>> # support '+' and '-' between datetime.date and datetime.timedelta
-        >>> ld = LunarDate(1976,8,8)
-        >>> sd = datetime.date(2008,1,1)
-        >>> td = datetime.timedelta(days=10)
-        >>> ld-ld
-        datetime.timedelta(0)
-        >>> ld-sd
-        datetime.timedelta(-11444)
-        >>> ld-td
-        LunarDate(1976, 7, 27, 0)
-        >>> sd-ld
-        datetime.timedelta(11444)
-        >>> ld+td
-        LunarDate(1976, 8, 18, 0)
-        >>> td+ld
-        LunarDate(1976, 8, 18, 0)
-        >>> ld2 = LunarDate.today()
-        >>> ld < ld2
-        True
-        >>> ld <= ld2
-        True
-        >>> ld > ld2
-        False
-        >>> ld >= ld2
-        False
-        >>> ld == ld2
-        False
-        >>> ld != ld2
-        True
-        >>> ld == ld
-        True
-        >>> LunarDate.today() == LunarDate.today()
-        True
-
-        >>> LunarDate.leapMonthForYear(2023)
-        2
-        >>> LunarDate.leapMonthForYear(2022)
-        None
+
+## API Highlights
+
+- `LunarDate.from_solar_date(year, month, day) -> LunarDate`
+- `LunarDate.to_solar_date() -> datetime.date`
+- `LunarDate.leap_month_for_year(year) -> int | None`
+- Arithmetic with `datetime.timedelta`
+
+## Migration Guide (0.2.x → 1.0.0)
+
+Old camelCase names are still available as deprecated aliases and emit `DeprecationWarning`.
+
+| Old Name | New Name |
+|----------|----------|
+| `fromSolarDate` | `from_solar_date` |
+| `toSolarDate` | `to_solar_date` |
+| `leapMonthForYear` | `leap_month_for_year` |
+| `isLeapMonth` | `is_leap_month` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy src/
+ruff check .
 ```
 
-## News
+## Version History
 
-* 0.2.2: add LunarDate.leapMonthForYear; fix bug in year 1899
-* 0.2.1: fix bug in year 1956
-* 0.2.0: extend year to 2099, thanks to @FuGangqiang
-* 0.1.5: fix bug in `==`
-* 0.1.4: support '+', '-' and compare, fix bug in year 2050
-* 0.1.3: support python 3.0
+- 1.0.0: Modernized package layout, typed API, pytest suite, PEP 8 method names
+- 0.2.2: add LunarDate.leapMonthForYear; fix bug in year 1899
+- 0.2.1: fix bug in year 1956
+- 0.2.0: extend year to 2099, thanks to @FuGangqiang
+- 0.1.5: fix bug in `==`
+- 0.1.4: support '+', '-' and compare, fix bug in year 2050
+- 0.1.3: support python 3.0
 
 ## Limits
 
-this library can only deal with year from 1900 to 2099 (in chinese calendar).
+This library can only deal with years from 1900 to 2099 (Chinese calendar years).
+
+## Attribution
+
+This project is a modernization of the original `python-lunardate` library by
+LI Daobing (lidaobing@gmail.com). Upstream source:
+https://github.com/lidaobing/python-lunardate
+
+The conversion data and algorithms are derived from the C program `lunar`:
+http://packages.qa.debian.org/l/lunar.html
+
+See `NOTICE.md` for attribution details.
+
+## License
+
+Licensed under the GNU General Public License v3.0 only (GPL-3.0-only).
+See `LICENSE.txt` and `NOTICE.md`.
 
 ## See also
 
-* lunar: http://packages.qa.debian.org/l/lunar.html,
+- lunar: http://packages.qa.debian.org/l/lunar.html,
   A converter written in C, this program is derived from it.
-* python-lunar: http://code.google.com/p/liblunar/
+- python-lunar: http://code.google.com/p/liblunar/
   Another library written in C, including a python binding.