Thank you for your interest in contributing to Cyclopts! This guide will help you get started.

Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive experience for everyone.

Looking for something to work on? Check out issues labeled good first issue on GitHub. These are curated to be approachable for new contributors.

If you're exploring the codebase, these are good entry points:

• cyclopts/core.py — the main App class and CLI lifecycle
• cyclopts/bind.py — token-to-parameter binding
• cyclopts/_convert.py — type conversion logic
• cyclopts/parameter.py — parameter configuration API

• Python 3.10 or later
• uv (recommended package manager)

1. Fork and clone the repository:

   # Replace with your fork URL, if appropriate
   git clone https://github.com/BrianPugh/cyclopts.git
   cd cyclopts

2. Install dependencies (including dev extras):

   uv sync --all-extras

3. Install pre-commit hooks:

   uv run pre-commit install

# Run all tests
uv run pytest

# Run all tests with coverage
uv run pytest --cov=cyclopts --cov-config=pyproject.toml --cov-report term

# Run a specific test file
uv run pytest tests/test_core.py

# Run a specific test function
uv run pytest tests/test_core.py::test_function_name

Tests automatically run in isolated temporary directories. Python 3.12+ specific tests live in tests/py312/ and are skipped on older versions.

Pre-commit hooks run automatically on git commit. You can also run them manually:

# Run all checks
uv run pre-commit run --all-files

# Run individual tools
uv run ruff check --fix   # Linting
uv run ruff format         # Formatting
uv run pyright             # Type checking

• Line length: 120 characters
• Docstrings: NumPy-style convention
• Type hints: Pyright strict mode
• Target Python: 3.10+ (do not use syntax or features exclusive to newer versions without version guards)

cd docs
make html

1. Create a feature branch from main.
2. Make your changes, adding tests for new functionality.
3. Ensure all checks pass:

   uv run pre-commit run --all-files
   uv run pytest

4. Push your branch and open a pull request against main.

• Write clear, concise commit messages describing what changed and why.
• Reference related issues in your PR description (e.g., Fixes #123).
• There is no changelog to update — that is handled by the maintainers.

If a PR has been opened to fix an issue you reported, you can test it by installing Cyclopts directly from the PR branch:

pip install git+https://github.com/BrianPugh/cyclopts.git@branch-name

Or with uv:

uv pip install git+https://github.com/BrianPugh/cyclopts.git@branch-name

Replace branch-name with the branch listed on the PR.

Alternatively, you can clone the repo and install in editable mode into your project's virtual environment:

git clone https://github.com/BrianPugh/cyclopts.git
cd cyclopts
git checkout branch-name

# Activate your project's virtual environment, then:
pip install -e .

Verify the fix against your original reproducer and report back on the PR.

Open an issue on GitHub with:

• A minimal reproducible example.
• Your Python version and Cyclopts version (python -c "import cyclopts; print(cyclopts.__version__)").
• The expected vs. actual behavior.

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.