API Reference¶

This page contains the full reference to this package’s API.

Classes¶

[source]class ntfy_api.actions.BroadcastAction(label: str, intent: str | None = None, extras: Mapping[str, str] | None = None, clear: bool | None = None)¶

Bases: _Action

A serializable broadcast action.

Parameters:

label¶ (str) – The action label.
intent¶ (str | None, optional) – The Android intent name.
extras¶ (Mapping[str, str] | None, optional) – The Android intent extras.
clear¶ (bool | None, optional) – Whether or not to clear the notification after the action is activated.

ivar label: str¶: See the label parameter.

ivar intent: str | None¶: See the intent parameter.

ivar extras: Mapping[str, str] | None¶: See the extras parameter.

ivar clear: bool | None¶: See the clear parameter.

method serialize() → str¶

Serialize this action into a single header value.

Returns:: The serialized header value.
Return type:: str

[source]class ntfy_api.creds.Credentials(basic: str | tuple[str, str] | None = None, bearer: str | None = None)¶

Stores access credentials.

Parameters:

basic¶ (str | tuple[str, str] | None, optional) – Basic HTTP credentials. If a single str is given, it is assumed to already be base64-encoded (encoded from a str of the format <user>:<pass>). If a 2-tuple is given, it should be of the form (<user>, <pass>).
bearer¶ (str | None, optional) – Bearer HTTP credentials. If both basic and bearer are defined, bearer will be used.

ivar basic: str | tuple[str, str] | None¶: See the basic parameter.

ivar bearer: str | None¶: See the bearer parameter.

[source]method get_header() → MappingProxyType¶

Create the authorization header with the given credentials. Result may be empty.

Returns:: The authentication header as an immutable mapping.
Return type:: MappingProxyType[str, str]
Raises:: ValueError – If no valid credentials are present.

[source]class ntfy_api.enums.Event¶

Bases: StrEnum

Represents an event in ReceivedMessage instances.

Bases: _Filter

A filter dataclass that stores filtering preferences used when polling and subscribing.

Parameters:

since¶ (str | int | None) – Return cached messages since timestamp, duration or message ID.
scheduled¶ (bool | None) – Include scheduled/delayed messages in message response.
id¶ (str | None) – Only return messages that match this exact message ID.
message¶ (str | None) – Only return messages that match this exact message string.
title¶ (str | None) – Only return messages that match this exact title string.
priority¶ (int | Iterable[int] | None) – Only return messages that match any priority given.
tags¶ (str | Iterable[str] | None) – Only return messages that match all listed tags.

ivar id: str | None¶: See the id parameter.

ivar message: str | None¶: See the message parameter.

ivar priority: int | Iterable[int] | None¶: See the priority parameter.

ivar scheduled: bool | None¶: See the scheduled parameter.

ivar since: str | int | None¶: See the since parameter.

ivar tags: str | Iterable[str] | None¶: See the tags parameter.

ivar title: str | None¶: See the title parameter.

method serialize() → dict[str, Any]¶: Serialize this filter into a header dictionary.

[source]class ntfy_api.actions.HTTPAction(label: str, url: str, method: str | None = None, headers: Mapping[str, str] | None = None, body: str | None = None, clear: bool | None = None)¶

Bases: _Action

A serializable HTTP action.

Parameters:

label¶ (str) – The action label.
url¶ (str) – The URL to send the HTTP request to.
method¶ (str | None, optional) – The HTTP method.
headers¶ (Mapping[str, str] | None, optional) – The HTTP headers.
body¶ (str | None, optional) – The HTTP body.
clear¶ (bool | None, optional) – Whether or not to clear the notification after the action is activated.

ivar label: str¶: See the label parameter.

ivar url: str¶: See the url parameter.

ivar method: str | None¶: See the method parameter.

ivar headers: Mapping[str, str] | None¶: See the headers parameter.

ivar body: str | None¶: See the body parameter.

ivar clear: bool | None¶: See the clear parameter.

method serialize() → str¶

Serialize this action into a single header value.

Returns:: The serialized header value.
Return type:: str

[source]class ntfy_api.enums.HTTPMethod¶

Bases: StrEnum

Represents an HTTP method (e.g. GET, POST, and so on).

Bases: _Message

Represents a message that will be published via NtfyClient.publish().

Parameters:

topic¶ (str) – The topic this message should be sent to.
message¶ (str) – The message body.
title¶ (str) – The message title.
priority¶ (int) – The message priority.
tags¶ (str | Iterable[str]) – A set of tags that will be displayed along with the message. If the tag is a supported emoji short code (i.e. those found in the Tag enum), they will be displayed to the left of the title. Unrecognized tags will be displayed below the message.
markdown¶ (bool) – Whether or not to render the message with markdown.
delay¶ (int | str) – When to schedule the message. This should be either a unix timestamp or a natural-language date/time or offset (see https://github.com/olebedev/when). Any value between 10 seconds and 3 days may be used.
templating¶ (bool) – If True, data will be interpreted as JSON and used as the template context of Go-styled templates in the message and title. Mutually exclusive with filename.
actions¶ (Iterable[_Action]) – Actions attached to this message.
click¶ (str) – The redirect URL that will be activated when the notification is clicked.
attachment¶ (str) – An externally-hosted attachment to be included in the message.
filename¶ (str) – The filename of the included attachment. If not provided, it will be derived from the URL resource identifier. Mutually exclusive with templating.
icon¶ (str) – An externally-hosted icon that will be displayed next to the notification.
email¶ (str) – The email address to forward this message to.
call¶ (str) – The phone number to forward this message to.
cache¶ (bool) – Whether or not to make use of the message cache.
firebase¶ (bool) – Whether or not to enable Firebase.
unified_push¶ (bool) – Whether or not to enable UnifiedPush.
data¶ (BinaryIO | dict[str, Any]) –
If defined, it should be one of the following:
- If sending a local file as an attachment, the raw
  attachment file data. If doing so, it is recommended to use the filename option in addition to this.
- If using templating, the template data.

ivar topic: str | None¶: See the topic parameter.

ivar message: str | None¶: See the message parameter.

ivar title: str | None¶: See the title parameter.

ivar priority: int | None¶: See the priority parameter.

ivar tags: str | Iterable[str] | None¶: See the tags parameter.

ivar markdown: bool | None¶: See the markdown parameter.

ivar delay: int | str | None¶: See the delay parameter.

ivar templating: bool | None¶: See the templating parameter.

ivar actions: Iterable[_Action] | None¶: See the actions parameter.

ivar click: str | None¶: See the click parameter.

ivar attachment: str | None¶: See the attachment parameter.

ivar filename: str | None¶: See the filename parameter.

ivar icon: str | None¶: See the icon parameter.

ivar email: str | None¶: See the email parameter.

ivar call: str | None¶: See the call parameter.

ivar cache: bool | None¶: See the cache parameter.

ivar firebase: bool | None¶: See the firebase parameter.

ivar unified_push: bool | None¶: See the unified_push parameter.

ivar data: BinaryIO | dict[str, Any] | None¶: See the data parameter.

[source]method get_args() → tuple[str | None, dict[str, str], dict[str, Any]]¶: Get the topic, headers, and POST kwargs.

[source]class ntfy_api.client.NtfyClient(base_url: str, default_topic: str | None = None, credentials: Credentials | None = None)¶

The class that handles publishing Message instances and creation of NtfySubscription instances.

Parameters:

base_url¶ (str) – The base URL of a ntfy server.
default_topic¶ (str, optional) – If provided, it will be used as a fallback topic in cases where no topic is provided in the Message instance being published, or as an argument (publish.topic) to the publish method.
credentials¶ (Credentials, optional) – The user credentials, if any.

ivar base_url: str¶: See the base_url parameter.

ivar default_topic: str | None¶: See the default_topic parameter.

ivar credentials: Credentials | None¶: See the credentials parameter.

[source]method connect(client: Client | None = None) → Self¶

Start a new connection pool.

Parameters:: client¶ (httpx.Client | None, optional) – If defined, uses the provided client. Otherwise, a new one is created.
Returns:: This NtfyClient instance.
Return type:: NtfyClient

[source]method close() → None¶: Close the HTTP connection pool, if it exists.

[source]method publish(msg: Message, topic: str | None = None, topic_override: bool = False) → Response¶

Publish a Message instance.

Note

If no connection pool exists (i.e. connect() wasn’t called and this client is not being used as a context manager), a single-use connection will be used.

Parameters:

msg¶ (Message) – The Message instance containing the content to publish.
topic¶ (str | None, optional) – A topic that will be used if no topic was provided in the given Message object.
topic_override¶ (bool, optional) – A flag that, if set to True, will cause the given topic (if provided) to be used regardless of whether or not a topic is present in the given Message instance.

Returns:

The httpx.Response instance.

Return type:

httpx.Response

Raises:

ValueError – If no topic was provided as an argument, no topic was found in the provided Message instance, and no default_topic was given when creating this NtfyClient instance.

[source]for ... in poll(topic: str | None = None, filter: Filter | None = None) → Generator[ReceivedMessage, None, None]¶

Poll for messages using an HTTP connection.

Note

If no connection pool exists (i.e. connect() wasn’t called and this client is not being used as a context manager), a single-use connection will be used.

Parameters:

topic¶ (str, optional) – The topic to poll. If not provide, this instance’s default topic will be used.
filter¶ (Filter, optional) – An optional Filter instance used to filter responses.

Returns:

A generator of ReceivedMessage instances.

Return type:

Iterator[ReceivedMessage]

Raises:

ValueError – If no topic was provided as an argument, and no default_topic was given when creating this NtfyClient instance.

[source]method subscribe(topics: str | Iterable[str] | None = None, filter: Filter | None = None, max_queue_size: int = 0) → NtfySubscription¶

A factory for NtfySubscription instances, which uses the same base URL and credentials as this NtfyClient instance.

Note

The NtfySubscription instance is created but the connection is not yet started. Use its NtfySubscription.connect() method or the context manager protocol to start receiving messages.

Parameters:

topics¶ (str | Iterable[str] | None) – Zero or more topics to subscribe to. If none are given, this instance’s default topic will be used.
filter¶ (Filter | None) – An optional Filter instance used to filter responses.
max_queue_size¶ (int, optional) – The maximum size of the message queue. If <=0, the queue is unbounded. If the queue is filled, all new messages are discarded. Only when the queue has room for another message, will messages start being added again. This means that, if bounded, some messages may be dropped if the frequency of received messages is greater than your program’s ability to handle those messages. Defaults to 0.

Returns:

The created NtfySubscription instance.

Return type:

NtfySubscription

Raises:

ValueError – If both the subscribe.topics argument and this instance’s default_topic are None.

[source]method __enter__() → Self¶

Enter the context manager protocol.

Returns:: This NtfyClient instance.
Return type:: NtfyClient

[source]method __exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) → Literal[False]¶

Exit the context manager protocol.

This ensures the client is closed.

Returns:: Always False. See object.__exit__() for more information on what this return value means.
Return type:: Literal[False]

[source]class ntfy_api.subscription.NtfySubscription(base_url: str, topics: tuple[str] | tuple[str, ...], credentials: Credentials | None = None, filter: Filter | None = None, max_queue_size: int = 0)¶

The class that handles subscriptions.

Parameters:

base_url¶ – The base URL of a ntfy server.
topics¶ – The topics to subscribe to.
credentials¶ – The user credentials, if any.
filter¶ – Optional response filters.
max_queue_size¶ – The maximum size of the message queue. If <=0, the queue is unbounded. If the queue is filled, all new messages are discarded. Only when the queue has room for another message, will messages start being added again. This means that, if bounded, some messages may be dropped if the frequency of received messages is greater than your program’s ability to handle those messages.

ivar base_url: str¶: See the base_url parameter.

ivar credentials: Credentials | None¶: See the credentials parameter.

ivar filter: Filter | None¶: See the filter parameter.

ivar max_queue_size: int¶: See the max_queue_size parameter.

ivar messages: ClearableQueue[ReceivedMessage]¶

The message queue.

This attribute stores received messages. See queue.Queue for details on how to interact with this attribute.

ivar topics: tuple[str] | tuple[str, ...]¶: See the topics parameter.

[source]method close() → None¶: Close the websocket connection, if it exists.

[source]method connect(connection: ClientConnection | None = None) → Self¶

Initiate the websocket connection.

Note

This also clears messages.

Parameters:: connection¶ (websockets.sync.client.ClientConnection | None, optional) – The websocket connection to use. If not provided, one will be created.
Returns:: This NtfySubscription instance.
Return type:: NtfySubscription

[source]method __enter__() → Self¶

Enter the context manager protocol.

Returns:: The NtfySubscription instance.
Return type:: NtfySubscription

[source]method __exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) → Literal[False]¶

Exit the context manager protocol.

This ensures the client is closed.

Returns:: Always False. See object.__exit__() for more information on what this return value means.
Return type:: Literal[False]

[source]class ntfy_api.enums.Priority¶

Bases: IntEnum

Represents message priority in Message and ReceivedMessage.

[source]class ntfy_api.message.ReceivedAttachment(*args, **kwargs)¶

Bases: Protocol

Protocol defining the interface for an attachment in a received message.

Parameters:

name¶ (str) – Name of the attachment.
url¶ (str) – URL of the attachment.
type¶ (str | None) – Mime type of the attachment (only if uploaded to ntfy server).
size¶ (int | None) – Size in bytes (only if uploaded to ntfy server).
expires¶ (int | None) – Expiry date as Unix timestamp (only if uploaded to ntfy server).

ivar expires: int | None¶: See the expires parameter.

ivar name: str¶: See the name parameter.

ivar size: int | None¶: See the size parameter.

ivar type: str | None¶: See the type parameter.

ivar url: str¶: See the url parameter.

[source]class ntfy_api.actions.ReceivedBroadcastAction(id: str, label: str, clear: bool, intent: str | None = None, extras: dict[str, str] | None = None)¶

Bases: WrappingDataclass

A received broadcast action. Similar to BroadcastAction, but cannot be serialized.

Parameters:

id¶ (str) – The action ID.
label¶ (str) – The action label.
clear¶ (bool) – Whether or not to clear the notification after the action is activated.
intent¶ (str | None, optional) – The Android intent name.
extras¶ (dict[str, str] | None, optional) – The Android intent extras.

ivar id: str¶: See the id parameter.

ivar label: str¶: See the label parameter.

ivar clear: bool¶: See the clear parameter.

ivar intent: str | None¶: See the intent parameter.

ivar extras: dict[str, str] | None¶: See the extras parameter.

classmethod from_json(data: Mapping[str, Any]) → Self¶

Parse a new WrappingDataclass instance from the given data.

Note

data is not modified when wrappers (if any) are applied. Instead, a shallow copy of the mapping is created and used. Keep in mind that, because it is a shallow copy, the wrappers may still modify the mapping values in-place.

Parameters:: data¶ (Mapping[str, Any]) – The JSON-like data.
Returns:: The parsed WrappingDataclass instance.
Return type:: WrappingDataclass

[source]class ntfy_api.actions.ReceivedHTTPAction¶

Bases: WrappingDataclass

A received HTTP action. Similar to HTTPAction, but cannot be serialized.

Parameters:

id¶ (str) – The action ID.
label¶ (str) – The action label.
url¶ (str) – The URL to send the HTTP request to.
clear¶ (bool) – Whether or not to clear the notification after the action is activated.
method¶ (HTTPMethod | None, optional) – The HTTP method.
headers¶ (dict[str, str] | None, optional) – The HTTP headers.
body¶ (str | None, optional) – The HTTP body.

ivar id: str¶: See the id parameter.

ivar label: str¶: See the label parameter.

ivar url: str¶: See the url parameter.

ivar clear: bool¶: See the clear parameter.

ivar method: HTTPMethod | None¶: See the method parameter.

ivar headers: dict[str, str] | None¶: See the headers parameter.

ivar body: str | None¶: See the body parameter.

classmethod from_json(data: Mapping[str, Any]) → Self¶

Parse a new WrappingDataclass instance from the given data.

Note

Parameters:: data¶ (Mapping[str, Any]) – The JSON-like data.
Returns:: The parsed WrappingDataclass instance.
Return type:: WrappingDataclass

[source]class ntfy_api.message.ReceivedMessage¶

Bases: Protocol

Protocol defining the interface for a message received from the ntfy server.

Parameters:

id¶ (str) – Randomly chosen message identifier.
time¶ (int) – Message datetime as Unix timestamp.
event¶ (Event) – Type of event.
topic¶ (str) – Topics the message is associated with.
message¶ (str | None) – Message body.
expires¶ (int | None) – When the message will be deleted.
title¶ (str | None) – Message title.
tags¶ (tuple[Tag, ...] | None) – List of tags that may map to emojis.
priority¶ (Priority | None) – Message priority.
click¶ (str | None) – Website opened when notification is clicked.
actions¶ (tuple[ReceivedAction, ...] | None) – Action buttons that can be displayed.
attachment¶ (ReceivedAttachment | None) – Details about an attachment if present.
icon¶ (str | None) – The icon URL sent with the message.
content_type¶ (str | None) – The content type.

ivar actions: tuple[ReceivedViewAction | ReceivedBroadcastAction | ReceivedHTTPAction, ...] | None¶: See the actions parameter.

ivar attachment: ReceivedAttachment | None¶: See the attachment parameter.

ivar click: str | None¶: See the click parameter.

ivar content_type: str | None¶: See the content_type parameter.

ivar event: Event¶: See the event parameter.

ivar expires: int | None¶: See the expires parameter.

ivar icon: str | None¶: See the icon parameter.

ivar id: str¶: See the id parameter.

ivar message: str | None¶: See the message parameter.

ivar priority: Priority | None¶: See the priority parameter.

ivar tags: tuple[Tag, ...] | None¶: See the tags parameter.

ivar time: int¶: See the time parameter.

ivar title: str | None¶: See the title parameter.

ivar topic: str¶: See the topic parameter.

[source]class ntfy_api.actions.ReceivedViewAction(id: str, label: str, url: str, clear: bool)¶

Bases: WrappingDataclass

A received view action. Similar to ViewAction, but cannot be serialized.

Parameters:

id¶ (str) – The action ID.
label¶ (str) – The action label.
url¶ (str) – The URL to open when the action is activated.
clear¶ (bool) – Whether or not to clear the notification after the action is activated.

ivar id: str¶: See the id parameter.

ivar label: str¶: See the label parameter.

ivar url: str¶: See the url parameter.

ivar clear: bool¶: See the clear parameter.

classmethod from_json(data: Mapping[str, Any]) → Self¶

Parse a new WrappingDataclass instance from the given data.

Note

Parameters:: data¶ (Mapping[str, Any]) – The JSON-like data.
Returns:: The parsed WrappingDataclass instance.
Return type:: WrappingDataclass

[source]class ntfy_api.enums.Tag¶

Bases: StrEnum

Represents message tags in Message and ReceivedMessage.

[source]class ntfy_api.actions.ViewAction(label: str, url: str, clear: bool | None = None)¶

Bases: _Action

A serializable view action.

Parameters:

label¶ (str) – The action label.
url¶ (str) – The URL to open when the action is activated.
clear¶ (bool | None, optional) – Whether or not to clear the notification after the action is activated.

ivar label: str¶: See the label parameter.

ivar url: str¶: See the url parameter.

ivar clear: bool | None¶: See the clear parameter.

method serialize() → str¶

Serialize this action into a single header value.

Returns:: The serialized header value.
Return type:: str