Add GitHub Actions workflows for release and testing, implement comprehensive tests for epidemiological week calculations

Author: Keng Susumpow

.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Build package
+      run: python -m build
+    
+    - name: Check distribution
+      run: twine check dist/*
+    
+    - name: Create GitHub Release
+      uses: actions/create-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: ${{ github.ref }}
+        release_name: Release ${{ github.ref }}
+        draft: false
+        prerelease: false

.github/workflows/test.yml

@@ -0,0 +1,84 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements-dev.txt
+        pip install -e .
+    
+    - name: Run tests with pytest
+      run: |
+        pytest tests/ -v --tb=short --cov=epydem --cov-report=xml --cov-report=term-missing
+    
+    - name: Test package functionality
+      run: |
+        python -c "
+        import epydem
+        result = epydem.calculate('2024-01-01')
+        print(f'2024-01-01 is epidemiological week {result}')
+        assert result > 0, 'Expected positive week number'
+        print('Package functionality test passed')
+        "
+    
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 black isort
+    
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 epydem --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 epydem --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    
+    - name: Check code formatting with black
+      run: |
+        black --check epydem
+    
+    - name: Check import sorting with isort
+      run: |
+        isort --check-only epydem
+    
+    - name: Check tests formatting
+      run: |
+        black --check tests/

.gitignore

@@ -0,0 +1,23 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Package build artifacts
+*egg-info/
+build/
+dist/
+
+# Testing
+.pytest_cache/
+
+# Virtual environments
+venv/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+
+# macOS
+.DS_Store

CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Epydem is a Python library for epidemiological data analysis, specifically focused on calculating epidemiological week numbers from date strings. The library provides a single main function that converts dates in YYYY-MM-DD format to epidemiological week numbers.
+
+## Development Commands
+
+```bash
+# Install the package locally for development
+pip install .
+
+# Install from GitHub
+pip install git+https://github.com/kengggg/epydem.git
+
+# Build the package
+python setup.py build
+
+# Create source distribution
+python setup.py sdist
+```
+
+## Code Architecture
+
+The library follows a simple, focused architecture:
+
+- **epydem/__init__.py**: Exports the main `calculate` function as the public API
+- **epydem/epiweek.py**: Contains the core epidemiological week calculation logic
+  - `calculate(date_str)`: Main function that takes YYYY-MM-DD date string and returns epidemiological week number
+  - `_verify_date_str(date_str)`: Private helper function for strict date format validation
+
+## Key Implementation Details
+
+- **Date Format**: Strictly enforces YYYY-MM-DD format using regex validation
+- **Epidemiological Week Logic**: Week 1 starts on the Sunday before the first Thursday of the year
+- **Error Handling**: Raises ValueError with descriptive messages for invalid date formats
+- **Return Values**: Returns week numbers 1-53, or 0 for dates before the start of the epidemiological year
+
+## Code Conventions
+
+- Private functions are prefixed with underscore (e.g., `_verify_date_str`)
+- Comprehensive docstrings following Python conventions with Args, Returns, and Raises sections
+- Clean public API exposure through `__init__.py`
+- No external dependencies - uses only Python standard library
+
+## Testing Notes
+
+Currently no test framework is configured. When adding tests, follow the existing function naming patterns and ensure coverage of:
+- Valid date inputs across different years
+- Invalid date format handling
+- Edge cases around year boundaries
+- Week 0 scenarios

README.md

@@ -1,10 +1,45 @@
 # Epydem
 
-`Epydem` is a Python library for epidemiological data analysis.
+`Epydem` is a Python library for calculating epidemiological week numbers from date strings.
+
+## Features
+
+- Calculate epidemiological week numbers from YYYY-MM-DD formatted dates
+- Follows standard epidemiological week definition where week 1 starts on the Sunday before the first Thursday of the year
+- Returns week numbers 1-53, or 0 for dates before the epidemiological year starts
+- Strict date format validation with clear error messages
 
 ## Installation
 
 You can install the library using pip:
 
 ```bash
 pip install git+https://github.com/kengggg/epydem.git
+```
+
+## Usage
+
+```python
+import epydem
+
+# Calculate epidemiological week for a date
+week_number = epydem.calculate('2024-01-01')
+print(week_number)  # Output: 1
+
+# Week 1 starts on the Sunday before the first Thursday
+week_number = epydem.calculate('2024-01-04')  # First Thursday of 2024
+print(week_number)  # Output: 1
+
+# Dates before the epidemiological year return 0
+week_number = epydem.calculate('2023-12-31')  # Before 2024's epi year
+print(week_number)  # Output: 0
+```
+
+## Epidemiological Week Definition
+
+Epidemiological weeks follow the standard definition:
+
+- Week 1 is the first week that contains the first Thursday of the year
+- Each epidemiological week starts on Sunday and ends on Saturday
+- The epidemiological year may start in the previous calendar year
+- Week numbers range from 1-53, with 0 for dates before the epidemiological year begins

epydem/epiweek.py

@@ -13,7 +13,7 @@ def calculate(date_str):
     date_str (str): The date in 'YYYY-MM-DD' format.
 
   Returns:
-    int: The epidemiological week number. Returns 0 if the date is
+    int: The epidemiological week number (1-53). Returns 0 if the date is
     before the start of the epidemiological year.
 
   Raises:
@@ -23,14 +23,19 @@ def calculate(date_str):
     date = datetime.strptime(date_str, '%Y-%m-%d')
     year = date.year
 
-    year_start = datetime(year, 1, 1)
-    week_start = year_start - timedelta(days=year_start.weekday() + 1)
+    # Find the first Thursday of the year
+    jan_1 = datetime(year, 1, 1)
+    days_to_thursday = (3 - jan_1.weekday()) % 7
+    first_thursday = jan_1 + timedelta(days=days_to_thursday)
+    
+    # The epidemiological week 1 starts on the Sunday before the first Thursday
+    epi_week_1_start = first_thursday - timedelta(days=3)
 
     # If the date is before the start of the epidemiological year, it's week 0
-    if date < week_start:
+    if date < epi_week_1_start:
       return 0
     else:
-      return (date - week_start).days // 7
+      return ((date - epi_week_1_start).days // 7) + 1
 
 def _verify_date_str(date_str):
   """

pytest.ini

@@ -0,0 +1,11 @@
+[tool:pytest]
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*
+python_classes = Test*
+addopts = 
+    -v
+    --tb=short
+    --strict-markers
+    --disable-warnings
+minversion = 6.0

requirements-dev.txt

@@ -0,0 +1,2 @@
+pytest>=6.0.0
+pytest-cov>=2.10.0