Skip to content

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
If you need test only specific folder or broker:

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 test to 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 if confluent-kafka is not installed.
  • @require_aiokafka: Skips if aiokafka is not installed (for standard Kafka).
  • @require_aiopika: Skips if aio-pika is not installed (RabbitMQ).
  • @require_redis: Skips if redis is not installed.
  • @require_nats: Skips if nats-py is 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
This command run ruff check, ruff format.

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.lock follows pyproject.toml. A pull request that changes dependencies runs uv lock and commits the result; CI fails on a lock that is out of sync. A pull request that does not touch dependencies leaves uv.lock alone.
  • 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, ...