DOCSEARCHbyAlgolia
Submit Docs

notify-py

repository·master·Indexed 43 days ago

https://github.com/ms7m/notify-py

A cross-platform desktop notification library for Python (version 0.3.42) that supports Windows, macOS, and Linux. It allows developers to send notifications with custom titles, messages, icons, and audio files via the Notify class or a command-line interface. The library supports asynchronous delivery with the block=False parameter and allows for custom notification providers by inheriting from BaseNotifier.

Tokens
4.1K
Snippets
19
Records
23
Agent score
54%

What's inside notify-py

  1. Important limitations and caveats

    master

    When using notify-py, be aware of the following limitations:

    • No Custom Actions: There is currently no support for embedding custom actions like buttons or dialogs in notifications, regardless of the platform.
    • No User Feedback: The library can tell you if the shell command to send the notification was successfully triggered, but it cannot confirm if a user actually interacted with the notification.
    • macOS Icon Limitation: As mentioned, macOS requires a custom-built binary to display custom icons; it does not support dynamic icon changes via the API.

  2. Send a native desktop notification with Notify

    master

    To send a native cross-platform desktop notification, import the Notify class from notifypy. Initialize the class, set the title and message attributes, and call the .send() method.

    from notifypy import Notify

notification = Notify()
notification.title = "Cool Title"
notification.message = "Even cooler message."

notification.send()

  3. Configure optional arguments for the Notify object

    master

    When instantiating the notifypy.Notify object, you can provide several optional arguments to customize behavior. These include overriding the detected notification system, enabling library logging, or specifying a custom macOS notificator path.

    from notifypy import Notify

# Example of using optional arguments
notify = Notify(
    override_detected_notification_system=my_custom_notifier,
    enable_logging=True,
    custom_mac_notificator='/path/to/custom/notificator'
)

  4. Prepare a custom macOS notification icon

    master

    macOS restrictions prevent adding custom icons on the fly. To use a custom icon, you must first build a customized version of the notificator application.

    1. Clone the notificator repository:
      git clone https://github.com/vitorgalvao/notificator
    2. Follow the instructions in the notificator README to add your custom icon.
    3. Build the application to generate a .app bundle.
    git clone https://github.com/vitorgalvao/notificator

  5. Build a custom notify.py wheel with a custom macOS icon

    master

    If you want to distribute your custom icon as part of the notify.py package, you can build a custom wheel. This involves replacing the bundled macOS notifier with your custom .app bundle.

    1. Clone the repository:
      git clone https://github.com/ms7m/notify-py
    2. Set up environment:
      python -m venv venv
python3 -m pip install loguru
python3 -m pip install --user --upgrade setuptools wheel
    3. Replace the binary: Copy your custom .app into the notifypy/os_notifiers/binary folder.
    4. Set permissions: Ensure the executable inside notifypy/os_notifiers/binary/Notificator.app/Contents/Resources/Scripts/notificator has execution permissions.
    5. Test: Run a simple script to verify the icon appears:
      import notifypy
n = notifypy.Notify()
n.send()
    6. Build: Generate the wheel:
      python3 setup.py sdist bdist_wheel
      The resulting .whl file will be in the dist/ folder.
    python3 setup.py sdist bdist_wheel

  7. Create a custom notification provider

    master

    You can implement custom notification logic by creating a class that inherits from BaseNotifier. To be compatible with notify.py, your class must implement the send_notification method.

    If you need to pass specific data to your custom provider, include **kwargs in your __init__ and send_notification methods. notify.py will automatically forward any extra arguments provided to the Notify constructor to your custom class.

    from notifypy import BaseNotifier
from notifypy import Notify

class CustomNotifier(BaseNotifier):
    def __init__(self, **kwargs):
        # Handle custom arguments passed via Notify constructor
        self.arg = kwargs.get('custom_notification_arguments')
        pass

    def send_notification(self, **kwargs):
        # Your custom notification logic here
        print("Yes. This works.")
        return True

n = Notify(
    override_detected_notification_system=CustomNotifier,
    # Extra arguments are forwarded to CustomNotifier
    custom_notification_arguments="Bob",
)

n.send()

  8. Platform-specific limitations and caveats

    master

    General

    • No Custom Actions: There is no support for embedding buttons or dialogs in notifications.
    • No User Feedback: The library cannot confirm if a user interacted with the notification.

    macOS

    • Custom Icons: macOS does not support custom icons on the fly. To use a custom icon, you must bundle a customized version of the notifier that has the icon embedded.

    Windows

    • Legacy Windows: No support for balloon tips on versions prior to Windows 10.

  9. Send a simple notification with Notify

    master

    To send a basic notification, instantiate the Notify class, set the title and message attributes, and call the .send() method.

    from notifypy import Notify

notification = Notify()
notification.title = "Cool Title"
notification.message = "Even cooler message."
notification.send()

  10. Send notifications with a custom icon

    master

    You can specify a custom icon for your notification by setting the icon attribute on a Notify instance. Use a .png file for best compatibility across platforms.

    Platform Note: macOS does not support custom icons on the fly. To use a custom icon on macOS, you must bundle a customized version of the notifier binary that already contains your icon.

    from notifypy import Notify

notification = Notify()
notification.title = "Cool Title"
notification.message = "Even cooler message."
notification.icon = "path/to/icon.png"

notification.send()

  11. Send notifications with a custom sound

    master

    To play a specific audio file when a notification is sent, set the audio attribute on the Notify instance with the path to your audio file (e.g., a .wav file).

    from notifypy import Notify

notification = Notify()
notification.title = "Cool Title"
notification.message = "Even cooler message."
notification.audio = "path/to/audio/file.wav"

notification.send()

  12. Send notifications with icons and audio

    master

    You can enhance notifications by providing paths to image and audio files using the icon and audio attributes.

    from notifypy import Notify

# With Icon
notification = Notify()
notification.title = "Cool Title"
notification.message = "Even cooler message."
notification.icon = "path/to/icon.png"
notification.send()

# With Sound
notification = Notify()
notification.title = "Cool Title"
notification.message = "Even cooler message."
notification.audio = "path/to/audio/file.wav"
notification.send()