| Name | SwampClient JSON |
| Version |
0.0.9
JSON |
| download |
| home_page | None |
| Summary | An MQTT client library built as a wrapper around Paho MQTT, configurable via environment variables, supporting JSONata transformations and timestamp handling through Zeitgleich. |
| upload_time | 2025-02-03 13:37:44 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | None |
| keywords |
asyncio
client
jsonata
mqtt
time series
timestamp
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SwampClient
**SwampClient** is an MQTT client library built as a wrapper around the [Paho MQTT](https://www.eclipse.org/paho/) library. It is configureable using environment variables and integrates timestamp handling through the [Zeitgleich](https://pypi.org/project/Zeitgleich/) library. SwampClient supports managing multiple MQTT clients simultaneously and provides functionalities for message transformation and timestamp management within MQTT-based applications.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Environment Variables](#environment-variables)
- [Usage and Examples](#usage-and-examples)
- [Basic Example](#basic-example)
- [Bridge Example](#bridge-example)
- [Publish Example](#publish-example)
- [Data Formats](#data-formats)
- [TODOs](#todos)
- [License](#license)
## Features
- **Environment Variable Configuration:** Configure multiple MQTT clients using prefixed environment variables.
- **JSONata Transformations:** Apply JSONata expressions to transform MQTT message payloads.
- **Timestamp Handling:** Integrate with Zeitgleich for timestamp parsing, conversion, and validation.
- **Multiple Transport Protocols:** Supports MQTT over TCP, TLS, WebSockets, and Secure WebSockets.
- **Subscription Management:** Subscribe to multiple topics with configurable QoS levels.
- **Asynchronous Operations:** Utilize `asyncio` for non-blocking MQTT operations and concurrent tasks.
- **Logging:** Configurable log levels for monitoring and debugging.
- **Graceful Shutdown:** Ensure proper disconnection from MQTT brokers on application exit.
## Installation
Install SwampClient using `pip`:
```bash
pip install SwampClient
```
Ensure you also have the required dependencies installed:
```bash
pip install -r requirements.txt
```
## Configuration
SwampClient is configured through environment variables, allowing for easy management of multiple MQTT clients by using unique prefixes.
### Environment Variables
**Note:** All environment variable names are prefixed with the client name (e.g., `MQTTCLIENT1_`) to support multiple clients simultaneously.
| Environment Variable | Description | Default Value | Tested |
|------------------------------|---------------------------------------------------------------------------------------------------------------|------------------------|--------|
| `[PREFIX]_URL` | **MQTT Broker URL.** Connection string, including the protocol. Supported schemes: `mqtt`, `mqtts`, `ws`, `wss`. | `mqtt://localhost:1883`| ✅ |
| `[PREFIX]_USERNAME` | **MQTT Username.** Username for MQTT broker authentication. | *None* | ❌ |
| `[PREFIX]_PASSWORD` | **MQTT Password.** Password for MQTT broker authentication. | *None* | ❌ |
| `[PREFIX]_TOPICS` | **MQTT Topics.** Comma-separated list of topics to subscribe to, each followed by `:qos`. Example: `topic1:0,topic2:1`. | *Empty String* | ✅ |
| `[PREFIX]_JSONATA` | **JSONata Expression Path.** Path to a JSONata expression file for transforming MQTT message payloads. | *Empty String* | ✅ |
| `[PREFIX]_TOPIC2PAYLOAD` | **Topic to Payload Key.** Key name to inject the topic into the payload. | *Empty String* | ❌ |
| `[PREFIX]_LOG_LEVEL` | **Log Level.** Sets the logging level for the client. Options: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. | `DEBUG` | ✅ |
| `[PREFIX]_RAW_DATA_HANDLING` | **Raw Data Handling.** Defines how to handle non-JSON payloads. Options: `wrap`, `pass_through`, `timeseries`. | `wrap` | ❌ |
| `[PREFIX]_RAW_DATA_KEY` | **Raw Data Key.** Key name used when wrapping raw data. Applicable if `RAW_DATA_HANDLING` is set to `wrap`. | `raw_data` | ✅ |
| `[PREFIX]_SPLIT_PAYLOAD` | **Split Payload Expression.** JSONata expression to split payloads into multiple messages. | *None* | ❌ |
| `[PREFIX]_TIMESTAMP` | **Timestamp Key.** Key name in the payload that contains the timestamp. | `timestamp` | ✅ |
| `[PREFIX]_TIMESTAMP_FROM` | **Input Timestamp Format.** Format of the incoming timestamp. Options: `RFC3339`, `UNIX`, `ISO`, `EPOCH_S`, `EPOCH_NS`. | `EPOCH_S` | ✅ |
| `[PREFIX]_TIMESTAMP_TO` | **Output Timestamp Format.** Desired format for the timestamp in outgoing messages. Options: `RFC3339`, `UNIX`, `ISO`, `EPOCH_S`, `EPOCH_NS`. | `RFC3339` | ✅ |
#### Example `.env` Configuration
```dotenv
# Example for MQTTCLIENT1
MQTTCLIENT1_URL="mqtt://localhost:1884"
MQTTCLIENT1_LOG_LEVEL="DEBUG"
# Example for MQTTCLIENT2
MQTTCLIENT2_URL="wss://broker.example.com:443"
MQTTCLIENT2_LOG_LEVEL="INFO"
```
## Usage and Examples
SwampClient provides interfaces to interact with MQTT brokers. Below are examples demonstrating different use cases, including initializing clients, subscribing to topics, handling incoming messages, and publishing messages.
### Basic Example
The **Basic Example** demonstrates initializing a single MQTT client, subscribing to topics, and handling incoming messages.
#### Running the Basic Example
1. **Set Up Environment Variables:**
Ensure your `.env` file includes the necessary configurations for `MQTTCLIENT1`.
2. **Run the Example:**
```bash
python swamp_mqtt_client/examples/basic.py
```
**Functionality:**
- Connects to the specified MQTT broker.
- Subscribes to `test/topic` with QoS 0 and `test/topic2` with QoS 1.
- Logs received messages on subscribed topics.
- Handles graceful shutdown on receiving `KeyboardInterrupt`.
### Bridge Example
The **Bridge Example** shows how to bridge messages between two MQTT brokers. It subscribes to topics on a source broker and republishes messages to a target broker.
#### Running the Bridge Example
1. **Set Up Environment Variables:**
Ensure your `.env` file includes the necessary configurations for both `SUBSCRIBE_CLIENT` and `PUBLISH_CLIENT`.
2. **Run the Example:**
```bash
python swamp_mqtt_client/examples/bridge/bridge.py
```
**Functionality:**
- Subscribes to `source/topic` with QoS 0 and `source/topic2` with QoS 1 on the source broker.
- Transforms incoming messages using the specified JSONata expression.
- Republishes the transformed messages to `target/topic` on the target broker.
- Handles graceful shutdown on receiving termination signals (`SIGINT`, `SIGTERM`).
### Publish Example
The **Publish Example** illustrates how to publish messages based on keyboard input to an MQTT topic.
#### Running the Publish Example
1. **Set Up Environment Variables:**
Ensure your `.env` file includes the necessary configurations for `MQTTCLIENT1`.
2. **Run the Example:**
```bash
python swamp_mqtt_client/examples/publish/publish.py
```
**Functionality:**
- Connects to the specified MQTT broker.
- Listens for keyboard inputs and publishes each key press to the `keyboard/keys` topic.
- Stops publishing and disconnects gracefully when the user types `exit` or interrupts the program.
## Data Formats
SwampClient uses the **Zeitgleich** library for timestamp handling. For detailed information on timestamp normalization and conversion, refer to the [Zeitgleich documentation](https://pypi.org/project/Zeitgleich/).
## TODOs
- **Unit Tests:**
- Implement unit tests for SwampClient functionalities.
- Test support for `mqtts`, `ws`, `wss` schemes.
- Verify MQTT broker authentication with username and password.
- Test `topic2payload` feature.
- Validate `pass_through` raw data handling.
- Test split payload functionality.
- **Configuration Enhancements:**
- Add configuration options for Bridge mode.
- Implement configuration for retaining messages.
- Make configuration options dependent on each other (e.g., `split_payload` requires `jsonata_expression`).
- **Exception Handling:**
- Wrap certain exceptions in custom exception classes.
- Improve error handling for connection and publishing failures.
- **Documentation:**
- Expand documentation for advanced configurations.
- Provide more examples covering additional features.
- **Code-Level TODOs:**
- Support configuration of all subscription options, not just QoS.
- Use `ts.Origin` for origin handling.
- Test `topic2payload` integration.
- Handle additional payload cases in message processing.
- Wrap disconnect errors in custom exceptions and handle logging appropriately.
## License
Licensed under the [MIT License](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "SwampClient",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "asyncio, client, jsonata, mqtt, time series, timestamp",
"author": null,
"author_email": "Jakob Friedl <jakob.friedl@tuwien.ac.at>",
"download_url": "https://files.pythonhosted.org/packages/3e/15/8a3c794bf871a6b03952e774feb71c7675da9b7e5bc2aaaf88657dcd2a9f/swampclient-0.0.9.tar.gz",
"platform": null,
"description": "# SwampClient\n\n**SwampClient** is an MQTT client library built as a wrapper around the [Paho MQTT](https://www.eclipse.org/paho/) library. It is configureable using environment variables and integrates timestamp handling through the [Zeitgleich](https://pypi.org/project/Zeitgleich/) library. SwampClient supports managing multiple MQTT clients simultaneously and provides functionalities for message transformation and timestamp management within MQTT-based applications.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Configuration](#configuration)\n - [Environment Variables](#environment-variables)\n- [Usage and Examples](#usage-and-examples)\n - [Basic Example](#basic-example)\n - [Bridge Example](#bridge-example)\n - [Publish Example](#publish-example)\n- [Data Formats](#data-formats)\n- [TODOs](#todos)\n- [License](#license)\n\n## Features\n\n- **Environment Variable Configuration:** Configure multiple MQTT clients using prefixed environment variables.\n- **JSONata Transformations:** Apply JSONata expressions to transform MQTT message payloads.\n- **Timestamp Handling:** Integrate with Zeitgleich for timestamp parsing, conversion, and validation.\n- **Multiple Transport Protocols:** Supports MQTT over TCP, TLS, WebSockets, and Secure WebSockets.\n- **Subscription Management:** Subscribe to multiple topics with configurable QoS levels.\n- **Asynchronous Operations:** Utilize `asyncio` for non-blocking MQTT operations and concurrent tasks.\n- **Logging:** Configurable log levels for monitoring and debugging.\n- **Graceful Shutdown:** Ensure proper disconnection from MQTT brokers on application exit.\n\n## Installation\n\nInstall SwampClient using `pip`:\n\n```bash\npip install SwampClient\n```\n\nEnsure you also have the required dependencies installed:\n\n```bash\npip install -r requirements.txt\n```\n\n## Configuration\n\nSwampClient is configured through environment variables, allowing for easy management of multiple MQTT clients by using unique prefixes.\n\n### Environment Variables\n\n**Note:** All environment variable names are prefixed with the client name (e.g., `MQTTCLIENT1_`) to support multiple clients simultaneously.\n\n| Environment Variable | Description | Default Value | Tested |\n|------------------------------|---------------------------------------------------------------------------------------------------------------|------------------------|--------|\n| `[PREFIX]_URL` | **MQTT Broker URL.** Connection string, including the protocol. Supported schemes: `mqtt`, `mqtts`, `ws`, `wss`. | `mqtt://localhost:1883`| \u2705 |\n| `[PREFIX]_USERNAME` | **MQTT Username.** Username for MQTT broker authentication. | *None* | \u274c |\n| `[PREFIX]_PASSWORD` | **MQTT Password.** Password for MQTT broker authentication. | *None* | \u274c |\n| `[PREFIX]_TOPICS` | **MQTT Topics.** Comma-separated list of topics to subscribe to, each followed by `:qos`. Example: `topic1:0,topic2:1`. | *Empty String* | \u2705 |\n| `[PREFIX]_JSONATA` | **JSONata Expression Path.** Path to a JSONata expression file for transforming MQTT message payloads. | *Empty String* | \u2705 |\n| `[PREFIX]_TOPIC2PAYLOAD` | **Topic to Payload Key.** Key name to inject the topic into the payload. | *Empty String* | \u274c |\n| `[PREFIX]_LOG_LEVEL` | **Log Level.** Sets the logging level for the client. Options: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. | `DEBUG` | \u2705 |\n| `[PREFIX]_RAW_DATA_HANDLING` | **Raw Data Handling.** Defines how to handle non-JSON payloads. Options: `wrap`, `pass_through`, `timeseries`. | `wrap` | \u274c |\n| `[PREFIX]_RAW_DATA_KEY` | **Raw Data Key.** Key name used when wrapping raw data. Applicable if `RAW_DATA_HANDLING` is set to `wrap`. | `raw_data` | \u2705 |\n| `[PREFIX]_SPLIT_PAYLOAD` | **Split Payload Expression.** JSONata expression to split payloads into multiple messages. | *None* | \u274c |\n| `[PREFIX]_TIMESTAMP` | **Timestamp Key.** Key name in the payload that contains the timestamp. | `timestamp` | \u2705 |\n| `[PREFIX]_TIMESTAMP_FROM` | **Input Timestamp Format.** Format of the incoming timestamp. Options: `RFC3339`, `UNIX`, `ISO`, `EPOCH_S`, `EPOCH_NS`. | `EPOCH_S` | \u2705 |\n| `[PREFIX]_TIMESTAMP_TO` | **Output Timestamp Format.** Desired format for the timestamp in outgoing messages. Options: `RFC3339`, `UNIX`, `ISO`, `EPOCH_S`, `EPOCH_NS`. | `RFC3339` | \u2705 |\n\n#### Example `.env` Configuration\n\n```dotenv\n# Example for MQTTCLIENT1\nMQTTCLIENT1_URL=\"mqtt://localhost:1884\"\nMQTTCLIENT1_LOG_LEVEL=\"DEBUG\"\n\n# Example for MQTTCLIENT2\nMQTTCLIENT2_URL=\"wss://broker.example.com:443\"\nMQTTCLIENT2_LOG_LEVEL=\"INFO\"\n```\n\n## Usage and Examples\n\nSwampClient provides interfaces to interact with MQTT brokers. Below are examples demonstrating different use cases, including initializing clients, subscribing to topics, handling incoming messages, and publishing messages.\n\n### Basic Example\n\nThe **Basic Example** demonstrates initializing a single MQTT client, subscribing to topics, and handling incoming messages.\n\n#### Running the Basic Example\n\n1. **Set Up Environment Variables:**\n\n Ensure your `.env` file includes the necessary configurations for `MQTTCLIENT1`.\n\n2. **Run the Example:**\n\n ```bash\n python swamp_mqtt_client/examples/basic.py\n ```\n\n **Functionality:**\n - Connects to the specified MQTT broker.\n - Subscribes to `test/topic` with QoS 0 and `test/topic2` with QoS 1.\n - Logs received messages on subscribed topics.\n - Handles graceful shutdown on receiving `KeyboardInterrupt`.\n\n### Bridge Example\n\nThe **Bridge Example** shows how to bridge messages between two MQTT brokers. It subscribes to topics on a source broker and republishes messages to a target broker.\n\n#### Running the Bridge Example\n\n1. **Set Up Environment Variables:**\n\n Ensure your `.env` file includes the necessary configurations for both `SUBSCRIBE_CLIENT` and `PUBLISH_CLIENT`.\n\n2. **Run the Example:**\n\n ```bash\n python swamp_mqtt_client/examples/bridge/bridge.py\n ```\n\n **Functionality:**\n - Subscribes to `source/topic` with QoS 0 and `source/topic2` with QoS 1 on the source broker.\n - Transforms incoming messages using the specified JSONata expression.\n - Republishes the transformed messages to `target/topic` on the target broker.\n - Handles graceful shutdown on receiving termination signals (`SIGINT`, `SIGTERM`).\n\n### Publish Example\n\nThe **Publish Example** illustrates how to publish messages based on keyboard input to an MQTT topic.\n\n#### Running the Publish Example\n\n1. **Set Up Environment Variables:**\n\n Ensure your `.env` file includes the necessary configurations for `MQTTCLIENT1`.\n\n2. **Run the Example:**\n\n ```bash\n python swamp_mqtt_client/examples/publish/publish.py\n ```\n\n **Functionality:**\n - Connects to the specified MQTT broker.\n - Listens for keyboard inputs and publishes each key press to the `keyboard/keys` topic.\n - Stops publishing and disconnects gracefully when the user types `exit` or interrupts the program.\n\n## Data Formats\n\nSwampClient uses the **Zeitgleich** library for timestamp handling. For detailed information on timestamp normalization and conversion, refer to the [Zeitgleich documentation](https://pypi.org/project/Zeitgleich/).\n\n## TODOs\n\n- **Unit Tests:**\n - Implement unit tests for SwampClient functionalities.\n - Test support for `mqtts`, `ws`, `wss` schemes.\n - Verify MQTT broker authentication with username and password.\n - Test `topic2payload` feature.\n - Validate `pass_through` raw data handling.\n - Test split payload functionality.\n\n- **Configuration Enhancements:**\n - Add configuration options for Bridge mode.\n - Implement configuration for retaining messages.\n - Make configuration options dependent on each other (e.g., `split_payload` requires `jsonata_expression`).\n\n- **Exception Handling:**\n - Wrap certain exceptions in custom exception classes.\n - Improve error handling for connection and publishing failures.\n\n- **Documentation:**\n - Expand documentation for advanced configurations.\n - Provide more examples covering additional features.\n\n- **Code-Level TODOs:**\n - Support configuration of all subscription options, not just QoS.\n - Use `ts.Origin` for origin handling.\n - Test `topic2payload` integration.\n - Handle additional payload cases in message processing.\n - Wrap disconnect errors in custom exceptions and handle logging appropriately.\n\n## License\n\nLicensed under the [MIT License](LICENSE).",
"bugtrack_url": null,
"license": null,
"summary": "An MQTT client library built as a wrapper around Paho MQTT, configurable via environment variables, supporting JSONata transformations and timestamp handling through Zeitgleich.",
"version": "0.0.9",
"project_urls": {
"source": "https://git.ift.tuwien.ac.at/lab/pub/pypi/swampclient"
},
"split_keywords": [
"asyncio",
" client",
" jsonata",
" mqtt",
" time series",
" timestamp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "60a87708e3e1e7a606c33518ba683fc2af5065cf9d2c7b6d2ae65f736b41f9fa",
"md5": "55a07b716c0091b0440074f4c8f54a74",
"sha256": "83d7e657e2b4dab7f770d9cad076adbdfe4828756ffe8790ab3d5a51ced027d7"
},
"downloads": -1,
"filename": "swampclient-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "55a07b716c0091b0440074f4c8f54a74",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 11766,
"upload_time": "2025-02-03T13:37:42",
"upload_time_iso_8601": "2025-02-03T13:37:42.859369Z",
"url": "https://files.pythonhosted.org/packages/60/a8/7708e3e1e7a606c33518ba683fc2af5065cf9d2c7b6d2ae65f736b41f9fa/swampclient-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3e158a3c794bf871a6b03952e774feb71c7675da9b7e5bc2aaaf88657dcd2a9f",
"md5": "4929ebc88f0ef17afbecd96d31680845",
"sha256": "43b7a4358a3ab23f38261203838bd206ad60bea4d348a3dda34069e4266a411d"
},
"downloads": -1,
"filename": "swampclient-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "4929ebc88f0ef17afbecd96d31680845",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11981,
"upload_time": "2025-02-03T13:37:44",
"upload_time_iso_8601": "2025-02-03T13:37:44.815539Z",
"url": "https://files.pythonhosted.org/packages/3e/15/8a3c794bf871a6b03952e774feb71c7675da9b7e5bc2aaaf88657dcd2a9f/swampclient-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-03 13:37:44",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "swampclient"
}
