API Reference¶

python_ntfy.client.NtfyClient ¶

NtfyClient(
    topic: str,
    server: str = "https://ntfy.sh",
    auth: tuple[str, str] | str | None = None,
)

A client for interacting with the ntfy notification service.

Initialize the client.

Parameters:

Name	Type	Description	Default
`topic`	`str`	The topic to use for this client.	required
`server`	`str`	The server base URL (must include protocol, e.g., https://).	`'https://ntfy.sh'`
`auth`	`tuple[str, str] \| str \| None`	Credentials for this client. Takes precedence over environment variables. May be a tuple `(user, password)` for Basic auth or a token string for Bearer auth.	`None`

get_cached_messages ¶

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

Get cached messages from the server.

get_topic ¶

get_topic() -> str

Get the current topic.

send ¶

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

Send a text-based message to the server.

send_file ¶

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

Send a file to the server.

set_topic ¶

set_topic(topic: str) -> None

Set a new topic for this client.

python_ntfy ¶

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`

BroadcastAction ¶

BroadcastAction(
    label: str,
    intent: str = "io.heckel.ntfy.USER_ACTION",
    extras: dict[str, str] | None = 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`	`dict[str, str] \| None`	Android intent extras.	`None`
`clear`	`bool`	Clear notification after action button is tapped.	`False`

HttpAction ¶

HttpAction(
    label: str,
    url: str,
    method: str = "POST",
    headers: dict[str, str] | None = None,
    body: str | None = 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`	`dict[str, str] \| None`	HTTP headers to send with the request.	`None`
`body`	`str \| None`	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`

MessageSendError ¶

MessageSendError(message: str)

Bases: Exception

Exception raised when a message fails to send.

Initialize the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to display.	required