or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-api.mdenums-constants.mdindex.mdnotification-components.mdresources.md
tile.json

tessl/pypi-desktop-notifier

Python library for cross-platform desktop notifications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/desktop-notifier@6.2.x

To install, run

npx @tessl/cli install tessl/pypi-desktop-notifier@6.2.0

index.mddocs/

Desktop Notifier

A comprehensive Python library for cross-platform desktop notifications. Desktop Notifier enables developers to send interactive notifications across Windows, Linux, macOS, iOS, and iPadOS, with support for advanced features including clickable callbacks, multiple action buttons, reply fields, notification sounds, thread grouping, and platform-specific capabilities detection.

Package Information

  • Package Name: desktop-notifier
  • Language: Python
  • Installation: pip install desktop-notifier

Core Imports

from desktop_notifier import DesktopNotifier, DesktopNotifierSync

Common imports for notification components:

from desktop_notifier import (
    Notification, Button, ReplyField, 
    Icon, Sound, Attachment, Urgency,
    DEFAULT_ICON, DEFAULT_SOUND, Capability
)

Basic Usage

import asyncio
from desktop_notifier import DesktopNotifier

async def main():
    # Create notifier instance
    notifier = DesktopNotifier(app_name="My App")
    
    # Send simple notification
    await notifier.send(
        title="Hello World",
        message="This is a desktop notification from Python!"
    )
    
    # Send interactive notification with buttons and reply field
    from desktop_notifier import Button, ReplyField, Urgency, DEFAULT_SOUND
    
    await notifier.send(
        title="Interactive Notification",
        message="Click buttons or reply below",
        urgency=Urgency.Critical,
        buttons=[
            Button(title="OK", on_pressed=lambda: print("OK clicked")),
            Button(title="Cancel", on_pressed=lambda: print("Cancel clicked"))
        ],
        reply_field=ReplyField(
            title="Reply",
            button_title="Send",
            on_replied=lambda text: print(f"User replied: {text}")
        ),
        sound=DEFAULT_SOUND,
        on_clicked=lambda: print("Notification clicked"),
        on_dismissed=lambda: print("Notification dismissed")
    )

# For async usage
asyncio.run(main())

# For synchronous usage
from desktop_notifier import DesktopNotifierSync

sync_notifier = DesktopNotifierSync(app_name="My App")
sync_notifier.send("Hello", "Synchronous notification!")

Architecture

Desktop Notifier uses a backend architecture that automatically selects the appropriate platform-specific implementation:

  • Linux: DBus backend using org.freedesktop.Notifications service
  • macOS/iOS: Cocoa backend using UNUserNotificationCenter framework
  • Windows: WinRT backend using Windows.UI.Notifications
  • Fallback: Dummy backend for unsupported platforms

This design provides cross-platform compatibility while leveraging native platform APIs for optimal integration and feature support. The library gracefully handles unsupported features without raising exceptions, allowing code to work across all platforms.

Capabilities

Core Notification API

Primary notification classes providing both asynchronous and synchronous interfaces for sending desktop notifications with full platform integration and callback support.

class DesktopNotifier:
    def __init__(self, app_name: str = "Python", app_icon: Icon | None = DEFAULT_ICON, notification_limit: int | None = None): ...
    async def send(self, title: str, message: str, **kwargs) -> str: ...
    async def send_notification(self, notification: Notification) -> str: ...
    async def request_authorisation(self) -> bool: ...
    async def has_authorisation(self) -> bool: ...
    async def get_current_notifications(self) -> list[str]: ...
    async def clear(self, identifier: str) -> None: ...
    async def clear_all(self) -> None: ...
    async def get_capabilities(self) -> frozenset[Capability]: ...

class DesktopNotifierSync:
    def __init__(self, app_name: str = "Python", app_icon: Icon | None = DEFAULT_ICON, notification_limit: int | None = None): ...
    def send(self, title: str, message: str, **kwargs) -> str: ...
    def send_notification(self, notification: Notification) -> str: ...
    # ... (all methods from DesktopNotifier but synchronous)

Core Notification API

Notification Components

Data classes and types for constructing rich, interactive notifications with buttons, reply fields, media attachments, and custom styling options.

@dataclass(frozen=True)
class Notification:
    title: str
    message: str
    urgency: Urgency = Urgency.Normal
    icon: Icon | None = None
    buttons: tuple[Button, ...] = ()
    reply_field: ReplyField | None = None
    attachment: Attachment | None = None
    sound: Sound | None = None
    # ... additional fields

@dataclass(frozen=True)
class Button:
    title: str
    on_pressed: Callable[[], Any] | None = None
    identifier: str = field(default_factory=uuid_str)

@dataclass(frozen=True)
class ReplyField:
    title: str = "Reply"
    button_title: str = "Send"
    on_replied: Callable[[str], Any] | None = None

Notification Components

Resource Management

Classes for managing icons, sounds, and file attachments with support for both file paths, URIs, and system-named resources across different platforms.

@dataclass(frozen=True)
class Icon(Resource):
    path: Path | None = None
    uri: str | None = None
    name: str | None = None
    def as_uri(self) -> str: ...
    def as_path(self) -> Path: ...
    def as_name(self) -> str: ...

@dataclass(frozen=True)
class Sound(Resource):
    # Same interface as Icon
    
@dataclass(frozen=True)
class Attachment(FileResource):
    path: Path | None = None
    uri: str | None = None
    def as_uri(self) -> str: ...
    def as_path(self) -> Path: ...

Resource Management

Enumerations and Constants

Urgency levels, capability flags, and default resource constants for customizing notification behavior and querying platform support.

class Urgency(Enum):
    Critical = "critical"
    Normal = "normal"
    Low = "low"

class Capability(Enum):
    APP_NAME = auto()
    TITLE = auto()
    MESSAGE = auto()
    URGENCY = auto()
    ICON = auto()
    BUTTONS = auto()
    REPLY_FIELD = auto()
    ATTACHMENT = auto()
    SOUND = auto()
    THREAD = auto()
    TIMEOUT = auto()
    # ... additional capabilities

DEFAULT_ICON: Icon
DEFAULT_SOUND: Sound

Enumerations and Constants