Welcome!

This module provides a universal interface for various communications systems and services (e.g. email, Slack, SMS, etc.) and makes it possible to send the same message to several services with a single method call. The same call structure is used regardless of which services are enabled.

Installation

Warning

This module is in early alpha stage. And while the code works (and passes all the tests), use at your own risk πŸ€“

You can install the f451 Communications module via pip from PyPi:

$ pip install f451-comms

Quickstart

A common use case for the f451 Communications module is in applications that send (usually programmatically generated) messages via one or more channels. The module assumes that you provide all necessary keys and secrets required to verify your credentials with the services linked to the channels that you want to use.

It is recommended that you store these keys and secrets in a separate file (e.g. secrets.ini). However, it is also possible to submit them – for example during testing – in the form of a so-called dict structure.

from configparser import ConfigParser, ExtendedInterpolation
from f451_comms.comms import Comms

secrets = ConfigParser(interpolation=ExtendedInterpolation())
secrets.read("_PATH_TO_YOUR_SECRETS_FILE_")

comms = Comms(secrets)
comms.send_message("Hello world!", "all")

The basic sequence is to first initialize the Comms object with the keys and secrets required to authenticate with the services that you want to use. After that you can send messages to one or more channels with a single method call to the Comms object.

The send_message() method also has a 3rd argument that allows you to include additional attributes using a dict structure. These attributes can contain a wide variety of items. For example, you can include the HTML version of an email, or Slack blocks for more complex Slack messages. You can also include references to images to be included with the message, or files to be attached to emails, and so on.

Background and history

This module was originally created to β€œscratch an itch” – or, as we say in marketing parlance: to solve a particular use case. πŸ˜‰ – I had several single-purpose applications running on different devices (e.g. Raspberry Pi) configured to support specific hardware configurations (i.e. sensors and displays, etc.), services, or functions. And all applications were designed to notify me via different channels that certain events had occurred and so on.

Using a standardized communications library made it easy to have the main application on each device communicate results to the same channels without writing duplicate code for each application for a given device. Instead, I can now import this library, and most/all per-application customization can be handled by updating config files on each device.

For example, I have several devices that continuously collect data from sensors and perform various processing tasks on that data. Then, at regular intervals, when specific tasks are completed or certain events are triggered, I get notified via SMS, some fancy Slack message, or even get a nice HTML-based email with a status update, etc. And in some cases, the devices also notify the world via Twitter that whatever status was updated.

But most importantly, I’m able to call a simple send_message() method, which works the same way regardless of which services are enabled for a given device. And if I add a new communications channel, I can enable it quickly on my devices without updating the core applications. Simply adding the new channel to a configuration file is enough 😎

Current support:

Future support:

  • Other - I know, this is really specific … but there will be more 😜

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, the f451 Communications module is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from @cjolowicz’s Hypermodern Python Cookiecutter template.