API Reference¶

python_ntfy._ntfy.NtfyClient ¶

NtfyClient(topic: str, server: str = 'https://ntfy.sh')

A class for interacting with the ntfy notification service.

Itinialize the NtfyClient.

Parameters:

Name	Type	Description	Default
`topic`	`str`	The topic to use for this client	required
`server`	`str`	The server to connect to. Must include the protocol (http/https)	`'https://ntfy.sh'`

Returns:

Type	Description
`None`	None

Examples:

client = NtfyClient(topic="my_topic")

get_topic ¶

get_topic() -> str

Get the current topic.

Returns:

Name	Type	Description
`str`	`str`	The current topic.

set_topic ¶

set_topic(topic: str) -> None

Set a new topic for the client.

Parameters:

Name	Type	Description	Default
`topic`	`str`	The topic to set for this client.	required

Returns:

Type	Description
`None`	None

ActionType ¶

Bases: Enum

Action button types.

Attributes:

Name	Type	Description
`VIEW`		A view action button.
`BROADCAST`		A broadcast action button.
`HTTP`		An HTTP action button.

BroadcastAction ¶

BroadcastAction(
    label: str,
    intent: str = "io.heckel.ntfy.USER_ACTION",
    extras: Optional[dict[str, str]] = None,
    clear: bool = False,
)

Bases: Action

A broadcast action button.

The broadcast action sends an Android broadcast intent when the action button is tapped.

Initialize a BroadcastAction.

Parameters:

Name	Type	Description	Default
`label`	`str`	Label of the action button in the notification.	required
`intent`	`str`	Android intent name.	`'io.heckel.ntfy.USER_ACTION'`
`extras`	`Optional[dict[str, str]]`	Android intent extras.	`None`
`clear`	`bool`	Clear notification after action button is tapped.	`False`

HttpAction ¶

HttpAction(
    label: str,
    url: str,
    method: str = "POST",
    headers: Optional[dict[str, str]] = None,
    body: Optional[str] = None,
    clear: bool = False,
)

Bases: Action

An HTTP action button.

The http action sends a HTTP request when the action button is tapped.

Initialize an HttpAction.

Parameters:

Name	Type	Description	Default
`label`	`str`	Label of the action button in the notification.	required
`url`	`str`	URL to open when action is tapped.	required
`method`	`str`	HTTP method to use for request.	`'POST'`
`headers`	`Optional[dict[str, str]]`	HTTP headers to send with the request.	`None`
`body`	`Optional[str]`	HTTP body to send with the request.	`None`
`clear`	`bool`	Clear notification after HTTP request succeeds. If the request fails, the notification is not cleared.	`False`

MessagePriority ¶

Bases: Enum

Ntfy message priority levels.

Attributes:

Name	Type	Description
`MIN`		The minimum priority.
`LOW`		A low priority.
`DEFAULT`		The default priority.
`HIGH`		A high priority.
`MAX`		The maximum priority.
`URGENT`		The maximum priority.

ViewAction ¶

ViewAction(label: str, url: str, clear: bool = False)

Bases: Action

A view action button.

The view action opens a website or app when the action button is tapped.

Initialize a ViewAction.

Parameters:

Name	Type	Description	Default
`label`	`str`	Label of the action button in the notification.	required
`url`	`str`	URL to open when action is tapped.	required
`clear`	`bool`	Clear notification after action button is tapped.	`False`

send ¶

send(
    self,
    message: str,
    title: Optional[str] = None,
    priority: MessagePriority = MessagePriority.DEFAULT,
    tags: Optional[list] = None,
    actions: Optional[
        list[Union[ViewAction, BroadcastAction, HttpAction]]
    ] = None,
    schedule: Optional[datetime] = None,
    format_as_markdown: bool = False,
    timeout_seconds: int = 5,
) -> dict

Send a text-based message to the server.

Call this function to send a message to the server. The message will be sent to the server and then broadcast to all clients subscribed to the topic.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to send.	required
`title`	`Optional[str]`	The title of the message.	`None`
`priority`	`MessagePriority`	The priority of the message.	`DEFAULT`
`tags`	`Optional[list]`	A list of tags to attach to the message. Can be an emoji short code.	`None`
`actions`	`Optional[list[Union[ViewAction, BroadcastAction, HttpAction]]]`	A list of Actions objects to attach to the message.	`None`
`schedule`	`Optional[datetime]`	The time to schedule the message to be sent.	`None`
`format_as_markdown`	`bool`	If true, the message will be formatted as markdown.	`False`
`additional_topics`		A list of additional topics to send the message to.	required
`timeout_seconds`	`int`	The number of seconds to wait before timing out the reqest to the server.	`5`

Returns:

Name	Type	Description
`dict`	`dict`	The response from the server.

Examples:

>>> response = client.send(message="Example message")

>>> response = client.send(message="Example message", title="Example title", priority=MessagePriority.HIGH, tags=["fire", "warning"])

>>> response = client.send(message="*Example markdown*", format_as_markdown=True)

send_file ¶

send_file(
    self,
    file: str,
    title: Optional[str] = None,
    priority: MessagePriority = MessagePriority.DEFAULT,
    tags: Optional[list] = None,
    actions: Optional[
        list[Union[ViewAction, BroadcastAction, HttpAction]]
    ] = None,
    schedule: Optional[datetime] = None,
    timeout_seconds: int = 30,
) -> dict

Sends a file to the server.

Parameters:

Name	Type	Description	Default
`file`	`str`	The path to the file to send.	required
`title`	`Optional[str]`	The title of the file.	`None`
`priority`	`MessagePriority`	The priority of the message. Optional, defaults to MessagePriority.	`DEFAULT`
`tags`	`Optional[list]`	A list of tags to attach to the message. Can be an emoji short code.	`None`
`actions`	`Optional[list[Union[ViewAction, BroadcastAction, HttpAction]]]`	A list of ActionButton objects to attach to the message.	`None`
`schedule`	`Optional[datetime]`	The time to schedule the message to be sent. Must be more than 10 seconds away and less than 3 days in the future.	`None`
`timeout_seconds`	`int`	The number of seconds to wait before timing out.	`30`

Returns:

Name	Type	Description
`dict`	`dict`	The response from the server.

Examples:

>>> response = client.send_file(file="example.txt")

get_cached_messages ¶

get_cached_messages(
    self,
    since: str = "all",
    scheduled: bool = False,
    timeout_seconds: int = 10,
) -> list[dict]

Get cached messages from the server.

Parameters:

Name	Type	Description	Default
`since`	`str`	The timestamp to start from. If set to "all", will return all messages.	`'all'`
`scheduled`	`bool`	If true, will return scheduled messages.	`False`
`timeout_seconds`	`int`	The number of seconds to wait for the response.	`10`

Returns:

Type	Description
`list[dict]`	A list of messages.

Examples:

>>> response = client.get(since="all")

>>> response = client.get(since="all", scheduled=True)

>>> response = client.get(since="2019-01-01")

>>> response = client.get(since="2019-01-01", scheduled=True)