القائمة
Use when writing or modifying FastStream library source code under faststream/ — package layout, broker package anatomy, typing rules, configs, and public API conventions.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when writing or editing documentation under docs/ — page layout, docs_src snippet embedding, snippet tests, link conventions, and FastStream example-code rules.
Use when setting up the FastStream dev environment, running tests/linters/static analysis, managing docker brokers, or preparing a PR.
Use when writing or modifying tests under tests/ — base testcase inheritance, pytest markers, fixtures, in-memory vs real-broker testing, and how to run the suite.
| name | code-architecture |
| description | Use when writing or modifying FastStream library source code under faststream/ — package layout, broker package anatomy, typing rules, configs, and public API conventions. |
faststream/_internal/ holds shared machinery: broker/ (abstract BrokerUsecase, registrator, router), endpoint/, di/ (fast-depends integration), context/, configs/, logger/, testing/, cli/, fastapi/, utils/.faststream/kafka/, rabbit/, nats/, redis/, confluent/, mqtt/) are thin public layers over _internal.faststream/middlewares/, params/, response/, specification/, message/, asgi/, opentelemetry/, prometheus/.Rule: implement shared behavior in _internal/, expose it through broker packages. User-facing code (docs, examples, error messages) must never import from faststream._internal.
Every broker package mirrors the same layout. Canonical reference: faststream/kafka/.
faststream/<broker>/
├── __init__.py # public exports with explicit __all__
├── annotations.py # broker-specific Annotated type aliases
├── broker/ # broker.py (BrokerUsecase subclass), router.py, registrator.py, logging.py
├── configs/ # @dataclass(kw_only=True) configs inheriting BrokerConfig
├── message.py # StreamMessage subclass
├── parser.py # message parser
├── publisher/ # publisher endpoint + producer.py
├── subscriber/ # subscriber endpoint (usecase.py; nats/redis split into usecases/)
├── response.py # PublishCommand subclasses
├── security.py # auth/security helpers
├── testing.py # in-memory TestBroker
└── exceptions.py # broker-specific exceptions
Brokers also carry optional integration subpackages where supported — kafka has fastapi/, helpers/, opentelemetry/, prometheus/, and schemas/ — follow kafka's structure when adding these to another broker.
All brokers expose the same surface: publish(), request(), ping(), start(), stop(), routers, publishers, message/response types. When adding a feature:
_internal/.strict = true (see [tool.mypy] in pyproject.toml): every function fully annotated, no implicit Optional, decorators typed. Checked paths: faststream/ and tests/mypy/.BrokerUsecase[MsgType, ConnectionType, BrokerConfigType] (see faststream/_internal/broker/broker.py), BaseMiddleware[PublishCommandType, AnyMsg].Callable, Awaitable, Sequence, Mapping from collections.abc; newer typing features (Self, ParamSpec, TypedDict, ...) from typing_extensions.TypedDict (e.g. KafkaInitKwargs in faststream/kafka/broker/broker.py).faststream/_internal/_compat.py — never inline version checks elsewhere.Config classes are @dataclass(kw_only=True) inheriting BrokerConfig (base in faststream/_internal/configs/). Example: faststream/kafka/configs/broker.py.
__init__.py declares __all__ explicitly.ImportError that tells the user which extra to install — see faststream/kafka/__init__.py.select = ["ALL"] with curated ignores in ruff.toml — don't assume a rule is disabled; run just linter to check.just mypy must pass before a PR.