Contributing to FACETpy

Thanks for contributing. This guide documents the current development workflow. For package-only usage, see Quick Start.

Terminal Conventions

  • bash blocks target Unix shells (macOS/Linux).

  • Commands shown as text are identical on both platforms.

Quick Setup

  1. Fork https://github.com/H0mire/facetpy.

  2. Clone your fork.

git clone https://github.com/<your-username>/facetpy.git
cd facetpy

  1. Install contributor dependencies (uv required).

Unix (macOS/Linux):

./scripts/install.sh

Optional one-shot setup (non-fork checkout):

curl -fsSL https://raw.githubusercontent.com/H0mire/facetpy/main/scripts/bootstrap.sh | sh
cd facetpy

Other platforms (including Windows):

uv sync --locked

  1. (Optional) Install docs dependencies when working on documentation.

uv sync --extra docs

  1. Strongly recommended: compile FastRANC for ANC performance.

python -m facet.build
# or: uv run build-fastranc

  1. Verify your environment.

uv run pytest -m "not slow"

Development Workflow

  1. Create a topic branch.

git checkout -b feature/<short-topic>

  1. Implement the change in src/facet.

  2. Add or update tests in tests.

  3. Update docs in docs/source when behavior or API changes.

  4. Run lint check and fix.

uv run ruff check src tests
uv run ruff check --fix src tests
uv run ruff format src tests

  1. Run checks locally.

uv run pytest

  1. Build docs locally when docs changed.

uv run sphinx-build -b html docs/source docs/build

VS Code users can run these steps via the predefined tasks in .vscode/tasks.json (e.g. Lint: Fix (Ruff), Test: Run All, Docs: Build HTML) using the Command Palette (Tasks: Run Task).

Code Style

  • Follow PEP 8 with four-space indentation.

  • Use descriptive snake_case names for functions/variables/modules.

  • Use PascalCase for classes and UPPER_CASE for constants.

  • Prefer explicit imports from facet modules.

  • Keep public APIs type hinted.

  • Use loguru for diagnostic logging.

Linting and Formatting

Ruff is the active linter configuration for this repository.

uv run ruff check src tests

(Optional auto-fix)

uv run ruff check --fix src tests

Testing

  • Place tests under tests/<module>/test_<feature>.py.

  • Use markers for heavy scenarios:

    • @pytest.mark.slow

    • @pytest.mark.requires_data

    • @pytest.mark.requires_c_extension

  • Use deterministic fixtures and sample data from examples when possible.

Run tests:

uv run pytest

Run a subset:

uv run pytest -m "not slow"

Documentation Style

Use NumPy-style docstrings for public code.

def my_function(param1: str, param2: int = 10) -> bool:
    """One-line summary.

    Parameters
    ----------
    param1 : str
        Description of param1.
    param2 : int, optional
        Description of param2.

    Returns
    -------
    bool
        Description of return value.
    """

Pull Requests

Before opening a PR:

  1. Ensure tests pass locally.

  2. Ensure documentation is updated for user-facing changes.

  3. Include a concise description of what changed and why.

  4. Link related issues when applicable.

  5. Mention skipped test markers (if any) with a reason.

Commit messages in this repository typically start with lowercase topic tags, for example:

  • docs, refactor: clarify pipeline flow

  • fix: handle missing trigger channel