Contribuer à Ketu

Nous sommes heureux d’accueillir vos contributions !

Comment contribuer

1. Fork the Project

# Fork on GitHub and then clone
git clone https://github.com/alkimya/ketu.git
cd ketu

2. Set Up a Development Environment

# Create a virtual environment
python -m venv venv

# Install in development mode with all dev extras
pip install -e ".[dev]"

L’extra [dev] installe pytest, pytest-cov, mypy, sphinx, myst-parser, interrogate et d’autres outils de développement.

3. Create a Branch

git checkout -b feature/my-new-feature

4. Develop and Test

# Run the full test suite
pytest tests/ -v

# Run with coverage check (must reach 100%)
pytest tests/ --cov=ketu --cov-fail-under=100

# Type checking (strict mode)
mypy ketu/

# Run doctests
pytest --doctest-modules ketu/ --no-cov

# Docstring coverage gate
interrogate ketu/ --fail-under 95

# Numpydoc lint
python -m numpydoc --validate ketu/

5. Commit with a Clear Message

git add src/module.py
git commit -m "feat: add house calculation"

Préfixes de message de commit :

feat: Nouvelle fonctionnalité
fix: Correction de bug
docs: Documentation
style: Formatage ou style de code
refactor: Refactorisation
test: Ajout de tests
chore: Tâches de maintenance

6. Push and Open a Pull Request

git push origin feature/my-new-feature

Puis créer une PR sur GitHub.

Directives de développement

Style de code

Suivre PEP 8 pour le code Python
Docstrings au style NumPy (obligatoires pour le gate numpydoc)
Annotations de type partout (mypy strict)
Maximum 88 caractères par ligne (défaut de Black)

Tests

Objectif de couverture : 100% (imposé via fail_under=100 en CI)
Pas d’annotations # pragma: no cover — les branches inaccessibles sont gérées via exclude_lines dans pyproject.toml
Utiliser pytest pour les tests unitaires
Ajouter des doctests (>>>) pour toutes les fonctions publiques

Documentation

Documenter chaque nouvelle fonction publique avec des Docstrings au style NumPy
Inclure une section Examples avec les invites >>> dans les Docstrings (collectées par make doctest)
Mettre à jour la documentation Sphinx dans docs/source/ lors de l’ajout de fonctionnalités
Utiliser le style from ketu.submodule import function — pas import ketu; ketu.function()

Politique pyswisseph

pyswisseph est réservé aux tests/validation — il n’est jamais importé à l’exécution. Le code d’exécution doit être Pure NumPy. Cela maintient l’isolation AGPL. Si un nouveau calcul nécessite des données Swiss Ephemeris, générer des coefficients hors ligne (comme cela a été fait pour Chiron en v1.3) et les embarquer sous forme de fichiers .npz.

Architecture du projet

ketu/
├── __init__.py          # Public re-exports (bodies, aspects, signs, HOUSES_DTYPE…)
├── core.py              # Data structures: bodies (14), aspects, signs
├── calculations.py      # High-level API: long, lat, body_sign, is_retrograde…
├── display.py           # CLI display: print_positions, print_aspects, main
├── aspects/             # Configurable aspect sets (CLASSICAL/TRADITIONAL/EXTENDED)
├── houses/              # Six house systems + HOUSES_DTYPE + HighLatitudeError
├── charts/              # Full natal chart: compute_chart, is_day_chart, CHART_DTYPE
├── synastry/            # Inter-chart aspects: calculate_synastry, SYNASTRY_DTYPE
├── composite/           # Midpoint composite: calculate_composite, circular_midpoint
├── returns/             # Solar/lunar returns: solar_return, lunar_return
├── parts/               # Arabic Parts: PARTS, calculate_part, calculate_all_parts
├── data/                # Embedded coefficient data (chiron_coeffs.npz)
└── ephemeris/           # Pure NumPy astronomical engine
    ├── time.py          # Time conversions
    ├── orbital.py       # Orbital mechanics (re-export hub)
    ├── _elements.py     # ORBITAL_ELEMENTS + Lilith constants
    ├── _perturbations.py # Perturbation strategies
    ├── coordinates.py   # Coordinate transformations
    ├── planets.py       # Planetary position dispatch (BODY_STRATEGIES)
    └── chiron.py        # Chiron Chebyshev evaluator (v1.3)
tests/
├── conftest.py          # Shared session-scoped fixtures
├── test_ketu.py         # Top-level API tests
└── [subpackage tests]

Gates de qualité (CI)

Tous les éléments suivants doivent passer avant de fusionner :

Gate	Commande	Cible
Tests	`pytest tests/`	Tous passent
Couverture	`pytest --cov=ketu --cov-fail-under=100`	100%
Vérification de types	`mypy ketu/`	0 erreur (strict)
Couverture des Docstrings	`interrogate ketu/ --fail-under 95`	≥95%
Lint numpydoc	`python -m numpydoc --validate ketu/`	0 violation
Doctests	`pytest --doctest-modules ketu/ --no-cov`	Tous passent

Processus de revue

Tests : la suite complète doit passer
Couverture : doit rester à 100% (aucune diminution autorisée)
Documentation : la garder à jour et claire
Style : respecter les conventions convenues
Performance : éviter les régressions