# weeve Modules Python Package
This Python pip package is a specially designed support package for developers to implement their own weeve modules.
The package takes care of all weeve specific intercontainer communication protocols and other aspects of the module's functionality within weeve ecosystem.
For the full documentation on building weeve modules, please see our official docs: [How to create a weeve module](https://docs.weeve.engineering/guides/how-to-create-a-weeve-module).
- [weeve Modules Python Package](#weeve-modules-python-package)
- [Package specific environment variables](#package-specific-environment-variables)
- [weeve\_modules.listener()](#weeve_moduleslistener)
- [weeve\_modules.send()](#weeve_modulessend)
- [weeve\_modules.weeve\_logger()](#weeve_modulesweeve_logger)
- [weeve\_modules.add\_graceful\_termination()](#weeve_modulesadd_graceful_termination)
- [Example: Input Module](#example-input-module)
- [Example: Processing Module](#example-processing-module)
- [Example: Output Module](#example-output-module)
## Package specific environment variables
These environment variables are set by the weeve Agent on the edge-node. In order to avoid conflicts, do not override these variables when pushing modules to production.
| Environment Variables | type | Description |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LOG_LEVEL | string | Allowed log levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Refer to [logging levels package documentation](https://docs.python.org/3/library/logging.html#levels). |
| MODULE_NAME | string | Name of the module. |
| INGRESS_HOST | string | Host to which data will be received. |
| INGRESS_PORT | string | Port to which data will be received. |
| EGRESS_URLS | string | HTTP ReST endpoint for the next modules. |
## weeve_modules.listener()
`listener()` is the most important function as it allows the module to set up a listener server to receive data from other modules within the weeve ecosystem. `listener()` takes one argument:
* `callback_function` (`object`): The callback function defined by a user and ready to receive data for further processing. Callback function **must** accept data as an argument.
```python
from weeve_modules import listener
def my_module_logic(data):
# your module code here
if __name__ == "__main__":
listener(callback_function=my_module_logic)
```
## weeve_modules.send()
This function enables passing data to the next module in the weeve Edge Application. It takes only one argument:
* `processed_data` (`dict`): Data in JSON format to send to the next module.
It returns empty string ("") on success. Otherwise, error message.
```text
On error:
"Failed sending data to urls: https://testing.com - Error 404."
```
Example:
```python
from weeve_modules import send
# send data to the next module
err = send({"temperature": 12, "pressure": 1019})
if err:
# your error protocol
```
## weeve_modules.weeve_logger()
Weeve logger is based on [logging package](https://docs.python.org/3/library/logging.html#). There are five supported logging levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Refer to [logging levels package documentation](https://docs.python.org/3/library/logging.html#levels). These messages have a custom weeve logging protocol which is in sync with weeve Agent and API. Current schema:
```text
{
"timestamp": <timestamp>,
"level": <logging_level>,
"filename": <log_message_source_filename>,
"message": <log_message>
}
```
Example:
```python
from weeve_modules import weeve_logger
# initialize logging by providing logger name, we strongly recommend using the filename
log = weeve_logger("tutorial_module")
# logging examples
log.debug("This is debug log messege.")
log.info("This is info log messege.")
log.warning("This is warning log messege.")
log.error("This is error log messege.")
log.critical("This is critical log messege.")
```
## weeve_modules.add_graceful_termination()
`add_graceful_termination()` function enables Docker to gracefully terminate the module container. This is optional as developers might want to implement their own graceful termination if their modules use extra resources or files. However, we strongly recommend calling `add_graceful_termination()` at the start of your script unless the module uses volumes, external resources, etc. when the custom implementation of graceful termination might be required.
Example:
```python
from weeve_modules import listener, add_graceful_termination
def my_module_logic(data):
# your module code here
if __name__ == "__main__":
add_graceful_termination()
listener(callback_function=my_module_logic)
```
## Example: Input Module
This is an example of a simple input module that receives data over HTTP ReST and passes it to the next module in the weeve Edge Application.
We need `send()` and `weeve_logger()` functions.
```python
from weeve_modules import send, weeve_logger
from bottle import run, post, request
log = weeve_logger("my_input_module")
@post("/")
def _request_handler():
# receive data
received_data = request.json
# send data to the next module
err = send(received_data)
if __name__ == "__main__":
add_graceful_termination()
# start the server on http://0.0.0.0:8080/
run(
host="0.0.0.0",
port=8080,
quiet=True,
)
```
## Example: Processing Module
This is an example of a simple processing module that receives data from the previous module and filters out `temperature` lower that 0. Later it sends data to the next module in the weeve Edge Application.
We need `send()`, `weeve_logger()` and `listener()` functions.
```python
from weeve_modules import send, weeve_logger, listener
log = weeve_logger("my_processing_module")
# my module logic functionality
def filter_temperature(data):
# filter temperature data
if data["temperature"] >= 0:
# send data to the next module
err = send(data)
# check the success of sending the data
if err:
log.error("Failed to pass filetered data: %s", err)
else:
log.info("Successfully passed filetered data.")
if __name__ == "__main__":
add_graceful_termination()
# set up a listener to receive data from other modules within the weeve ecosystem
listener(callback_function=filter_temperature)
```
## Example: Output Module
This is an example of a simple output module that receives data from the previous module and sends it over HTTP ReST to a selected endpoint.
We need `weeve_logger()` and `listener()` functions.
```python
from weeve_modules import weeve_logger, listener
from requests import post
from json import dumps
log = weeve_logger("my_output_module")
# my module logic functionality
def send_to_endpoint(data):
log.info("Sending data to the endpoint.")
post(url="", json=data)
if __name__ == "__main__":
add_graceful_termination()
# set up a listener to receive data from other modules within the weeve ecosystem
listener(callback_function=send_to_endpoint)
```
Raw data
{
"_id": null,
"home_page": "",
"name": "weeve-modules",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Jakub Grzelak <jakub.grzelak@weeve.network>, Sanyam Arya <sanyam.arya@weeve.network>, Paul Gaiduk <paul.gaiduk@weeve.network>",
"keywords": "Internet of Things,IoT,Machine Economy,modules,weeve",
"author": "",
"author_email": "Jakub Grzelak <jakub.grzelak@weeve.network>",
"download_url": "https://files.pythonhosted.org/packages/99/c7/ab76bcdc0c325f34dd3da14e4ab65a50feb676ed5fe61f02ab79d1895912/weeve_modules-1.0.0.tar.gz",
"platform": null,
"description": "# weeve Modules Python Package\n\nThis Python pip package is a specially designed support package for developers to implement their own weeve modules.\nThe package takes care of all weeve specific intercontainer communication protocols and other aspects of the module's functionality within weeve ecosystem.\n\nFor the full documentation on building weeve modules, please see our official docs: [How to create a weeve module](https://docs.weeve.engineering/guides/how-to-create-a-weeve-module).\n\n- [weeve Modules Python Package](#weeve-modules-python-package)\n - [Package specific environment variables](#package-specific-environment-variables)\n - [weeve\\_modules.listener()](#weeve_moduleslistener)\n - [weeve\\_modules.send()](#weeve_modulessend)\n - [weeve\\_modules.weeve\\_logger()](#weeve_modulesweeve_logger)\n - [weeve\\_modules.add\\_graceful\\_termination()](#weeve_modulesadd_graceful_termination)\n - [Example: Input Module](#example-input-module)\n - [Example: Processing Module](#example-processing-module)\n - [Example: Output Module](#example-output-module)\n\n## Package specific environment variables\n\nThese environment variables are set by the weeve Agent on the edge-node. In order to avoid conflicts, do not override these variables when pushing modules to production.\n\n| Environment Variables | type | Description |\n| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| LOG_LEVEL | string | Allowed log levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Refer to [logging levels package documentation](https://docs.python.org/3/library/logging.html#levels). |\n| MODULE_NAME | string | Name of the module. |\n| INGRESS_HOST | string | Host to which data will be received. |\n| INGRESS_PORT | string | Port to which data will be received. |\n| EGRESS_URLS | string | HTTP ReST endpoint for the next modules. |\n\n\n## weeve_modules.listener()\n\n`listener()` is the most important function as it allows the module to set up a listener server to receive data from other modules within the weeve ecosystem. `listener()` takes one argument:\n\n* `callback_function` (`object`): The callback function defined by a user and ready to receive data for further processing. Callback function **must** accept data as an argument.\n\n```python\nfrom weeve_modules import listener\n\ndef my_module_logic(data):\n # your module code here\n\nif __name__ == \"__main__\":\n listener(callback_function=my_module_logic)\n```\n\n## weeve_modules.send()\n\nThis function enables passing data to the next module in the weeve Edge Application. It takes only one argument:\n\n* `processed_data` (`dict`): Data in JSON format to send to the next module.\n\nIt returns empty string (\"\") on success. Otherwise, error message.\n\n```text\nOn error:\n\"Failed sending data to urls: https://testing.com - Error 404.\"\n```\n\nExample:\n\n```python\nfrom weeve_modules import send\n\n# send data to the next module\nerr = send({\"temperature\": 12, \"pressure\": 1019})\nif err:\n # your error protocol\n```\n\n## weeve_modules.weeve_logger()\n\nWeeve logger is based on [logging package](https://docs.python.org/3/library/logging.html#). There are five supported logging levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Refer to [logging levels package documentation](https://docs.python.org/3/library/logging.html#levels). These messages have a custom weeve logging protocol which is in sync with weeve Agent and API. Current schema:\n\n```text\n{\n \"timestamp\": <timestamp>,\n \"level\": <logging_level>,\n \"filename\": <log_message_source_filename>,\n \"message\": <log_message>\n}\n```\n\nExample:\n\n```python\nfrom weeve_modules import weeve_logger\n\n# initialize logging by providing logger name, we strongly recommend using the filename\nlog = weeve_logger(\"tutorial_module\")\n\n# logging examples\nlog.debug(\"This is debug log messege.\")\nlog.info(\"This is info log messege.\")\nlog.warning(\"This is warning log messege.\")\nlog.error(\"This is error log messege.\")\nlog.critical(\"This is critical log messege.\")\n```\n\n## weeve_modules.add_graceful_termination()\n\n`add_graceful_termination()` function enables Docker to gracefully terminate the module container. This is optional as developers might want to implement their own graceful termination if their modules use extra resources or files. However, we strongly recommend calling `add_graceful_termination()` at the start of your script unless the module uses volumes, external resources, etc. when the custom implementation of graceful termination might be required.\n\nExample:\n\n```python\nfrom weeve_modules import listener, add_graceful_termination\n\ndef my_module_logic(data):\n # your module code here\n\nif __name__ == \"__main__\":\n add_graceful_termination()\n\n listener(callback_function=my_module_logic)\n```\n\n## Example: Input Module\n\nThis is an example of a simple input module that receives data over HTTP ReST and passes it to the next module in the weeve Edge Application.\nWe need `send()` and `weeve_logger()` functions.\n\n```python\nfrom weeve_modules import send, weeve_logger\nfrom bottle import run, post, request\n\nlog = weeve_logger(\"my_input_module\")\n\n@post(\"/\")\ndef _request_handler():\n # receive data\n received_data = request.json\n\n # send data to the next module\n err = send(received_data)\n\nif __name__ == \"__main__\":\n add_graceful_termination()\n\n # start the server on http://0.0.0.0:8080/\n run(\n host=\"0.0.0.0\",\n port=8080,\n quiet=True,\n )\n```\n\n## Example: Processing Module\n\nThis is an example of a simple processing module that receives data from the previous module and filters out `temperature` lower that 0. Later it sends data to the next module in the weeve Edge Application.\nWe need `send()`, `weeve_logger()` and `listener()` functions.\n\n```python\nfrom weeve_modules import send, weeve_logger, listener\n\nlog = weeve_logger(\"my_processing_module\")\n\n# my module logic functionality\ndef filter_temperature(data):\n\n # filter temperature data\n if data[\"temperature\"] >= 0:\n\n # send data to the next module\n err = send(data)\n\n # check the success of sending the data\n if err:\n log.error(\"Failed to pass filetered data: %s\", err)\n else:\n log.info(\"Successfully passed filetered data.\")\n\nif __name__ == \"__main__\":\n add_graceful_termination()\n\n # set up a listener to receive data from other modules within the weeve ecosystem\n listener(callback_function=filter_temperature)\n```\n\n## Example: Output Module\n\nThis is an example of a simple output module that receives data from the previous module and sends it over HTTP ReST to a selected endpoint.\nWe need `weeve_logger()` and `listener()` functions.\n\n```python\nfrom weeve_modules import weeve_logger, listener\nfrom requests import post\nfrom json import dumps\n\nlog = weeve_logger(\"my_output_module\")\n\n# my module logic functionality\ndef send_to_endpoint(data):\n\n log.info(\"Sending data to the endpoint.\")\n post(url=\"\", json=data)\n\nif __name__ == \"__main__\":\n add_graceful_termination()\n\n # set up a listener to receive data from other modules within the weeve ecosystem\n listener(callback_function=send_to_endpoint)\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Python package supporting weeve modules infrastructure.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/weeve-modules/weeve-modules-python-package/issues",
"GitHub": "https://github.com/weeve-modules/weeve-modules-python-package",
"How to create a weeve module": "https://docs.weeve.engineering/guides/how-to-create-a-weeve-module",
"weeve": "https://www.weeve.network"
},
"split_keywords": [
"internet of things",
"iot",
"machine economy",
"modules",
"weeve"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fdc7153bd4d33d5f846b5924401a235a0f07f787c18ae4aea043b743c278bc66",
"md5": "5b9fc0a612ff3de4298727816e39aa5e",
"sha256": "c9016e3af42b7ec15110affa181bc4ac2d6a818ae6f4da45ebcb317042ec3554"
},
"downloads": -1,
"filename": "weeve_modules-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b9fc0a612ff3de4298727816e39aa5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21905,
"upload_time": "2023-06-07T12:48:59",
"upload_time_iso_8601": "2023-06-07T12:48:59.219510Z",
"url": "https://files.pythonhosted.org/packages/fd/c7/153bd4d33d5f846b5924401a235a0f07f787c18ae4aea043b743c278bc66/weeve_modules-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "99c7ab76bcdc0c325f34dd3da14e4ab65a50feb676ed5fe61f02ab79d1895912",
"md5": "69407dd96acf4f9a46983c9ec4efdbfb",
"sha256": "ff98a439c59b4506fccea485f651cdf6fcb2d0e5f5b6a592a4da9ac93cfa2c71"
},
"downloads": -1,
"filename": "weeve_modules-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "69407dd96acf4f9a46983c9ec4efdbfb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 22871,
"upload_time": "2023-06-07T12:49:01",
"upload_time_iso_8601": "2023-06-07T12:49:01.508561Z",
"url": "https://files.pythonhosted.org/packages/99/c7/ab76bcdc0c325f34dd3da14e4ab65a50feb676ed5fe61f02ab79d1895912/weeve_modules-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-07 12:49:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "weeve-modules",
"github_project": "weeve-modules-python-package",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "weeve-modules"
}
JSON
