SwampClient


NameSwampClient JSON
Version 0.0.9 PyPI version JSON
download
home_pageNone
SummaryAn MQTT client library built as a wrapper around Paho MQTT, configurable via environment variables, supporting JSONata transformations and timestamp handling through Zeitgleich.
upload_time2025-02-03 13:37:44
maintainerNone
docs_urlNone
authorNone
requires_python>=3.6
licenseNone
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"
}
        
Elapsed time: 1.77907s