Contributing

PyRapide is open source under the MIT License. Contributions of all kinds are welcome: code, documentation, bug reports, and ideas.

How to Contribute

Clone the repository, set up a virtual environment, and install the development dependencies. The entire setup takes under a minute.

setup bash
$ git clone https://github.com/ShaneDolphin/pyrapide.git
cd pyrapide
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Verify everything works by running the test suite, type checker, and linter:

verify bash
$ pytest
mypy src/
ruff check src/

All three must pass cleanly before submitting a pull request.

Development Workflow

PyRapide follows a strict test-driven development workflow. Every change follows the same sequence:

1

Write the test first

Define the expected behavior in a test before writing any implementation code. Tests go in the tests/ directory, mirroring the source structure.

2

Confirm it fails

Run pytest and verify that the new test fails for the expected reason. A test that passes before you write the implementation is testing nothing.

3

Implement the feature

Write the minimum code needed to make the test pass. Resist the urge to add functionality that is not yet tested.

4

Zero regressions

Run the full test suite. Every existing test must still pass. If a change breaks an existing test, fix the regression before proceeding.

5

Type check and lint

Run mypy src/ and ruff check src/. Both must produce zero errors, zero warnings.

Code Standards

All code must meet these requirements:

  • ✓ Python 3.11+. Use modern syntax including match statements, type aliases, and ExceptionGroup where appropriate.
  • ✓ Frozen Pydantic models. All data classes must be immutable. Use model_config = ConfigDict(frozen=True) or the frozen=True class parameter.
  • ✓ Async by default. All action methods and handlers must use async def. Synchronous wrappers may be provided for convenience but must not be the primary API.
  • ✓ Docstrings on all public symbols. Use Google-style docstrings. Every public class, method, and function must be documented with a summary, parameter descriptions, return type, and at least one example.
  • ✓ Full type annotations. All function signatures must have complete type hints. No Any unless genuinely unavoidable.

What to Contribute

There are many areas where contributions would have significant impact:

Adapters

New event source adapters for Kafka, RabbitMQ, Redis Streams, AWS EventBridge, or other messaging systems. Each adapter translates external events into causally-linked PyRapide events.

Visualization Backends

Interactive visualization using D3.js, Cytoscape.js, or other graph rendering libraries. The current backends produce static output; interactive exploration of causal graphs would be valuable.

Pattern Operators

New pattern combinators beyond the current set. RAPIDE's original specification hinted at additional operators that were never fully implemented.

Performance

Optimizations for large-scale computations: faster graph algorithms, memory-efficient poset storage, incremental pattern matching for streaming workloads.

Documentation

Tutorials, examples, and guides. Particularly welcome are real-world case studies showing PyRapide applied to production systems.

Bug Reports

Clear, reproducible bug reports with minimal test cases. A well-written bug report is as valuable as a code contribution.

Repository

All development happens in the open on GitHub.

Source Code Issue Tracker Pull Requests

PyRapide is released under the MIT License. By contributing, you agree that your contributions will be licensed under the same terms.