Git Product home page Git Product logo

herald-of-completion's Introduction

Herald of Completion

Version pypi CI Issues Donate

Hark! The herald of completion has arrived ... to let you know when your long-running tasks are done.

Decorate your functions with messengers, who will send a notification to you when your function has finished running.

The notification can contain a message and, optionally, the traceback if your function failed.

Installation

pip install herald-of-completion

Usage

Wrap the @herald decorator around the function you want to be notified about:

from herald.decorators import Herald
from herald.messengers import DiscordMessenger

herald = Herald(".env")  # Specify location of your .env settings file
                         # herald is the name of your decorator

discord = DiscordMessenger()  # create a new messenger

@herald(discord)  # wrap decorator around the function, with the messenger you want to use
def my_function():
    a = [1, 2, 3]
    return a

You can send multiple messengers at the same time:

from herald.decorators import Herald
from herald.messengers import DiscordMessenger, EmailMessenger

herald = Herald(".env")

discord = DiscordMessenger()
email = EmailMessenger("[email protected]")  # some messengers take arguments

@herald([discord, email])  # multiple messengers can be used at the same time
def my_function():
    a = [1, 2, 3]
    return a

Options

By default, Herald will send a basic notification message indicating whether the function finished successfully or with an error. You can pass in a custom message to use instead:

@herald(email, message="My custom message")

Passing send_result=True to the decorator will send the return value of your function through the messenger. This also includes notifying you of any exceptions that were raised:

@herald(email, send_result=True)  # defaults to True
def my_function():
    a = [1, 2, 3]
    return a[100]  # if an exception is raised, `send_result=True` will also send the traceback

Passing send_args=True will show the args and kwargs the function was called with:

@herald(email, send_args=True)  # defaults to True
def my_function(var1, var2):
    return ", ".join([var1, var2])

my_function("Hello", var2="world")  # function call will be notified with all args and kwargs

Manual notifications

There may be times where you want to send a notification without using a decorator / tying it to a specific function.

A utility function, send_notification(), can be used for this purpose. To use this, you'll need to construct your own TaskInfo object (see: fields) containing the notification contents:

from herald.types import TaskInfo
from herald.utils import send_notification  # import the utility

discord = DiscordMessenger()
email = EmailMessenger()
info = TaskInfo(message="custom message", ...)  # create TaskInfo with contents of the message

send_notification([discord, email], info, ".env")  # pass in path to your .env file, if required

For more details about usage, the full API documentation can be found here: documentation

.env settings

Some messengers require credentials and/or additional settings to work. These values are stored in a .env file.

Pass the location of this file to the Herald constructor, which will pass the values down to your messengers.

The .env file should look something like this. You only need settings for the messengers you want to use:

# Discord settings
WEBHOOK_URL="https://discord.com/..."

# Email settings
SMTP_SERVER="smtp.gmail.com"
SMTP_PORT=587
SMTP_STARTTLS=True
SMTP_USER="[email protected]"
SMTP_PASSWORD="password"

Given the contents of this file, make sure you don't check it in to version control!

Explanation

Name Value Type Messenger Description
WEBHOOK_URL str Discord The webhook URL for your server. Instructions here
SMTP_SERVER str Email STMP server of the email address you want to send from
SMTP_PORT int Email STMP port of the email address you want to send from
SMTP_STARTTLS bool Email Whether your server uses STARTTLS for authentication
SMTP_USER str Email Your email username
SMTP_PASSWORD str Email Your email password

Contribution

Creating a new messenger

Creating a new messenger is straightforward and requires only 1 file:

  1. Create a new module in src/herald/messengers/
  2. Your class name should take the form <Name>Messenger and inherit the base Messenger abstract class. Example: class DiscordMessenger(Messenger): ...
  3. Your class must implement the abstract methods defined in the base Messenger class here
  4. Those methods define how your messenger sets it's secret values, and how it uses those settings to send a notification
  5. Finally, import your messenger in the __init__.py file here. This shortens the import path for users.

The notify() method of your messenger will receive a TaskInfo dataclass object. You can use the dataclass' fields (e.g. name, header) to construct custom notification messages.

Note: Pull requests should be made to the develop branch.

Tests

Unit and integration tests are located here.

Tests should be run using pytest.

Code style

The project is formatted using the black formatter.

Docstrings should follow the Google style (with a few tweaks to help with Sphinx generation of documentation pages). Use the docstrings throughout the codebase as a guide.

herald-of-completion's People

Contributors

sho-87 avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.