Development#
Before contributing, read the AI Policy. It covers AI assistance and automated contribution farms. Contributors without write access may have one open PR, including drafts, until their first PR is merged into FastStream.
After cloning the project, you'll need to set up the development environment. Here are the guidelines on how to do this.
Install Justfile Utility#
Install justfile on your system:
https://just.systems/man/en/prerequisites.html
View all available commands:
just
Install uv#
Install uv on your system:
https://docs.astral.sh/uv/getting-started/installation/
Init development environment#
Build faststream image and install all dependencies:
just init
By default, this builds Python 3.11. If you need another version, pass it as an argument to the just command:
just init 3.11.5
To check available Python versions, refer to the pyproject.toml file in the project root.
Run all Dependencies#
Start all dependencies as docker containers:
just up
Once you are done with development and running tests, you can stop the dependencies' docker containers by running:
just stop
# or
just down
Running Tests#
To run fast tests, use:
just test
To run all tests with brokers connections, use:
just test-all
To run tests with coverage:
just test-coverage
# or
just test-coverage-all
just test tests/brokers/kafka
# or
just test-all tests/brokers/kafka
# or
just coverage-test tests/brokers/kafka
If you need some pytest arguments:
just test -vv
# or
just test tests/brokers/kafka -vv
# or
just test "-vv -s"
Pytest Marks Usage Rules#
Broker-specific marks#
Use these marks for tests that interact with specific message brokers.
- kafka: Apply to tests that interact with a Kafka broker using aiokafka.
- confluent: Apply to tests using Confluent Kafka client (confluent-kafka package).
- rabbit: For tests with RabbitMQ broker (aio-pika).
- redis: For Redis broker tests (redis package).
- nats: For NATS broker tests (nats-py).
To mark tests that require a real broker connection, use the connected mark. These tests are excluded by default to allow fast testing without external dependencies.
So, the tests that require a real RabbitMQ connection should be look like this:
@pytest.mark.asyncio()
@pytest.mark.connected()
@pytest.mark.rabbit()
async def test_rabbit_connection():
pass
Other marks#
- slow: Mark slow-running tests, such as performance benchmarks or complex integration tests. Excluded in default
just testto keep CI fast. - all: Automatically added to all test items. Used internally for running comprehensive test suites.
Skip marks#
Import from tests/marks.py and apply to individual tests or classes to skip under certain conditions:
@skip_windows: Skips tests on Windows OS.@skip_macos: Skips tests on macOS.@pydantic_v1: Runs only if Pydantic v1 is installed (skips on v2).@pydantic_v2: Runs only if Pydantic v2 is installed (skips on v1).@require_confluent: Skips ifconfluent-kafkais not installed.@require_aiokafka: Skips ifaiokafkais not installed (for standard Kafka).@require_aiopika: Skips ifaio-pikais not installed (RabbitMQ).@require_redis: Skips ifredisis not installed.@require_nats: Skips ifnats-pyis not installed.
When writing new tests, always mark them appropriately with broker-specific marks if they require external services, and use skip marks for conditional execution.
By default, just test will execute not slow and not connected tests. just test-all will execute all tests. You can specify marks to include or exclude tests:
just test tests/ -vv "not kafka and not rabbit"
# or
just test . -vv "not kafka and not rabbit"
# or if you no need pytest arguments
just test . "" "not kafka and not rabbit"
Linter#
Run all linters:
just linter
To use specific command
just ruff-check
# or
just ruff-format
Static analysis#
To run mypy, please use the following command.
just mypy
Pre-commit#
Run pre-commit:
just pre-commit
# or
just pre-commit-all
Documentation#
For detailed instructions on building and serving the documentation, please refer to the documentation contribution guide.
Opening a pull request#
- One pull request, one change. Unrelated fixes — a typo you spotted, a lint failure in another module, a dependency bump — belong in their own pull request. They are welcome; they just do not travel with a feature. An unrelated change makes the diff harder to review and ties a trivial fix to a long discussion.
uv.lockfollowspyproject.toml. A pull request that changes dependencies runsuv lockand commits the result; CI fails on a lock that is out of sync. A pull request that does not touch dependencies leavesuv.lockalone.- The CLA is signed before review starts. We do not spend a review round on a contribution we cannot merge.
- Discussion happens in the pull request, not in a private message. A decision made in a chat is invisible to the next contributor who hits the same question — and to us, six months later.
- A design question with no consequence for the merge does not block it. If it can be answered afterwards, we merge and answer afterwards.
When a maintainer edits your branch#
Maintainers sometimes push directly to a pull request branch instead of asking for another round. When that happens you are owed two things:
- a comment listing what was changed and which parts were the maintainer's own preference rather than a project requirement;
- a warning before any force-push, so your local branch does not diverge silently.
A maintainer changing behaviour in your branch follows the same rules as you do: the change is explained in the pull request and comes with a test. A silent behaviour change relies on one person noticing it, which is not something the project can repeat.
If a change was made on top of your work without an explanation, ask — the explanation is the part that makes the next contribution easier, and it is our job to provide it.
Commits#
Please, use Conventional Commits to name your commits and PR's.
- build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
- ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
- docs: Documentation only changes
- feat: A new feature
- fix: A bug fix
- perf: A code change that improves performance
- refactor: A code change that neither fixes a bug nor adds a feature
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- test: Adding missing tests or correcting existing tests
- chore Miscellaneous commits e.g. modifying .gitignore, ...