Skip to main content

rocketmq3-py-client

Python3 RocketMQ 3.x 客户端库,基于 JPype 桥接 RocketMQ Java 客户端。仅支持 RocketMQ 3.x 老集群;4.x 及以后请使用官方 rocketmq-client-python。

特性

  • 三种发送模式:同步、异步、单向(策略模式)
  • 两种消费模式:Pull(主动拉取)、Push(被动推送 / 观察者模式)
  • 上下文管理器:所有客户端支持 with 语句,自动释放资源
  • 重试机制:发送失败自动重试,可配置次数和退避策略
  • 线程安全:JVM 单例 + 线程锁
  • 完整异常体系:Java 异常自动翻译为 Python 异常
  • 配置驱动:通过 ClientConfig 统一管理参数
  • 消息建造者:链式 API 构建消息

环境要求

  • Python 3.8 ~ 3.12(已放弃 3.13 / 3.14 支持,换取 JDK 8 兼容性)
  • JDK 8+(默认依赖 JPype1 1.5.x,官方支持 Java 8;JDK 11+ 亦可向后兼容运行)
  • JPype1 >= 1.5.0, < 1.6.0(最后支持 Java 8 的版本线;自带 macOS universal2 预编译包,含 arm64,Apple Silicon 免源码编译)
  • RocketMQ 3.2.6 JAR 包(获取方式见下方「获取 RocketMQ Java 客户端」)

💡 本库默认兼容 JDK 8:只要本机 JAVA_HOME 指向 JDK 8(或任意 8+),无需特殊处理即可启动。若需强制指定某个 JDK,仍可用 java_home:

config = ClientConfig(namesrv_addr="...", java_home="/Library/Java/JavaVirtualMachines/jdk1.8.0_xxx.jdk/Contents/Home")

⚠️ 注意:JPype1 1.6.0+ 不再支持 Java 8(要求 11+)。如切换到 1.6.0+,须将 JAVA_HOME 指向 JDK 11+,且 Python 上限为 3.12(本库已锁定 1.5.x,因此保持 JDK 8 兼容)。

获取 RocketMQ 3.2.6 Java 客户端

本库通过 JPype 桥接 RocketMQ 3.2.6 的 Java 客户端,但不自带 JAR 包,需自行准备并放到 ROCKETMQ_LIB_PATH(默认 /opt/rocketmq3/lib),运行时会自动加载该目录下所有 JAR。

⚠️ RocketMQ 3.x 使用旧的 com.alibaba.rocketmq 命名空间(不是 4.x+ 的 org.apache.rocketmq),坐标与官方新版完全不同。

Maven 坐标(Maven Central)

<dependency>
    <groupId>com.alibaba.rocketmq</groupId>
    <artifactId>rocketmq-client</artifactId>
    <version>3.2.6</version>
</dependency>

Maven 仓库地址:

  • Maven Central:https://repo1.maven.org/maven2/com/alibaba/rocketmq/rocketmq-client/3.2.6/
  • 检索页:https://mvnrepository.com/artifact/com.alibaba.rocketmq/rocketmq-client/3.2.6

一键拉取全部依赖 JAR

建一个临时 pom.xml,用 maven-dependency-plugin 把所有传递依赖收集到 target/lib:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>tmp</groupId>
  <artifactId>rmq-libs</artifactId>
  <version>1.0</version>
  <dependencies>
    <dependency>
      <groupId>com.alibaba.rocketmq</groupId>
      <artifactId>rocketmq-client</artifactId>
      <version>3.2.6</version>
    </dependency>
  </dependencies>
</project>
mvn dependency:copy-dependencies -DoutputDirectory=target/lib
sudo cp target/lib/*.jar /opt/rocketmq3/lib/   # 复制到默认加载目录

自定义 JAR 目录

若不放默认路径,用环境变量指定:

export ROCKETMQ_LIB_PATH=/path/to/your/rocketmq3/lib

安装

pip install rocketmq3-py-client
# 或开发模式
pip install -r requirements.txt
pip install -e .

快速开始

生产者

from rocketmq3_py_client import Producer

with Producer("my_group", "127.0.0.1:9876") as producer:
    result = producer.send("topic", b'{"id": 1}', tags="tag_a", keys="key_1")
    print(result)

Push 消费者

from rocketmq3_py_client import PushConsumer

consumer = PushConsumer("cg", "127.0.0.1:9876", "topic")

@consumer.register_handler
def handle(messages):
    for msg in messages:
        print(msg.msg_id, msg.body)
    return True

consumer.start()

Pull 消费者

from rocketmq3_py_client import PullConsumer

with PullConsumer("cg", "127.0.0.1:9876") as consumer:
    queues = consumer.fetch_message_queues("topic")
    for q in queues:
        result = consumer.pull(q, offset=0, max_nums=32)
        for msg in result.messages:
            print(msg.msg_id, msg.body)

Metadata

Release files for rocketmq3-py-client 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rocketmq3-py-client 0.2.0
File Size Uploaded Provenance Actions
rocketmq3_py_client-0.2.0.tar.gz 25.2 kB With provenance Details for rocketmq3_py_client-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rocketmq3-py-client 0.2.0
File Interpreter ABI Platform Actions
rocketmq3_py_client-0.2.0-py3-none-any.whl Python 3 none any Details for rocketmq3_py_client-0.2.0-py3-none-any.whl

Total release size: 52.1 kB

Release files / rocketmq3_py_client-0.2.0.tar.gz

Download URL rocketmq3_py_client-0.2.0.tar.gz
Size 25.2 kB
Tags Source
SHA-256 checksum
How to use checksums
99f05ee0fcab51930ed66cf84f46a06298baca22f0f35f457dcaa87b12b3fa7f
BLAKE2b-256 checksum
How to use checksums
ced75feb9a8a141690316ef1324b937551746a2ee09095619edbe1b1608be3e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 8, 2026.

Transparency log

Release files / rocketmq3_py_client-0.2.0-py3-none-any.whl

Download URL rocketmq3_py_client-0.2.0-py3-none-any.whl
Size 27.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a86b104475114f8426e5cbc4854c089524fd717698d5536225c93914db7b7849
BLAKE2b-256 checksum
How to use checksums
0d33559608a8302630ab937e2358e8c021a80f004a708f1dd4eeaf52df240b08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 8, 2026.

Transparency log

Security for rocketmq3-py-client 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rocketmq3_py_client-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page