gmqtt: Python async MQTT client implementation.
Installation
The latest stable version is available in the Python Package Index (PyPi) and can be installed using
pip3 install gmqtt
Usage
Getting Started
Here is a very simple example that subscribes to the broker TOPIC topic and prints out the resulting messages:
import asyncio
import os
import signal
import time
from gmqtt import Client as MQTTClient
# gmqtt also compatibility with uvloop
import uvloop
asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
STOP = asyncio.Event()
def on_connect(client, flags, rc, properties):
print('Connected')
client.subscribe('TEST/#', qos=0)
def on_message(client, topic, payload, qos, properties):
print('RECV MSG:', payload)
def on_disconnect(client, packet, exc=None):
print('Disconnected')
def on_subscribe(client, mid, qos, properties):
print('SUBSCRIBED')
def ask_exit(*args):
STOP.set()
async def main(broker_host, token):
client = MQTTClient("client-id")
client.on_connect = on_connect
client.on_message = on_message
client.on_disconnect = on_disconnect
client.on_subscribe = on_subscribe
client.set_auth_credentials(token, None)
await client.connect(broker_host)
client.publish('TEST/TIME', str(time.time()), qos=1)
await STOP.wait()
await client.disconnect()
if __name__ == '__main__':
loop = asyncio.get_event_loop()
host = 'mqtt.flespi.io'
token = os.environ.get('FLESPI_TOKEN')
loop.add_signal_handler(signal.SIGINT, ask_exit)
loop.add_signal_handler(signal.SIGTERM, ask_exit)
loop.run_until_complete(main(host, token))
MQTT Version 5.0
gmqtt supports MQTT version 5.0 protocol
Version setup
Version 5.0 is used by default. If your broker does not support 5.0 protocol version and responds with proper CONNACK reason code, client will downgrade to 3.1 and reconnect automatically. Note, that some brokers just fail to parse the 5.0 format CONNECT packet, so first check manually if your broker handles this properly. You can also force version in connect method:
from gmqtt.mqtt.constants import MQTTv311
client = MQTTClient('clientid')
client.set_auth_credentials(token, None)
await client.connect(broker_host, 1883, keepalive=60, version=MQTTv311)
Properties
MQTT 5.0 protocol allows to include custom properties into packages, here is example of passing response topic property in published message:
TOPIC = 'testtopic/TOPIC'
def on_connect(client, flags, rc, properties):
client.subscribe(TOPIC, qos=1)
print('Connected')
def on_message(client, topic, payload, qos, properties):
print('RECV MSG:', topic, payload.decode(), properties)
async def main(broker_host, token):
client = MQTTClient('asdfghjk')
client.on_message = on_message
client.on_connect = on_connect
client.set_auth_credentials(token, None)
await client.connect(broker_host, 1883, keepalive=60)
client.publish(TOPIC, 'Message payload', response_topic='RESPONSE/TOPIC')
await STOP.wait()
await client.disconnect()
Connect properties
Connect properties are passed to Client object as kwargs (later they are stored together with properties received from broker in client.properties field). See example below.
session_expiry_interval-intSession expiry interval in seconds. If the Session Expiry Interval is absent the value 0 is used. If it is set to 0, or is absent, the Session ends when the Network Connection is closed. If the Session Expiry Interval is 0xFFFFFFFF (max possible value), the Session does not expire.receive_maximum-intThe Client uses this value to limit the number of QoS 1 and QoS 2 publications that it is willing to process concurrently.user_property-tuple(str, str)This property may be used to provide additional diagnostic or other information (key-value pairs).maximum_packet_size-intThe Client uses the Maximum Packet Size (in bytes) to inform the Server that it will not process packets exceeding this limit.
Example:
client = gmqtt.Client("lenkaklient", receive_maximum=24000, session_expiry_interval=60, user_property=('myid', '12345'))
Publish properties
This properties will be also sent in publish packet from broker, they will be passed to on_message callback.
message_expiry_interval-intIf present, the value is the lifetime of the Application Message in seconds.content_type-unicodeUTF-8 Encoded String describing the content of the Application Message. The value of the Content Type is defined by the sending and receiving application.user_property-tuple(str, str)subscription_identifier-int(see subscribe properties) sent by brokertopic_alias-intFirst client publishes messages with topic string and kwarg topic_alias. After this initial message client can publish message with empty string topic and same topic_alias kwarg.
Example:
def on_message(client, topic, payload, qos, properties):
# properties example here: {'content_type': ['json'], 'user_property': [('timestamp', '1524235334.881058')], 'message_expiry_interval': [60], 'subscription_identifier': [42, 64]}
print('RECV MSG:', topic, payload, properties)
client.publish('TEST/TIME', str(time.time()), qos=1, retain=True, message_expiry_interval=60, content_type='json')
Subscribe properties
subscription_identifier-intIf the Client specified a Subscription Identifier for any of the overlapping subscriptions the Server MUST send those Subscription Identifiers in the message which is published as the result of the subscriptions.
Reconnects
By default, connected MQTT client will always try to reconnect in case of lost connections. Number of reconnect attempts is unlimited. If you want to change this behaviour, do the following:
client = MQTTClient("client-id")
client.set_config({'reconnect_retries': 10, 'reconnect_delay': 60})
Code above will set number of reconnect attempts to 10 and delay between reconnect attempts to 1min (60s). By default reconnect_delay=6 and reconnect_retries=-1 which stands for infinity.
The first reconnect after a lost connection waits reconnect_delay; after each failed attempt in a row (refusal, network error, ...)
the delay doubles (starting from 1s if reconnect_delay is 0), up to reconnect_delay_max (300s by default):
client.set_config({'reconnect_delay_max': 120})
Note that manually calling await client.disconnect() will set reconnect_retries for 0, which will stop auto reconnect.
A refusal that retrying cannot fix (bad credentials, banned client, ...) stops the reconnects; client.permanently_refused
then turns True and client.connect_error holds the refusal.
Rotating credentials
If credentials expire (e.g. tokens), pass a credentials_provider. gmqtt awaits it before every connect and reconnect,
and uses what it returns instead of the credentials set with set_auth_credentials:
async def credentials(client, error):
# error: the refusal (MQTTConnectError) since the provider was last called,
# None otherwise (e.g. after a plain connection loss)
if error is not None and error.code in (134, 135): # bad user name or password, not authorized
await issuer.refresh()
return issuer.token, None
client = MQTTClient("client-id", credentials_provider=credentials)
With a provider, auto-reconnect retries auth refusals (134/135, 4/5 on MQTT 3.1.1), as new credentials may succeed.
An explicit await client.connect(...) still raises them, leaving the retry to the caller.
Other permanent refusals still stop the reconnects, since new credentials cannot fix them.
Asynchronous on_message callback
You can define asynchronous on_message callback.
Note that it must return valid PUBACK code (0 is success code, see full list in constants)
async def on_message(client, topic, payload, qos, properties):
pass
return 0
Other examples
Check examples directory for more use cases.
Metadata
Release files for gmqtt 0.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gmqtt-0.9.0.tar.gz | 53.5 kB | Without provenance | Details for gmqtt-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gmqtt-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for gmqtt-0.9.0-py3-none-any.whl |
Total release size: 93.9 kB
Release files / gmqtt-0.9.0.tar.gz
| Download URL | gmqtt-0.9.0.tar.gz |
|---|---|
| Size | 53.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
970919a29058a12db3f218a9b5ee81124e02a92882d696ba9d85078e74e1f72a
|
|
BLAKE2b-256 checksum How to use checksums |
8eb9e057074deb69a775a1dfbdb621e75cb1b20e1ee01ebd82b7f1d649d1d3c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / gmqtt-0.9.0-py3-none-any.whl
| Download URL | gmqtt-0.9.0-py3-none-any.whl |
|---|---|
| Size | 40.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6a083c5eddbe3f2f3e3ef6c4b9de15b4a34bc93dce1abc864d1f1e2a1fb1e398
|
|
BLAKE2b-256 checksum How to use checksums |
6e667a26e1d430b6c8f7ae46c2ce01ee04181b0f09049f79f4c84605d887bf52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for gmqtt 0.9.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.