ntfy_wrapper

Submodules

Package Contents

Classes

Notifier

The main class in ntfy-wrapper.

Attributes

__version__

class ntfy_wrapper.Notifier(topics=None, emails=None, base_url=None, notify_defaults={}, conf_path=None, write=True, warnings=True, verbose=True)

The main class in ntfy-wrapper. A Notifier(…) will handle both the configuration file and the notifications.

Constructor for the Notifier class.

Its spirit is to reduce redundancy as much as possible. This is why its configuration is saved in a file by default.

It comes with sane defaults so ntfy = Notifier() is enough to get started!

Warning

Remember that a topic is much like a password: anyone with that string can subscribe to your notifications so it’s probably best you do not track any piece of code containing your topics. That includes the configuration file this class creates automatically (except if write is False).

Parameters

  • topics (Optional[Union[str, List[str]]], optional) – String, or list of strings describing the default target topics to publish to using https://ntfy.sh. Remember that a topic is much like a password: anyone with that string can subscribe to your notifications so it’s probably best you do not track any piece of code containing your topics. That includes the configuration file this class creates automatically (except if write is False). Defaults to None, meaning a random (uuid) topic will be generated for you, and re-used next time, provided you have enabled write.

  • emails (Optional[Union[str, List[str]]], optional) – String, or list of strings describing the emails to send notifications to by default. Be aware of the rate limits: https://ntfy.sh/docs/publish/#limitations Defaults to None.

  • base_url (Optional[str], optional) – String or list of strings describing the base url to use and send notifications to. It defaults to None, i.e. https://ntfy.sh but you can set it to a self-hosted ntfy instance for example. base_url can be a list of comma-separated urls, in which case they will all be notified.

  • notify_defaults (Optional[Dict], optional) – Dict whose keys and values will be default keyword arguments for the Notifier.notify() method so that you don’t have to write the same stuff again and again throughout your code. Defaults to {}.

  • conf_path (Optional[Union[str, Path]], optional) – String or pathlib.Path pointing to where the Notifier should get or create its INI configuration file. Defaults to None, meaning $CWD/.ntfy.conf.

  • write (Optional[bool], optional) – Whether to write the Notifier’s config if a new topic has to be created because none pre-exist. Defaults to True.

  • warnings (Optional[bool], optional) – Whether or not to print warnings, in particular the version control warning if write is True (by default). Defaults to True.

  • verbose (Optional[bool], optional) – Whether to describe the Notifier after its initialization from your args and the (potentially non-existing) conf. Defaults to True.

__call__(*args, **kwds)

Alias for Notifier.notify().

Parameters

  • args (Any) –

  • kwds (Any) –

Return type

Any

_warn(message)

Print a warning message if warnings are enabled.

Parameters

message (str) – The message to print.

Return type

None

describe()

Describe the notifier.

notify(message, topics=None, emails=None, base_url=None, title=None, priority=None, tags=None, click=None, attach=None, actions=None, icon=None, debug=False)

Send a notification to the given topics and emails.

Note

Refer to the ntfy documentation more details about all those options: https://ntfy.sh/docs/publish/

The defaults you may have used in the init() method are used here. You can override them by passing the corresponding arguments.

In other words: arg > self.conf > defaults.

If topics is None, the topics are taken from the configuration file. If emails is not None, the notification is sent by email to the given addresses. If emails have been specified in the configuration file, they are used by default. Set emails="" to disable emails even if there are some in the configuration.

Warning

You cannot send both a string message and a file attachment.

Parameters

  • message (str) – The message to send.

  • topics (Optional[Union[str, List[str]]], optional) – Target topics to notify. Defaults to None.

  • emails (Optional[Union[str, List[str]]], optional) – Target emails to send notifications to. Defaults to None.

  • base_url (Optional[Union[str, List[str]]], optional) – The base URL to use for the API. Can be a coma-separated list of URLs. Defaults to None, i.e. https://ntfy.sh if base_url is neither an arg nor in the config.

  • title (Optional[str], optional) – The notifications’ title. Defaults to “From ntfy_wrapper”.

  • priority (Optional[int], optional) – The notifications’ priority. Defaults to None.

  • tags (Optional[Union[str, List[str]]], optional) – The notifications’ tags. Defaults to None.

  • click (Optional[str], optional) – URL to open when a notification is clicked. Defaults to None.

  • attach (Optional[str], optional) – Attachment to send: either a local image file or an URL pointing to one. Defaults to None.

  • actions (Optional[Union[str, List[str]]], optional) – A string or list of strings describing actions as per: https://ntfy.sh/docs/publish/#using-a-header Defaults to None.

  • icon (Optional[str], optional) – The notifications’ icon as a URL to a remote file. Defaults to None.

  • debug (Optional[bool], optional) – Whether to print debug information or not. Defaults to False.

Raises

ValueError – The user cannot specify both attach and message

Returns

A list of the targets notifications have been dispatched to:

one for each topic and one for each email.

Return type

List[str]

remove_all_base_urls(write=True)

Remove all base urls from the Notifier’s targets. If write is True, the configuration file is updated.

Parameters

write (Optional[bool], optional) – Whether to update the config file or not. Defaults to True.

remove_all_emails(write=True)

Remove all emails from the Notifier’s targets. If write is True, the configuration file is updated.

Parameters

write (Optional[bool], optional) – Whether to update the config file or not. Defaults to True.

remove_all_topics(write=True)

Remove all emails from the Notifier’s targets. If write is True, the configuration file is updated.

Parameters

write (Optional[bool], optional) – Whether to update the config file or not. Defaults to True.

remove_base_urls(base_urls, write=True)

Remove urls from the Notifier’s targets. If write is True, the configuration file is updated. If an url does not exist, it is ignored.

Parameters

  • base_urls (List[str]) – The base_urls to remove.

  • write (Optional[bool], optional) – Whether to update the config file or not. Defaults to True.

remove_emails(emails, write=True)

Remove emails from the Notifier’s targets. If write is True, the configuration file is updated. If an email does not exist, it is ignored.

Parameters

  • emails (List[str]) – The emails to remove.

  • write (Optional[bool], optional) – Whether to update the config file or not. Defaults to True.

remove_notify_defaults(notify_defaults, write=True)

Remove notify defaults from the Notifier’s configuration. If a key does not exist, it is ignored.

Parameters

  • notify_defaults (List[str]) – The notify defaults to remove.

  • write (bool) –

remove_topics(topics, write=True)

Remove topics from the Notifier’s targets. If write is True, the configuration file is updated. If a topic does not exist, it is ignored.

Parameters

  • topics (List[str]) – The topics to remove.

  • write (Optional[bool], optional) – Whether to update the config file or not. Defaults to True.

update_notify_defaults(notify_defaults, write=True)

Add notify defaults to the Notifier’s configuration. If a key already exists, it is overwritten.

Parameters

  • notify_defaults (Dict[str, Any]) – The notify defaults to add.

  • write (bool) –

write_to_conf()

Write the topics to the configuration file.

ntfy_wrapper.__version__