Fast & Free notifications for your code: Python wrapper around the ntfy.sh notifications service.
Project description
ntfy-wrapper
is a free and hassle-free customizable notifier for Python. No login, no API token, no fees, no bullshit.
It's actually a simple Python wrapper around ntfy
. Kudos to them ❤️
You can now send notification from your Python code and receive them on your computer through a Web App or a CLI, or on your phone with a dedicated app!
Again, all credit to ntfy
.
Install
Install ntfy-wrapper
with pip
:
pip install ntfy-wrapper
Dependencies:
requests
for easy HTTP requests and interacting with thentfy.sh
APItyper
for a powerful and beautiful CLIxkcdpass
to generate secure but human-friendly topics[^1]
Why?
Imagine you execute jobs on a shared cluster. They are in a queue. You get notified when they start. You get notified if there's an error. You get notified with the final performance of your model and if you click on the notification, you have access to the online logs from wandb or comet.ml.
That's just one scenario inspired from my work in AI, but really you can use it in any context!
Getting Started
from ntfy_wrapper import Notifier
if __name__ == "__main__":
ntfy = Notifier(notify_defaults={"title": "Your Project Name"})
# IFF this is the first call to `ntfy_wrapper` in your project, this line ^
# will print a topic id.
# It will also write the topic id to `.ntfy.conf` so this only happens once!
#
# Use one of those methods (from the print or the conf file) to copy the topic id
# and use it to subscribe to notifications from the web or mobile apps.
#
# You can also use the command-line `$ py-ntfy init` before executing your code
# and the same process will happen (new topic + conf file)
#
# Note: anyone with your topic id can subscribe to your notification. It's probably
# best to *exclude* the configuration file from version control.
ntfy("Job has been allocated, starting Model training")
try:
results = do_some_stuff()
if results["metric"] > threshold:
ntfy(
f"Great model! Its metric is {results['metric']:.3f}",
tags="white_check_mark", # this is the ✅ emoji
click=results["online_run_url"],
)
else:
ntfy(f"Done, but not great ({results['metric']:.3f})", tags="disappointed")
except Exception as e:
ntfy.notify(f"Error! -> {str(e)}", priority=4, emails="you@foo.bar")
Note ntfy(message)
is equivalent to ntfy.notify(message)
, the former is an alias of the latter.
If you do not receive notifications after you've made sure you've subscribed to the exact topic used by your Notifier
, it's probably because the request being sent out is malformed. Investigate using debug=True
in the notify()
call (e.g. : ntfy(message, debug=True)
).
User Guide
The central concept is "topics". It's basically an ID used to publish/subscribe to notifications. You should keep it secret and not easily guessable because anyone with the topic id can subscribe to your notifications. In particular, you should add .ntfy.conf
to .gitignore
.
In short, ntfy-wrapper
will publish to a topic and you'll have to subscribe to that same topic in order to receive the notification. You can receive your notification:
- On your computer
- By opening a local web app
- By setting up the
ntfy
CLI tool
- By opening a local web app
- On your phone
- By installing a mobile app
How to use
- Create topics in one of the following ways:
- configure one manually
- In a Python console use
ntfy_wrapper.utils.generate_topic()
to get a secure unique and human-readable topic (eg:winter-abide-dinghy-wand
) - From the command-line use
$ py-ntfy new-topic
to get a similar topic. Add--save
to add it to the configuration.
- Tell the
Notifier
to use this topic in one of the following ways:- In your code
Notifier(topics=your_topic)
orNotifier(topics=[topic1, topic2])
- Using a configuration file
- A configuration file will be created by default when constructing a
Notifier
except if you addwrite=False
to theNotifier.__init__
arguments - The configuration file is used to hold default values for:
targets
, i.e. a list of comma-separatedtopics
and a list of comma-separatedemails
message_defaults
which are default values used when calling.notify(...)
- You can also use
$ py-ntfy init
to initialize yourntfy-wrapper
configuration
- A configuration file will be created by default when constructing a
- From the command-line with
$ py-ntfy add topic your-topic
- In your code
- Setup defaults in one of the following ways
- By editing the config file
- By using the
py-ntfy
command-line tool
- Explore notification options by referring to the original
ntfy
docs
Configuration file
ntfy-wrapper
uses the INI standard along with configparser
to parse the configuration file. It expects 2 sections:
[notifier_init]
with optional fieldsemails =
andtopics =
to define systematic targets for the notification instead of putting them in your Python code[notify_defaults]
with optional fields listed below, which will define default parameters used byNotifier.notify(...)
. For instance you can set defaulttitle
andtags
for your code's.notify(...)
calls and override them at specific locations with keyword arguments.notify(title="Non-default title")
- The behavior of the
title
,priority
,tags
,click
,attach
,actions
andicon
keys is described in thentfy
docs
- The behavior of the
# For Notifier(emails=..., topics=...)
[notifier_init]
topics = my-secret-topic-1, mysecrettopic2
emails = you@foo.bar
# For Notifier.notify(title=..., priority=..., etc.)
[notify_defaults]
title = Message from ntfy-wrapper
priority = 0
tags = fire
click =
attach =
actions =
icon = https://raw.githubusercontent.com/vict0rsch/ntfy-wrapper/main/assets/logo.png
Command-line
ntfy_wrapper
comes with a command-line interface called py-ntfy
. It uses the great Python CLI tool Typer
. Its goal is to interact with ntfy-wrapper
's configuration in a user-friendly way. It is different in that sense to the original ntfy
CLI tool which is more generic.
-
Get help
$ py-ntfy --help Usage: py-ntfy [OPTIONS] COMMAND [ARGS]... ╭─ Options ────────────────────────────────────────────────────────────────────────────────╮ │ --install-completion Install completion for the current shell. │ │ --show-completion Show completion for the current shell, to copy it or │ │ customize the installation. │ │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────────────────╮ │ add [command sub-group] Add a new notification target or a default notification │ │ value. Run `$ py-ntfy add --help` for more info. │ │ clean Removes the configuration file. Use --conf-path to specify a path to the │ │ configuration file. Use --force to skip the confirmation prompt. │ │ init Initializes the configuration file. It should NOT be tracked by version │ │ control in order to protect the topic ID. Use --conf-path to specify a path │ │ to the configuration file. Use --force to overwrite an existing configuration │ │ file. │ │ new-topic Generates a random topic name and saves it to the config file if you use the │ │ --save option. │ │ remove [command sub-group] Remove a notification target or a default notification │ │ value. Run `$ py-ntfy remove --help` for more info. │ │ send Sends a notification to the given emails and topics. Optional command-line │ │ arguments can be passed to override the defaults in the config file and │ │ customize the message options. Refer to https://ntfy.sh/docs/publish to │ │ understand the options. Run `py-ntfy send --help` to see the available │ │ options. │ ╰──────────────────────────────────────────────────────────────────────────────────────────╯ $ py-ntfy add --help (similar output) $ py-ntfy add default --help (similar output) $ py-ntfy remove --help (similar output)
-
Initialize the configuration file
$ py-ntfy init 🔑 Your first topic is `aloe-corset-stream-alto`. Use it to subscribe to notifications! 🎉 Config file created at /path/to/repo/.ntfy.conf
-
Add a topic or an email
$ py-ntfy add topic some-secret-string-for-your-topic 🎉 Topic `some-secret-string-for-your-topic` added to /path/to/repo/.ntfy.conf $ py-ntfy add email you@foo.bar 🎉 Email you@foo.bar added to /Users/.../vict0rsch/ntfy-wrapper/.ntfy.conf
-
Add a default value for the
.notify(...)
calls$ py-ntfy add default key value 🎉 Default key=value added to /Users/.../vict0rsch/ntfy-wrapper/.ntfy.conf
-
Remove items by simply replacing
add
byremove
$ py-ntfy remove default key 🎉 Default key=value removed from /Users/.../vict0rsch/ntfy-wrapper/.ntfy.conf $ py-ntfy remove email hello@you.com Email hello@you.com does not exist. Ignoring.
-
Generate a new topic with
new-topic
and add it to your configuration with--save
$ py-ntfy new-topic --save 🎉 Topic nutty-tiling-clear-parlor added to /Users/.../vict0rsch/ntfy-wrapper/.ntfy.conf
-
Send a notification from the command-line with
send
$ py-ntfy send "hello" --topics frays-errant-acting-huddle --title "This is Victor" --click "https://9gag.com" 🎉 Notification sent to frays-errant-acting-huddle, you@foo.bar
-
Change the default configuration path for any command with the option
--conf-path
- Specify a directory
--conf-path path/to/conf/directory
and.ntfy.conf
will be created there - Specify a file
--conf-path path/to/file.conf
and that will be used as a configuration file
- Specify a directory
Todo
- Better readme and doc
- CLI
- Screenshots
-
requests
timeout or non-blocking
[^1]: cf xkcd936
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ntfy_wrapper-0.1.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b541f3f1df4d908350ff002a7109a06871e1d15a8b0b24f9c338c6b23a802e60 |
|
MD5 | 95c2498df80dc0e438e915b752e265d9 |
|
BLAKE2b-256 | cb4fae2308617e0a57d094674b690680f64cc415c5dbcea67d7ece5af4d12b94 |