Metadata-Version: 2.1
Name: mqttwarn
Version: 0.35.0
Summary: mqttwarn - subscribe to MQTT topics and notify pluggable services
Home-page: https://github.com/mqtt-tools/mqttwarn
Author: Jan-Piet Mens, Ben Jones, Andreas Motl
Author-email: jpmens@gmail.com
License: EPL 2.0
Keywords: mqtt notification plugins data acquisition push transformation engine mosquitto
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: Eclipse Public License 2.0 (EPL-2.0)
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: Education
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: XMPP
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Pre-processors
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Archiving
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
License-File: LICENSE
Requires-Dist: attrs<23
Requires-Dist: docopt<1
Requires-Dist: funcy<3
Requires-Dist: future<1,>=0.18.0
Requires-Dist: jinja2<4
Requires-Dist: paho-mqtt<2
Requires-Dist: requests<3
Requires-Dist: six<2
Requires-Dist: importlib-metadata; python_version < "3.8"
Requires-Dist: importlib-resources; python_version < "3.8"
Provides-Extra: all
Requires-Dist: apns>=2.0.1; extra == "all"
Requires-Dist: apprise<2,>=1.3; extra == "all"
Requires-Dist: pyst2>=0.5.0; extra == "all"
Requires-Dist: celery; extra == "all"
Requires-Dist: dnspython>=1.15.0; extra == "all"
Requires-Dist: fbchat>=1.3.6; extra == "all"
Requires-Dist: gspread>=2.1.1; extra == "all"
Requires-Dist: oauth2client>=4.1.2; extra == "all"
Requires-Dist: mysqlclient; extra == "all"
Requires-Dist: pynsca>=1.6; extra == "all"
Requires-Dist: desktop-notifier<4; extra == "all"
Requires-Dist: Pastebin>=1.1.2; extra == "all"
Requires-Dist: psycopg2-binary>=2.7.4; extra == "all"
Requires-Dist: pyprowl>=3.0.1; extra == "all"
Requires-Dist: redis>=2.10.6; extra == "all"
Requires-Dist: pyserial>=3.4; extra == "all"
Requires-Dist: slack-sdk>=3.1.0; extra == "all"
Requires-Dist: Mastodon.py>=1.2.2; extra == "all"
Requires-Dist: twilio>=6.11.0; extra == "all"
Requires-Dist: python-twitter>=3.4.1; extra == "all"
Requires-Dist: websocket-client>=0.47.0; extra == "all"
Requires-Dist: xmpppy>=0.6.1; extra == "all"
Requires-Dist: dnspython>=1.16.0; extra == "all"
Requires-Dist: slixmpp>=1.5.2; extra == "all"
Requires-Dist: mqttwarn-contrib; extra == "all"
Requires-Dist: puka>=0.0.7; python_version < "3.12" and extra == "all"
Requires-Dist: pychromecast>=7.5.0; python_version >= "3.7" and extra == "all"
Requires-Dist: google-api-python-client<2; python_version >= "3.7" and extra == "all"
Requires-Dist: paramiko>=2.4.1; python_version >= "3.7" and extra == "all"
Provides-Extra: amqp
Requires-Dist: puka>=0.0.7; python_version < "3.12" and extra == "amqp"
Provides-Extra: apns
Requires-Dist: apns>=2.0.1; extra == "apns"
Provides-Extra: apprise
Requires-Dist: apprise<2,>=1.3; extra == "apprise"
Provides-Extra: asterisk
Requires-Dist: pyst2>=0.5.0; extra == "asterisk"
Provides-Extra: celery
Requires-Dist: celery; extra == "celery"
Provides-Extra: chromecast
Requires-Dist: pychromecast>=7.5.0; python_version >= "3.7" and extra == "chromecast"
Provides-Extra: contrib
Requires-Dist: mqttwarn-contrib; extra == "contrib"
Provides-Extra: desktopnotify
Requires-Dist: desktop-notifier<4; extra == "desktopnotify"
Provides-Extra: develop
Requires-Dist: black<23; extra == "develop"
Requires-Dist: build<1; extra == "develop"
Requires-Dist: mypy<1.3; extra == "develop"
Requires-Dist: poethepoet<1; extra == "develop"
Requires-Dist: sphinx-autobuild; extra == "develop"
Requires-Dist: ruff==0.0.254; python_version >= "3.7" and extra == "develop"
Provides-Extra: dnsupdate
Requires-Dist: dnspython>=1.15.0; extra == "dnsupdate"
Provides-Extra: fbchat
Requires-Dist: fbchat>=1.3.6; extra == "fbchat"
Provides-Extra: gss2
Requires-Dist: gspread>=2.1.1; extra == "gss2"
Requires-Dist: oauth2client>=4.1.2; extra == "gss2"
Requires-Dist: google-api-python-client<2; python_version >= "3.7" and extra == "gss2"
Provides-Extra: mysql
Requires-Dist: mysql; extra == "mysql"
Provides-Extra: mysql_dynamic
Requires-Dist: mysqlclient; extra == "mysql-dynamic"
Provides-Extra: nsca
Requires-Dist: pynsca>=1.6; extra == "nsca"
Provides-Extra: pastebinpub
Requires-Dist: Pastebin>=1.1.2; extra == "pastebinpub"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.7.4; extra == "postgres"
Provides-Extra: prowl
Requires-Dist: pyprowl>=3.0.1; extra == "prowl"
Provides-Extra: pushbullet
Provides-Extra: redispub
Requires-Dist: redis>=2.10.6; extra == "redispub"
Provides-Extra: rrdtool
Requires-Dist: rrdtool>=0.1.12; extra == "rrdtool"
Provides-Extra: serial
Requires-Dist: pyserial>=3.4; extra == "serial"
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.1.0; extra == "slack"
Provides-Extra: slixmpp
Requires-Dist: slixmpp>=1.5.2; extra == "slixmpp"
Provides-Extra: ssh
Requires-Dist: paramiko>=2.4.1; python_version >= "3.7" and extra == "ssh"
Provides-Extra: test
Requires-Dist: pytest<8; extra == "test"
Requires-Dist: pytest-cov<5; extra == "test"
Requires-Dist: pytest-mock<4; extra == "test"
Requires-Dist: pytest-mqtt<1; extra == "test"
Requires-Dist: tox<4; extra == "test"
Requires-Dist: requests-toolbelt<2,>=1; extra == "test"
Requires-Dist: responses<1,>=0.13.3; extra == "test"
Requires-Dist: pyfakefs<6,>=4.5; extra == "test"
Requires-Dist: apns>=2.0.1; extra == "test"
Requires-Dist: apprise<2,>=1.3; extra == "test"
Requires-Dist: pyst2>=0.5.0; extra == "test"
Requires-Dist: celery; extra == "test"
Requires-Dist: dnspython>=1.15.0; extra == "test"
Requires-Dist: fbchat>=1.3.6; extra == "test"
Requires-Dist: gspread>=2.1.1; extra == "test"
Requires-Dist: oauth2client>=4.1.2; extra == "test"
Requires-Dist: mysqlclient; extra == "test"
Requires-Dist: pynsca>=1.6; extra == "test"
Requires-Dist: desktop-notifier<4; extra == "test"
Requires-Dist: Pastebin>=1.1.2; extra == "test"
Requires-Dist: psycopg2-binary>=2.7.4; extra == "test"
Requires-Dist: pyprowl>=3.0.1; extra == "test"
Requires-Dist: redis>=2.10.6; extra == "test"
Requires-Dist: pyserial>=3.4; extra == "test"
Requires-Dist: slack-sdk>=3.1.0; extra == "test"
Requires-Dist: Mastodon.py>=1.2.2; extra == "test"
Requires-Dist: twilio>=6.11.0; extra == "test"
Requires-Dist: python-twitter>=3.4.1; extra == "test"
Requires-Dist: websocket-client>=0.47.0; extra == "test"
Requires-Dist: xmpppy>=0.6.1; extra == "test"
Requires-Dist: dnspython>=1.16.0; extra == "test"
Requires-Dist: slixmpp>=1.5.2; extra == "test"
Requires-Dist: mqttwarn-contrib; extra == "test"
Requires-Dist: puka>=0.0.7; python_version < "3.12" and extra == "test"
Requires-Dist: dataclasses; python_version < "3.7" and extra == "test"
Requires-Dist: pychromecast>=7.5.0; python_version >= "3.7" and extra == "test"
Requires-Dist: google-api-python-client<2; python_version >= "3.7" and extra == "test"
Requires-Dist: paramiko>=2.4.1; python_version >= "3.7" and extra == "test"
Provides-Extra: tootpaste
Requires-Dist: Mastodon.py>=1.2.2; extra == "tootpaste"
Provides-Extra: twilio
Requires-Dist: twilio>=6.11.0; extra == "twilio"
Provides-Extra: twitter
Requires-Dist: python-twitter>=3.4.1; extra == "twitter"
Provides-Extra: websocket
Requires-Dist: websocket-client>=0.47.0; extra == "websocket"
Provides-Extra: xmpp
Requires-Dist: xmpppy>=0.6.1; extra == "xmpp"
Requires-Dist: dnspython>=1.16.0; extra == "xmpp"

########
mqttwarn
########

.. image:: https://cloud.githubusercontent.com/assets/2345521/6320105/4dd7a826-bade-11e4-9a61-72aa163a40a9.png

To *warn*, *alert*, or *notify*.

.. image:: https://raw.githubusercontent.com/mqtt-tools/mqttwarn/main/assets/google-definition.jpg


******
Status
******

.. image:: https://github.com/mqtt-tools/mqttwarn/workflows/Tests/badge.svg
    :target: https://github.com/mqtt-tools/mqttwarn/actions?workflow=Tests

.. image:: https://codecov.io/gh/mqtt-tools/mqttwarn/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/mqtt-tools/mqttwarn

.. image:: https://img.shields.io/pypi/pyversions/mqttwarn.svg
    :target: https://pypi.org/project/mqttwarn/

|

.. image:: https://img.shields.io/pypi/l/mqttwarn.svg
    :target: https://pypi.org/project/mqttwarn/

.. image:: https://img.shields.io/pypi/status/mqttwarn.svg
    :target: https://pypi.org/project/mqttwarn/

.. image:: https://img.shields.io/pypi/v/mqttwarn.svg
    :target: https://pypi.org/project/mqttwarn/

.. image:: https://pepy.tech/badge/mqttwarn/month
    :target: https://pepy.tech/project/mqttwarn

|

`GitHub <https://github.com/mqtt-tools/mqttwarn>`_
| `PyPI <https://pypi.org/project/mqttwarn/>`_
| `Documentation <https://mqttwarn.readthedocs.io>`_
| `Issues <https://github.com/mqtt-tools/mqttwarn/issues>`_
| `Changelog <https://github.com/mqtt-tools/mqttwarn/blob/main/CHANGES.rst>`_


*****
About
*****

mqttwarn - subscribe to MQTT topics and notify pluggable services.


Description
===========

*mqttwarn* subscribes to any number of MQTT topics and publishes received
payloads to one or more notification services after optionally applying
sophisticated transformations.

A picture says a thousand words.

.. image:: https://raw.githubusercontent.com/mqtt-tools/mqttwarn/main/assets/mqttwarn.png
    :target: #


Notification service coverage
=============================

*mqttwarn* comes with **over 70 notification handler plugins**, covering a
wide range of notification services and is very open to further contributions.
You can enjoy the alphabetical list of plugins on the `mqttwarn notifier
catalog`_ page.

On top of that, it integrates with the excellent `Apprise`_ notification
library. `Apprise notification services`_ has a complete list of the **80+
notification services** supported by Apprise.



*************
Documentation
*************

The `mqttwarn documentation`_ is the right place to read all about *mqttwarn*'s
features and integrations, and how you can leverage all its framework components
for building custom applications. Its service plugins can be inspected on the
`mqttwarn notifier catalog`_ page.


************
Installation
************

Using pip
=========

Synopsis::

    pip install --upgrade mqttwarn

You can also add support for a specific service plugin::

    pip install --upgrade 'mqttwarn[xmpp]'

You can also add support for multiple services, all at once::

    pip install --upgrade 'mqttwarn[apprise,asterisk,nsca,desktopnotify,tootpaste,xmpp]'

See also: `Installing mqttwarn with pip`_.

OCI container image
===================

For running ``mqttwarn`` on a container infrastructure like Docker or
Kubernetes, corresponding images are automatically published to the
GitHub Container Registry (GHCR).

- ``ghcr.io/mqtt-tools/mqttwarn-standard:latest``
- ``ghcr.io/mqtt-tools/mqttwarn-full:latest``

To learn more about this topic, please follow up reading the `Using the OCI image
with Docker or Podman`_ documentation section.


*************
Configuration
*************

In order to learn how to configure mqttwarn, please head over to the documentation
section about the `mqttwarn configuration`_.


*****
Usage
*****

Interactive service
===================
Just launch ``mqttwarn``::

    # Run mqttwarn
    mqttwarn


To supply a different configuration file or log file, optionally use::

    # Define configuration file
    export MQTTWARNINI=/etc/mqttwarn/acme.ini

    # Define log file
    export MQTTWARNLOG=/var/log/mqttwarn.log

    # Run mqttwarn
    mqttwarn

System daemon
=============

There are different ways to run mqttwarn as a system daemon. There are examples
for systemd, traditional init, OpenRC, and Supervisor_ in the ``etc`` directory
of this repository, for example `supervisor.ini`_ (Supervisor) and
`mqttwarn.service`_ (systemd).

Standalone
==========

In order to directly invoke notification plugins from custom programs, or for
debugging them, see `Running notification plugins standalone`_.

Development sandbox
===================

For hacking on mqttwarn, please install it in development mode, using a
`mqttwarn development sandbox`_ installation.


*******************
Project information
*******************

About
=====
These links will guide you to the source code of *mqttwarn* and its documentation.

- `mqttwarn on GitHub <https://github.com/mqtt-tools/mqttwarn>`_
- `mqttwarn on the Python Package Index (PyPI) <https://pypi.org/project/mqttwarn/>`_
- `mqttwarn documentation <https://mqttwarn.readthedocs.io/>`_


Requirements
============
You will need at least the following components:

* Python 3.x or PyPy 3.x.
* An MQTT broker. We recommend `Eclipse Mosquitto`_.
* For invoking specific service plugins, additional Python modules may be required.
  See ``setup.py`` file.


Contributing
============

We are always happy to receive code contributions, ideas, suggestions
and problem reports from the community.

So, if you would like to contribute, you are most welcome.
Spend some time taking a look around, locate a bug, design issue or
spelling mistake, and then send us a pull request or create an `issue`_.

Thank you in advance for your efforts, we really appreciate any help or feedback.


License
=======

mqttwarn is copyright © 2014-2023 Jan-Piet Mens and contributors. All
rights reserved.

It is and will always be **free and open source software**.

Use of the source code included here is governed by the `Eclipse Public License
2.0 <EPL-2.0_>`_, see LICENSE_ file for details. Please also recognize the
licenses of third-party components.


***************
Troubleshooting
***************

If you encounter any problems during setup or operations or if you have further
suggestions, please let us know by `opening an issue on GitHub`_. Thank you
already.


************
Attributions
************

Acknowledgements
================
Thanks to all the contributors of *mqttwarn* who helped to conceive it in one
way or another. You know who you are.

Legal stuff
===========
"MQTT" is a trademark of the OASIS open standards consortium, which publishes the
MQTT specifications. "Eclipse Mosquitto" is a trademark of the Eclipse Foundation.

----

Have fun!


.. _Apprise: https://github.com/caronc/apprise
.. _Apprise notification services: https://github.com/caronc/apprise/wiki#notification-services
.. _backlog: https://github.com/mqtt-tools/mqttwarn/blob/main/doc/backlog.rst
.. _Eclipse Mosquitto: https://mosquitto.org
.. _EPL-2.0: https://www.eclipse.org/legal/epl-2.0/
.. _hacking: https://github.com/mqtt-tools/mqttwarn/blob/main/doc/hacking.rst
.. _How do your servers talk to you?: https://jpmens.net/2014/04/03/how-do-your-servers-talk-to-you/
.. _Installing mqttwarn with pip: https://mqttwarn.readthedocs.io/en/latest/usage/pip.html
.. _issue: https://github.com/mqtt-tools/mqttwarn/issues/new
.. _LICENSE: https://github.com/mqtt-tools/mqttwarn/blob/main/LICENSE
.. _MQTTwarn\: Ein Rundum-Sorglos-Notifier: https://web.archive.org/web/20140611040637/http://jaxenter.de/news/MQTTwarn-Ein-Rundum-Sorglos-Notifier-171312
.. _mqttwarn configuration: https://mqttwarn.readthedocs.io/en/latest/configure/
.. _mqttwarn development sandbox: https://mqttwarn.readthedocs.io/en/latest/workbench/sandbox.html
.. _mqttwarn documentation: https://mqttwarn.readthedocs.io/
.. _mqttwarn notifier catalog: https://mqttwarn.readthedocs.io/en/latest/notifier-catalog.html
.. _mqttwarn.service: https://github.com/mqtt-tools/mqttwarn/blob/main/etc/mqttwarn.service
.. _opening an issue on GitHub: https://github.com/mqtt-tools/mqttwarn/issues/new
.. _Running notification plugins standalone: https://mqttwarn.readthedocs.io/en/latest/usage/standalone.html
.. _Schwarmalarm using mqttwarn: https://hiveeyes.org/docs/system/schwarmalarm-mqttwarn.html
.. _Supervisor: https://jpmens.net/2014/02/13/in-my-toolbox-supervisord/
.. _supervisor.ini: https://github.com/mqtt-tools/mqttwarn/blob/main/etc/supervisor.ini
.. _Using the OCI image with Docker or Podman: https://mqttwarn.readthedocs.io/en/latest/usage/oci.html
