Metadata-Version: 2.4
Name: faststream-mq
Version: 0.2.0
Summary: Standalone IBM MQ adapter for FastStream
Keywords: faststream,ibm-mq,mq,message-broker,asyncapi
Author: David Zuckerman
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pydantic
Classifier: Typing :: Typed
Classifier: Topic :: System :: Distributed Computing
Requires-Dist: faststream>=0.7.0rc1,<0.8
Requires-Dist: ibmmq>=2,<3 ; (platform_machine == 'AMD64' and sys_platform == 'linux') or (platform_machine == 'amd64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux') or (platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'amd64' and sys_platform == 'win32') or (platform_machine == 'x86_64' and sys_platform == 'win32')
Requires-Dist: cryptography>=46,<47
Requires-Dist: fastapi>=0.128.0 ; extra == 'all'
Requires-Dist: starlette ; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.24.0,<2.0.0 ; extra == 'all'
Requires-Dist: prometheus-client>=0.20.0,<0.30.0 ; extra == 'all'
Requires-Dist: fastapi>=0.128.0 ; extra == 'fastapi'
Requires-Dist: starlette ; extra == 'fastapi'
Requires-Dist: opentelemetry-sdk>=1.24.0,<2.0.0 ; extra == 'otel'
Requires-Dist: prometheus-client>=0.20.0,<0.30.0 ; extra == 'prometheus'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/davzucky/faststream-mq
Project-URL: Source, https://github.com/davzucky/faststream-mq
Project-URL: Tracker, https://github.com/davzucky/faststream-mq/issues
Provides-Extra: all
Provides-Extra: fastapi
Provides-Extra: otel
Provides-Extra: prometheus
Description-Content-Type: text/markdown

# faststream-mq

[![CI](https://github.com/davzucky/faststream-mq/actions/workflows/ci.yml/badge.svg)](https://github.com/davzucky/faststream-mq/actions/workflows/ci.yml)
[![Connected IBM MQ tests](https://github.com/davzucky/faststream-mq/actions/workflows/integration.yml/badge.svg)](https://github.com/davzucky/faststream-mq/actions/workflows/integration.yml)
[![Docs](https://readthedocs.org/projects/faststream-mq/badge/?version=latest)](https://faststream-mq.readthedocs.io/en/latest/)
[![PyPI](https://img.shields.io/pypi/v/faststream-mq.svg)](https://pypi.org/project/faststream-mq/)
[![Python versions](https://img.shields.io/pypi/pyversions/faststream-mq.svg)](https://pypi.org/project/faststream-mq/)

Standalone IBM MQ adapter for [FastStream](https://github.com/ag2ai/faststream).

`faststream-mq` is an early standalone adapter extracted from pending FastStream IBM MQ work. It is already used in production, but still tracks upstream FastStream work closely. If equivalent IBM MQ support is accepted upstream, this package will be deprecated in favor of upstream FastStream.

## Install

```bash
pip install faststream-mq
```

Real IBM MQ connections require IBM MQ native C client libraries. For IBM MQ 9.4 redistributable clients, native runtime support is available on Linux x86-64 and Windows x64. The package remains installable on other platforms so `TestMQBroker` and non-connected tests can run without native MQ libraries.

Optional integrations:

```bash
pip install "faststream-mq[fastapi]"
pip install "faststream-mq[otel]"
pip install "faststream-mq[prometheus]"
pip install "faststream-mq[all]"
```

## Quick start

```python
from faststream import FastStream
from faststream_mq import MQBroker

broker = MQBroker(queue_manager="QM1")
app = FastStream(broker)


@broker.subscriber("DEV.QUEUE.1")
async def handle(message: str) -> None:
    print(message)
```

Run a local IBM MQ broker with Docker Compose:

```bash
docker compose up -d ibmmq
```

## Migration from the pending FastStream PR

The standalone adapter intentionally uses `faststream_mq` as its canonical import package.

```python
# Before
from faststream.mq import MQBroker, TestMQBroker

# After
from faststream_mq import MQBroker, TestMQBroker
```

There is intentionally no `faststream.mq` compatibility shim. A standalone package cannot safely inject a submodule into the non-namespace `faststream` package. See the [migration guide](https://faststream-mq.readthedocs.io/en/latest/migration/) for project migration details.

## Development

This repository uses `uv`, `uv_build`, `ruff`, `ty`, and `prek`.

Install the IBM MQ client SDK first when you need real MQ runtime support on a Supported MQ Client Platform; the `ibmmq` Python package needs the MQ C headers to build. See the [IBM MQ Client SDK docs](https://faststream-mq.readthedocs.io/en/latest/mq-client-sdk/) for details and troubleshooting.

```bash
MQ_FILE_PATH="$HOME/.local/opt/mqm" ./scripts/install-mq-client.sh
export MQ_FILE_PATH="$HOME/.local/opt/mqm"
export LD_LIBRARY_PATH="$MQ_FILE_PATH/lib64:$LD_LIBRARY_PATH"

uv sync --all-extras --group dev
uv run prek install
uv run ruff format
uv run ruff check
./scripts/ty-check.sh
uv run pytest
uv run --only-group docs mkdocs build --strict
```

Connected IBM MQ tests require the local MQ services and a successful client-connectivity probe. See the [connected testing docs](https://faststream-mq.readthedocs.io/en/latest/connected-testing/) for details and troubleshooting.

```bash
docker compose up -d ibmmq ibmmq_ha2
uv run python scripts/wait-mq-ready.py "127.0.0.1(1414)" "127.0.0.1(1415)"
uv run pytest -m connected
```

## Documentation

Documentation is built with MkDocs using the `docs` uv dependency group.
Read the Docs can build the site from `.readthedocs.yaml` without a separate `requirements.txt`.

```bash
uv sync --only-group docs
uv run --only-group docs mkdocs serve
```

## Release

Releases are published from version tags by GitHub Actions using PyPI Trusted Publishing. The release workflow also creates a GitHub Release and attaches the built package artifacts. See the [release checklist](https://faststream-mq.readthedocs.io/en/latest/release-checklist/).

```bash
git tag v0.1.0
git push origin v0.1.0
```

## License and attribution

Apache-2.0. This package is extracted from IBM MQ broker work originally written for FastStream and preserves the FastStream upstream attribution and API style where appropriate.
