Contributing

Contributions are welcome. This guide covers setup, coding standards, and the PR process.

Development setup

git clone https://github.com/fastpii/fastpii.git
cd fastpii
pip install -e ".[dev]"

This installs the package in editable mode with development tools: pytest, ruff, and mypy.

Running tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/detectors/test_cz_rodne_cislo.py

# Run data integrity tests
pytest tests/data/

Code quality

# Lint
ruff check src/fastpii tests/

# Format
ruff format src/fastpii tests/

# Type check
mypy src/fastpii

Adding a detector

1. Create a new detector file in src/fastpii/detectors/<region>/
2. Subclass Detector from fastpii.detectors.base
3. Implement detect(), validate(), and optionally _extract_metadata()
4. Add tests in tests/detectors/
5. Register in the country pack's detectors property

Adding a country pack

1. Create src/fastpii/countries/<code>/ directory with __init__.py, pack.py, patterns.py, validators.py
2. Create src/fastpii/countries/<code>/data/ directory with data modules
3. Implement CountryPack with detectors, patterns, and validators
4. Add tests in tests/
5. Keep PRs focused and tested

PR guidelines

• Keep PRs small and focused
• Add tests for new functionality
• Run ruff check and mypy before submitting
• Follow existing code conventions
• Do not add external dependencies to the core package

Architecture principles

• Zero external dependencies for the core package
• Explicit registration over implicit discovery
• Checksum validation for all official identifiers
• ASCII transliteration for all country data (no umlauts/accents)
• Lazy data loading via if self._data is None: from ... import X