desktop_notifier.main ===================== .. py:module:: desktop_notifier.main .. autoapi-nested-parse:: Asynchronous desktop notification API Classes ------- .. autoapisummary:: desktop_notifier.main.DesktopNotifier Module Contents --------------- .. py:class:: DesktopNotifier(app_name = 'Python', app_icon = DEFAULT_ICON, notification_limit = None) Cross-platform desktop notification emitter Uses different backends depending on the platform version and available services. All implementations will dispatch notifications without an event loop but will require a running event loop to execute callbacks when the end user interacts with a notification. On Linux, an asyncio event loop is required. On macOS, a CFRunLoop *in the main thread* is required. Packages such as :mod:`rubicon.objc` can be used to integrate asyncio with a CFRunLoop. Callbacks to handle user interactions with a notification can be specified either at the class level, where they take the notification identifier as input, or directly on the notification itself. The latter will take precedence if set. Note that handlers that are directly set on the notification are tied to Python notification instance and therefore the app's lifecycle. Handlers that are set on the class level may run also for interactions with a notification while the app was not running, if DesktopNotifier is instantiated at app startup. :param app_name: Name to identify the application in the notification center. On Linux, this should correspond to the application name in a desktop entry. On macOS, this argument is ignored and the app is identified by the bundle ID of the sending program (e.g., Python). :param app_icon: Default icon to use for notifications. This should be a :class:`desktop_notifier.base.Icon` instance referencing either a file or a named system icon. :class:`str` or :class:`pathlib.Path` are also accepted but deprecated. .. py:property:: app_name :type: str The application name .. py:property:: app_icon :type: desktop_notifier.common.Icon | None The application icon .. py:method:: request_authorisation() :async: Requests authorisation to send user notifications. This will be automatically called for you when sending a notification for the first time. It also can be called manually to request authorisation in advance. On some platforms such as macOS and iOS, a prompt will be shown to the user when this method is called for the first time. This method does nothing on platforms where user authorisation is not required. :returns: Whether authorisation has been granted. .. py:method:: has_authorisation() :async: Returns whether we have authorisation to send notifications. .. py:method:: send_notification(notification) :async: Sends a desktop notification. This method does not raise an exception when scheduling the notification fails but logs warnings instead. Note that even a successfully scheduled notification may not be displayed to the user, depending on their notification center settings (for instance if "do not disturb" is enabled on macOS). :param notification: The notification to send. :returns: An identifier for the scheduled notification. .. py:method:: send(title, message, urgency = Urgency.Normal, icon = None, buttons = (), reply_field = None, on_dispatched = None, on_clicked = None, on_dismissed = None, attachment = None, sound = None, thread = None, timeout = -1) :async: Sends a desktop notification This is a convenience function which creates a :class:`desktop_notifier.base.Notification` with the provided arguments and then calls :meth:`send_notification`. :returns: An identifier for the scheduled notification. .. py:method:: get_current_notifications() :async: Returns identifiers of all currently displayed notifications for this app. .. py:method:: clear(identifier) :async: Removes the given notification from the notification center. :param identifier: Notification identifier. .. py:method:: clear_all() :async: Removes all currently displayed notifications for this app from the notification center. .. py:method:: get_capabilities() :async: Returns which functionality is supported by the implementation. .. py:property:: on_dispatched :type: Callable[[str], Any] | None A method to call when a notification is sent to the notifications server The method must take the notification identifier as a single argument. If the notification itself already specifies an on_dispatched handler, it will be used instead of the class-level handler. .. py:property:: on_clicked :type: Callable[[str], Any] | None A method to call when a notification is clicked The method must take the notification identifier as a single argument. If the notification itself already specifies an on_clicked handler, it will be used instead of the class-level handler. .. py:property:: on_dismissed :type: Callable[[str], Any] | None A method to call when a notification is dismissed The method must take the notification identifier as a single argument. If the notification itself already specifies an on_dismissed handler, it will be used instead of the class-level handler. .. py:property:: on_button_pressed :type: Callable[[str, str], Any] | None A method to call when one of the notification's buttons is clicked The method must take the notification identifier and the button identifier as arguments. If the notification button itself already specifies an on_pressed handler, it will be used instead of the class-level handler. .. py:property:: on_replied :type: Callable[[str, str], Any] | None A method to call when a user responds through the reply field of a notification The method must take the notification identifier and input text as arguments. If the notification's reply field itself already specifies an on_replied handler, it will be used instead of the class-level handler.