Maintainers
Pricing
Enterprise
More
More
Documentation
Try Live
Rankings
Install
Blog
Docs7
Ask
New
Add Docs
aiontfy
https://tr4nt0r.github.io/aiontfy
Admin
aiontfy is an asynchronous client library for the ntfy pub-sub notification service.
Tokens:
4,699
Snippets:
66
Trust Score:
9.7
Update:
3 months ago
Context
Chat
Benchmark
Latest
Show doc for...
Code
Info
Show Results
Tokens:
Raw
Copy
Link
Tokens:
Raw
Copy
Link
### Install aiontfy via pip Source: https://tr4nt0r.github.io/aiontfy Install the aiontfy library using pip. This is the standard method for adding Python packages to your project. ```bash pip install aiontfy ``` -------------------------------- ### Subscribe to ntfy Topics Source: https://tr4nt0r.github.io/aiontfy Example of subscribing to one or more ntfy topics and processing incoming notifications. A callback function is used to handle received messages. Supports filtering by priority. ```python """Subscribe to ntfy topics.""" import asyncio from aiohttp import ClientSession from aiontfy import Event, Notification, Ntfy def callback(message: Notification) -> None: """Process notifications callback function.""" if message.event is Event.MESSAGE: print(message.to_dict()) async def main() -> None: async with ClientSession() as session: ntfy = Ntfy("https://ntfy.sh", session) await ntfy.subscribe( ["aiontfy", "test"], # Subscribe to multiple topics callback, priority=[3, 4, 5], # Only subscribe to priority >= 3 ) asyncio.run(main()) ``` -------------------------------- ### Publish a Message to ntfy Source: https://tr4nt0r.github.io/aiontfy Example of publishing a message to a ntfy topic using aiontfy. Requires an active aiohttp ClientSession. The Message object allows customization of title, body, priority, tags, and more. ```python """Publish to a ntfy topic.""" import asyncio from aiohttp import ClientSession from aiontfy import Message, Ntfy async def main() -> None: async with ClientSession() as session: ntfy = Ntfy("https://ntfy.sh", session) message = Message( topic="aiontfy", title="Hello", message="World", click="https://example.com/", delay="10s", priority=3, tags=["octopus"], ) print(await ntfy.publish(message)) asyncio.run(main()) ``` -------------------------------- ### `Ntfy.__init__` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Initializes the Ntfy client with a base URL and an optional aiohttp ClientSession. ```APIDOC ## `Ntfy.__init__` ### Description Initialize Ntfy client. ### Parameters #### Path Parameters - **url** (str) - Required - The base URL for the Ntfy service. - **session** (ClientSession) - Optional - An existing aiohttp ClientSession. If not provided, a new session will be created. ``` -------------------------------- ### Serve MkDocs documentation locally Source: https://tr4nt0r.github.io/aiontfy/CONTRIBUTING Serve the MkDocs documentation locally to preview changes. This command is useful for checking documentation updates before committing. ```bash hatch run docs-serve ``` -------------------------------- ### Run all unit tests Source: https://tr4nt0r.github.io/aiontfy/CONTRIBUTING Execute all unit tests for the project using the Hatch build tool. This command ensures code quality and correctness. ```bash hatch run test ``` -------------------------------- ### Clone the aiontfy repository Source: https://tr4nt0r.github.io/aiontfy/CONTRIBUTING Fork the aiontfy repository on GitHub and clone your fork locally to begin development. ```bash git clone git@github.com:yourusername/aiontfy.git ``` -------------------------------- ### Publish a new version (patch) Source: https://tr4nt0r.github.io/aiontfy/CONTRIBUTING Bump the version of the project by a patch increment, create a commit, and associate a tag with the new version using Hatch. ```bash hatch version patch ``` -------------------------------- ### Publish a new version (minor) Source: https://tr4nt0r.github.io/aiontfy/CONTRIBUTING Bump the version of the project by a minor increment, create a commit, and associate a tag with the new version using Hatch. ```bash hatch version minor ``` -------------------------------- ### Create a new branch for development Source: https://tr4nt0r.github.io/aiontfy/CONTRIBUTING Create a new branch for local development to isolate your changes. Use a descriptive name for bug fixes or new features. ```bash git checkout -b name-of-your-bugfix-or-feature ``` -------------------------------- ### Publish a new version (major) Source: https://tr4nt0r.github.io/aiontfy/CONTRIBUTING Bump the version of the project by a major increment, create a commit, and associate a tag with the new version using Hatch. ```bash hatch version major ``` -------------------------------- ### __aenter__ Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Async enter method for context management. Returns the Ntfy client instance for use within an async context manager. ```APIDOC ## __aenter__ async ### Description Async enter. ### Returns #### Success Response (Self) - The Ntfy client instance. ``` -------------------------------- ### Apply linting and check typing Source: https://tr4nt0r.github.io/aiontfy/CONTRIBUTING Run the linting process and type checking for the code using Hatch. This command helps maintain code style and identify potential type errors. ```bash hatch run lint ``` -------------------------------- ### __aexit__ Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Async exit method for context management. Handles cleanup, including closing the aiohttp ClientSession if it was created by this instance. ```APIDOC ## __aexit__ async ### Description Async exit. Closes the aiohttp ClientSession if it was created by this instance. ### Parameters #### Path Parameters - **exc_info** (object) - Exception information. ``` -------------------------------- ### `Ntfy.account` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Retrieves account information for the authenticated client. ```APIDOC ## `Ntfy.account` ### Description Get account information. ### Returns #### Success Response - **Account** (Account) - An instance of the `Account` class containing account information. ### Raises - **NtfyUnauthorizedAuthenticationError** - If the client is not authorized to access the account information. ``` -------------------------------- ### version Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Retrieves the server version. This method is intended for administrative use and provides information about the ntfy server's current version. ```APIDOC ## version async ### Description Get server version (admin-only). ### Returns #### Success Response (Version) - An instance of the `Version` class containing ntfy server version. ``` -------------------------------- ### `Ntfy.can_subscribe` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Checks if the client has the necessary permissions to subscribe to the specified topics. ```APIDOC ## `Ntfy.can_subscribe` ### Description Check if the client can subscribe to a topic. ### Parameters #### Path Parameters - **topics** (list of str) - Required - A list of topic names to check subscription permissions for. ### Returns #### Success Response - **bool** - True if the client can subscribe to the given topics. ### Raises - **NtfyForbiddenAccessError** - If the client is not authorized to subscribe to the given topics. ``` -------------------------------- ### Sound StrEnum Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Defines the available notification sounds. It is a StrEnum. ```APIDOC ## Sound Bases: `StrEnum` Notification sound. ``` -------------------------------- ### Reservation Dataclass Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Defines the settings for topic reservations. It inherits from DataClassORJSONMixin. ```APIDOC ## Reservation dataclass Bases: `DataClassORJSONMixin` Topic reservation settings. ``` -------------------------------- ### `Ntfy.generate_token` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Generates a new token for the account with an optional label and expiration date. ```APIDOC ## `Ntfy.generate_token` ### Description Generate a token for the account. ### Parameters #### Request Body - **label** (str) - Optional - A label for the token, defaults to None. - **expires** (datetime) - Optional - The expiration date and time for the token. If not provided, the token will not expire. ### Returns #### Success Response - **AccountTokenResponse** (AccountTokenResponse) - An instance of `AccountTokenResponse` containing the generated token details. ### Raises - **NtfyUnauthorizedAuthenticationError** - If the client is not authenticated. ``` -------------------------------- ### `Ntfy.subscribe` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Subscribes to one or more ntfy topics and provides a callback function to handle incoming notifications. ```APIDOC ## `Ntfy.subscribe` ### Description Subscribe to one or more ntfy topics. ### Parameters #### Request Body - **topics** (list[str]) - Required - A list of topic names to subscribe to. - **callback** (Callable[[Notification], None]) - Required - A callback function that will be called when a new notification is received. The callback function should accept a single argument of type `Notification`. - **title** (str) - Optional - Filter: Only return messages that match this exact message string, defaults to None. - **message** (str) - Optional - Filter: Only return messages that match this exact title string, defaults to None. - **tags** (list[str]) - Optional - Filter: Only return messages that match all listed tags, defaults to None. - **priority** (int) - Optional - Filter: Only return messages that match any priority listed, defaults to None. ### Raises - **NtfyTimeoutError** - If a timeout occurs during the subscription. - **NtfyConnectionError** - If a client error occurs during the subscription. ``` -------------------------------- ### Version Dataclass Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Represents the version information of the ntfy system. It inherits from DataClassORJSONMixin. ```APIDOC ## Version dataclass Bases: `DataClassORJSONMixin` Version response. ``` -------------------------------- ### Priority IntEnum Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Defines the priority levels for messages within the ntfy system. It is an IntEnum. ```APIDOC ## Priority Bases: `IntEnum` Message priority. ``` -------------------------------- ### `Ntfy.publish` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Publishes a message to an ntfy topic. The message can include details like topic, title, and content. ```APIDOC ## `Ntfy.publish` ### Description Publish a message to an ntfy topic. ### Parameters #### Request Body - **message** (Message) - Required - The message to be published, containing details such as topic, title, and content. ### Returns #### Success Response - **Notification** (Notification) - A `Notification` object representing the response from the ntfy service. ### Raises - **NtfyTimeoutError** - If a timeout occurs during the request. - **NtfyConnectionError** - If a client error occurs during the request. ``` -------------------------------- ### `Ntfy.stats` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Retrieves message statistics from the ntfy service. ```APIDOC ## `Ntfy.stats` ### Description Get message statistics. ### Returns #### Success Response - **Stats** (Stats) - An instance of the `Stats` class containing message statistics. ``` -------------------------------- ### HttpAction Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Represents an HTTP action that can be triggered by a notification. It allows specifying the URL, HTTP method, headers, and body for the request, and can optionally clear the notification upon success. ```APIDOC ## HttpAction ### Description An Http ntfy action. ### Attributes - **label** (str) - Required - Label of the action button in the notification. - **url** (URL) - Required - URL to which the HTTP request will be sent. - **method** (str, optional) - HTTP method to use for request, default is POST. - **headers** (dict[str, str] or None, optional) - HTTP headers to pass in request. - **body** (str or None, optional) - HTTP body. - **clear** (bool, optional) - Clear notification after HTTP request succeeds. If the request fails, the notification is not cleared. ``` -------------------------------- ### close Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Closes the client session. Ensures that the aiohttp ClientSession is properly closed if it was created by this instance. ```APIDOC ## close async ### Description Close session. Closes the aiohttp ClientSession if it is not already closed. ``` -------------------------------- ### Message Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Represents a message to be published to ntfy. This includes the target topic, message content, title, tags, priority, and various action and delivery options. ```APIDOC ## Message ### Description A message to publish to ntfy. ### Attributes - **topic** (str) - Required - Target topic name. - **message** (str or None, optional) - Message body; set to triggered if empty or not passed. - **title** (str or None, optional) - Message title. Defaults to the topic short URL (ntfy.sh/mytopic) if not set. - **tags** (list[str], optional) - List of tags that may or may not map to emojis (https://docs.ntfy.sh/emojis/). - **priority** (int or None, optional) - Message priority with 1=min, 3=default and 5=max. - **actions** (list[ViewAction or BroadcastAction or HttpAction or CopyAction], optional) - Custom user action buttons for notifications. - **click** (URL or None, optional) - Website opened when notification is clicked. - **attach** (URL or None, optional) - URL of an attachment. - **markdown** (bool, optional) - Set to true if the message is Markdown-formatted. - **icon** (URL or None, optional) - URL to use as notification icon. - **filename** (str or None, optional) - File name of the attachment. - **delay** (str or None, optional) - Timestamp or duration for delayed delivery. - **email** (str or None, optional) - E-mail address for e-mail notifications. - **call** (str or None, optional) - Phone number to use for voice call. - **sequence_id** (str or None, optional) - Sequence ID for updating/deleting notifications ### Methods #### `__post_init__` Post-initialization processing to validate attributes. Raises: - `ValueError` - If the priority is not between the minimum and maximum allowed values. #### `to_x_headers` Serialize the dataclass as a dict with X- keys (e.g., X-Message, X-Title). ``` -------------------------------- ### reservation Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Reserves or changes the reservation status of a topic. This method allows clients to manage topic reservations, ensuring exclusive access or modifying existing reservation states. ```APIDOC ## reservation async ### Description Reserve or change the reservation status of a topic. ### Parameters #### Path Parameters - **topic** (str) - Required - The topic to reserve. - **everyone** (str) - Required - The reservation status to set for the topic. ### Returns #### Success Response (bool) - True if successful. ``` -------------------------------- ### ViewAction Dataclass Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Represents an action button displayed within a notification. It inherits from DataClassORJSONMixin. ```APIDOC ## ViewAction dataclass Bases: `DataClassORJSONMixin` A view ntfy action. Attributes: Name | Type | Description ---|---|--- `label` | `str` | Label of the action button in the notification. `url` | `URL` | URL to open when action is tapped. `clear` | `(bool, optional)` | Clear notification after action button is tapped. ``` -------------------------------- ### Response Dataclass Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Represents a successful response from an API operation. It inherits from DataClassORJSONMixin. ```APIDOC ## Response dataclass Bases: `DataClassORJSONMixin` Success response. ``` -------------------------------- ### `Ntfy.clear` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Clears a notification by marking it as read and dismissing it from the notification drawer. ```APIDOC ## `Ntfy.clear` ### Description Clear a notification. Clearing a notification means marking it as read and dismissing it from the notification drawer. ### Parameters #### Path Parameters - **topic** (str) - Required - The topic from which to clear a notification. - **sequence_id** (str) - Required - The sequence-ID to identify the notification to be cleared. ### Raises - **NtfyTimeoutError** - If a timeout occurs during the request. - **NtfyConnectionError** - If a client error occurs during the request. ``` -------------------------------- ### `Ntfy.delete` Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Deletes a notification, removing it from the notification drawer and the client's database. ```APIDOC ## `Ntfy.delete` ### Description Delete a notification. Deleting a notification means removing it from the notification drawer and from the client's database. ### Parameters #### Path Parameters - **topic** (str) - Required - The topic from which to delete a notification. - **sequence_id** (str) - Required - The sequence-ID to identify the notification to be deleted. ### Raises - **NtfyTimeoutError** - If a timeout occurs during the request. - **NtfyConnectionError** - If a client error occurs during the request. ``` -------------------------------- ### Notification Dataclass Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Represents a notification received from a subscribed topic. It inherits from DataClassORJSONMixin. ```APIDOC ## Notification dataclass Bases: `DataClassORJSONMixin` A notification received from a subscribed topic. ``` -------------------------------- ### Stats Dataclass Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Contains statistics related to message processing. It inherits from DataClassORJSONMixin. ```APIDOC ## Stats dataclass Bases: `DataClassORJSONMixin` Stats response. Attributes: Name | Type | Description ---|---|--- `messages` | `int` | The total number of messages. `messages_rate` | `float` | Average number of messages per second. ``` -------------------------------- ### delete_reservation Source: https://tr4nt0r.github.io/aiontfy/reference/aiontfy Deletes a topic reservation. This method can optionally remove all cached messages and attachments associated with the reservation. ```APIDOC ## delete_reservation async ### Description Delete a topic reservation. ### Parameters #### Path Parameters - **topic** (str) - Required - The name of the topic whose reservation is to be deleted. - **delete_messages** (bool) - Optional - If True, deletes all messages and attachments that are cached on the server otherwise they will become publicly available. Defaults to False. ### Returns #### Success Response (bool) - True if the reservation was successfully deleted, False otherwise. ### Raises #### NtfyUnauthorizedAuthenticationError - If the client is not authenticated or the reservation does not exist. ```
