desktop_notifier.common
=======================

.. py:module:: desktop_notifier.common

.. autoapi-nested-parse::

   This module defines base classes for desktop notifications.



Attributes
----------

.. autoapisummary::

   desktop_notifier.common.DEFAULT_ICON
   desktop_notifier.common.DEFAULT_SOUND


Exceptions
----------

.. autoapisummary::

   desktop_notifier.common.AuthorisationError


Classes
-------

.. autoapisummary::

   desktop_notifier.common.FileResource
   desktop_notifier.common.Resource
   desktop_notifier.common.Icon
   desktop_notifier.common.Attachment
   desktop_notifier.common.Sound
   desktop_notifier.common.Urgency
   desktop_notifier.common.Button
   desktop_notifier.common.ReplyField
   desktop_notifier.common.Notification
   desktop_notifier.common.Capability


Module Contents
---------------

.. py:class:: FileResource

   A file resource represented by a URI or path

   Only one of :attr:`path` or :attr:`uri` can be set.


   .. py:attribute:: path
      :type:  pathlib.Path | None
      :value: None


      Path to a local file



   .. py:attribute:: uri
      :type:  str | None
      :value: None


      URI reference to a file



   .. py:method:: as_uri()

      Returns the represented resource as a URI string



   .. py:method:: as_path()

      Returns the represented resource as a Path

      Note that any information about the URI scheme is lost on conversion.



.. py:class:: Resource

   Bases: :py:obj:`FileResource`


   A resource represented by a resource name, URI or path

   Only one of :attr:`path`, :attr:`uri` or :attr:`name` can be set.


   .. py:attribute:: name
      :type:  str | None
      :value: None


      Name of the system resource



   .. py:method:: is_named()

      Returns whether the instance was initialized with ``name``



   .. py:method:: is_file()

      Returns whether the instance was initialized with ``path`` or ``uri``



.. py:class:: Icon

   Bases: :py:obj:`Resource`


   An icon represented by an icon name, URI or path


.. py:class:: Attachment

   Bases: :py:obj:`FileResource`


   An attachment represented by a URI or path


.. py:class:: Sound

   Bases: :py:obj:`Resource`


   A sound represented by a sound name, URI or path


.. py:data:: DEFAULT_ICON
   :type:  Icon

   Python icon


.. py:data:: DEFAULT_SOUND
   :type:  Sound

   Default system notification sound


.. py:exception:: AuthorisationError

   Bases: :py:obj:`Exception`


   Raised when we are not authorised to send notifications


.. py:class:: Urgency

   Bases: :py:obj:`enum.Enum`


   Enumeration of notification levels

   The interpretation and visuals depend on the platform.


   .. py:attribute:: Critical
      :value: 'critical'


      For critical errors.



   .. py:attribute:: Normal
      :value: 'normal'


      Default platform notification level.



   .. py:attribute:: Low
      :value: 'low'


      Low priority notification.



.. py:class:: Button

   A button for interactive notifications


   .. py:attribute:: title
      :type:  str

      The localized button title



   .. py:attribute:: on_pressed
      :type:  Callable[[], Any] | None
      :value: None


      Method to call when the button is pressed



   .. py:attribute:: identifier
      :type:  str
      :value: ''


      A unique identifier to use in callbacks to specify with button was clicked



.. py:class:: ReplyField

   A text field for interactive notifications


   .. py:attribute:: title
      :type:  str
      :value: 'Reply'


      A title for the field itself. On macOS, this will be the title of a button to
      show the field.



   .. py:attribute:: button_title
      :type:  str
      :value: 'Send'


      The title of the button to send the reply



   .. py:attribute:: on_replied
      :type:  Callable[[str], Any] | None
      :value: None


      Method to call when the 'reply' button is pressed



.. py:class:: Notification

   A desktop notification

   Some properties of a notification may be ignored or interpreted differently
   depending on the platform.

   Callbacks for interactions will be executed on the Python process that scheduled the
   notification and only as long as the DesktopNotifier instance that scheduled the
   notification still exists.

   Install handlers on the DesktopNotifier instance itself to respond to interactions
   with notification from your app while it was not running.


   .. py:attribute:: title
      :type:  str

      Notification title



   .. py:attribute:: message
      :type:  str

      Notification message



   .. py:attribute:: urgency
      :type:  Urgency

      Notification urgency. Can determine stickiness, notification appearance and
      break through silencing.



   .. py:attribute:: icon
      :type:  Icon | None
      :value: None


      Icon to use for the notification



   .. py:attribute:: buttons
      :type:  tuple[Button, Ellipsis]
      :value: ()


      Buttons shown on an interactive notification



   .. py:attribute:: reply_field
      :type:  ReplyField | None
      :value: None


      Text field shown on an interactive notification. This can be used for example
      for messaging apps to reply directly from the notification.



   .. py:attribute:: on_dispatched
      :type:  Callable[[], Any] | None
      :value: None


      Method to call when the notification was sent to the notifications server for display



   .. py:attribute:: on_clicked
      :type:  Callable[[], Any] | None
      :value: None


      Method to call when the notification is clicked



   .. py:attribute:: on_dismissed
      :type:  Callable[[], Any] | None
      :value: None


      Method to call when the notification is dismissed



   .. py:attribute:: attachment
      :type:  Attachment | None
      :value: None


      A file attached to the notification which may be displayed as a preview



   .. py:attribute:: sound
      :type:  Sound | None
      :value: None


      A sound to play on notification



   .. py:attribute:: thread
      :type:  str | None
      :value: None


      An identifier to group related notifications together, e.g., from a chat space



   .. py:attribute:: timeout
      :type:  int
      :value: -1


      Duration in seconds for which the notification is shown



   .. py:attribute:: identifier
      :type:  str
      :value: ''


      A unique identifier for this notification. Generated automatically if not
      passed by the client.



.. py:class:: Capability

   Bases: :py:obj:`enum.Enum`


   Notification capabilities that can be supported by a platform


   .. py:attribute:: APP_NAME

      Supports setting a custom app name



   .. py:attribute:: TITLE

      Supports setting a notification title



   .. py:attribute:: MESSAGE

      Supports setting a notification message



   .. py:attribute:: URGENCY

      Supports different urgency levels



   .. py:attribute:: ICON

      Supports custom notification icons



   .. py:attribute:: ICON_FILE

      Supports setting a custom icon from a user-provided file



   .. py:attribute:: ICON_NAME

      Supports setting a named system icon as notification icon



   .. py:attribute:: BUTTONS

      Supports at least two notification buttons



   .. py:attribute:: REPLY_FIELD

      Supports reply fields



   .. py:attribute:: ATTACHMENT

      Supports notification attachments. Allowed file types vary by platform.



   .. py:attribute:: ON_DISPATCHED

      Supports on-dispatched callbacks



   .. py:attribute:: ON_CLICKED

      Supports on-clicked callbacks



   .. py:attribute:: ON_DISMISSED

      Supports on-dismissed callbacks



   .. py:attribute:: SOUND

      Supports custom notification sounds



   .. py:attribute:: SOUND_FILE

      Supports setting a custom sound from a user-provided file



   .. py:attribute:: SOUND_NAME

      Supports setting a named system sound as notification sound



   .. py:attribute:: THREAD

      Supports grouping notifications by topic thread



   .. py:attribute:: TIMEOUT

      Supports notification timeouts