Upgrading

Upgrading to 2.0.0

message_retry_sec has been removed

message_retry_sec was previously deprecated and ignored. In 2.0.0, it has been removed from Gourd(...).

Before:

app = Gourd(app_name='my_app', message_retry_sec=10)

After:

app = Gourd(app_name='my_app')

message.json now returns None on failure instead of {}

Previously, message.json returned an empty dict {} when the payload could not be decoded or was not a JSON object. It now returns None.

Code that distinguishes a failed parse from a successfully parsed empty-ish result should be updated. Code that simply uses if message.json: as a truthy check will continue to work unchanged, since both None and {} are falsy.

Before — guarded by truthiness (still works):

@app.subscribe('sensors/#')
def handle(message):
    if message.json:
        temp = message.json.get('celsius')

Before — explicit empty-dict check (must update):

@app.subscribe('sensors/#')
def handle(message):
    if message.json != {}:
        temp = message.json.get('celsius')

After — check against None if an explicit check is needed:

@app.subscribe('sensors/#')
def handle(message):
    if message.json is not None:
        temp = message.json.get('celsius')

message.payload now preserves the original MQTT payload

In previous releases, message.payload was decoded as UTF-8 text and stripped. In 2.0.0, message.payload preserves the original payload from paho-mqtt unchanged, which is typically bytes.

Use message.text when you want UTF-8 decoded text. This keeps binary payloads available without losing the original bytes.

Before:

@app.subscribe('sensors/#')
def handle_sensor(message):
    app.log.info(f'{message.topic}: {message.payload}')

After — use message.text for decoded text payloads:

@app.subscribe('sensors/#')
def handle_sensor(message):
    app.log.info(f'{message.topic}: {message.text}')

Invalid MQTT wildcard filters now raise ValueError

mqtt_wildcard() now validates wildcard patterns. Invalid filters (for example foo# or foo/#/bar) raise ValueError instead of being treated as loose string patterns.

If you register subscriptions dynamically, validate/correct malformed filters before registering them.

gourd CLI now applies config/env overrides for MQTT settings

The CLI now supports applying command-line and environment-driven overrides for connection/auth/QoS/status/logging/TLS settings.

If you run via gourd module:app, existing environment variables or CLI flags can now change runtime behavior that was previously controlled only in Python code.

TLS can auto-enable when certificate paths are provided

If TLS certificate paths are configured (tls_ca_certs, tls_certfile, tls_keyfile), TLS is automatically enabled unless explicitly disabled.

Set tls_enabled=False explicitly if you provide certificate paths but do not want TLS enabled.

Upgrading to 1.0.0

paho-mqtt upgraded from v1 to v2

Gourd 1.0.0 requires paho-mqtt>=2. If you are upgrading from an earlier version of Gourd, update paho-mqtt:

pip install --upgrade paho-mqtt

message_retry_sec is deprecated

The message_retry_sec argument to Gourd() is no longer functional. paho-mqtt v2 removed the underlying message_retry_set() API. Passing this argument now emits a DeprecationWarning and has no effect. It will be removed in a future release.

Before:

app = Gourd(app_name='my_app', message_retry_sec=10)

After — remove the argument:

app = Gourd(app_name='my_app')