0
# Desktop Notifier
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: desktop-notifier
7
- **Language**: Python
8
- **Installation**: `pip install desktop-notifier`
9

10
## Core Imports
11

12
```python
13
from desktop_notifier import DesktopNotifier, DesktopNotifierSync
14
```
15

16
Common imports for notification components:
17

18
```python
19
from desktop_notifier import (
20
    Notification, Button, ReplyField, 
21
    Icon, Sound, Attachment, Urgency,
22
    DEFAULT_ICON, DEFAULT_SOUND, Capability
23
)
24
```
25

26
## Basic Usage
27

28
```python
29
import asyncio
30
from desktop_notifier import DesktopNotifier
31

32
async def main():
33
    # Create notifier instance
34
    notifier = DesktopNotifier(app_name="My App")
35
    
36
    # Send simple notification
37
    await notifier.send(
38
        title="Hello World",
39
        message="This is a desktop notification from Python!"
40
    )
41
    
42
    # Send interactive notification with buttons and reply field
43
    from desktop_notifier import Button, ReplyField, Urgency, DEFAULT_SOUND
44
    
45
    await notifier.send(
46
        title="Interactive Notification",
47
        message="Click buttons or reply below",
48
        urgency=Urgency.Critical,
49
        buttons=[
50
            Button(title="OK", on_pressed=lambda: print("OK clicked")),
51
            Button(title="Cancel", on_pressed=lambda: print("Cancel clicked"))
52
        ],
53
        reply_field=ReplyField(
54
            title="Reply",
55
            button_title="Send",
56
            on_replied=lambda text: print(f"User replied: {text}")
57
        ),
58
        sound=DEFAULT_SOUND,
59
        on_clicked=lambda: print("Notification clicked"),
60
        on_dismissed=lambda: print("Notification dismissed")
61
    )
62

63
# For async usage
64
asyncio.run(main())
65

66
# For synchronous usage
67
from desktop_notifier import DesktopNotifierSync
68

69
sync_notifier = DesktopNotifierSync(app_name="My App")
70
sync_notifier.send("Hello", "Synchronous notification!")
71
```
72

73
## Architecture
74

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

77
- **Linux**: DBus backend using org.freedesktop.Notifications service
78
- **macOS/iOS**: Cocoa backend using UNUserNotificationCenter framework  
79
- **Windows**: WinRT backend using Windows.UI.Notifications
80
- **Fallback**: Dummy backend for unsupported platforms
81

82
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.
83

84
## Capabilities
85

86
### Core Notification API
87

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

90
```python { .api }
91
class DesktopNotifier:
92
    def __init__(self, app_name: str = "Python", app_icon: Icon | None = DEFAULT_ICON, notification_limit: int | None = None): ...
93
    async def send(self, title: str, message: str, **kwargs) -> str: ...
94
    async def send_notification(self, notification: Notification) -> str: ...
95
    async def request_authorisation(self) -> bool: ...
96
    async def has_authorisation(self) -> bool: ...
97
    async def get_current_notifications(self) -> list[str]: ...
98
    async def clear(self, identifier: str) -> None: ...
99
    async def clear_all(self) -> None: ...
100
    async def get_capabilities(self) -> frozenset[Capability]: ...
101

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

109
[Core Notification API](./core-api.md)
110

111
### Notification Components
112

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

115
```python { .api }
116
@dataclass(frozen=True)
117
class Notification:
118
    title: str
119
    message: str
120
    urgency: Urgency = Urgency.Normal
121
    icon: Icon | None = None
122
    buttons: tuple[Button, ...] = ()
123
    reply_field: ReplyField | None = None
124
    attachment: Attachment | None = None
125
    sound: Sound | None = None
126
    # ... additional fields
127

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

134
@dataclass(frozen=True)
135
class ReplyField:
136
    title: str = "Reply"
137
    button_title: str = "Send"
138
    on_replied: Callable[[str], Any] | None = None
139
```
140

141
[Notification Components](./notification-components.md)
142

143
### Resource Management
144

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

147
```python { .api }
148
@dataclass(frozen=True)
149
class Icon(Resource):
150
    path: Path | None = None
151
    uri: str | None = None
152
    name: str | None = None
153
    def as_uri(self) -> str: ...
154
    def as_path(self) -> Path: ...
155
    def as_name(self) -> str: ...
156

157
@dataclass(frozen=True)
158
class Sound(Resource):
159
    # Same interface as Icon
160
    
161
@dataclass(frozen=True)
162
class Attachment(FileResource):
163
    path: Path | None = None
164
    uri: str | None = None
165
    def as_uri(self) -> str: ...
166
    def as_path(self) -> Path: ...
167
```
168

169
[Resource Management](./resources.md)
170

171
### Enumerations and Constants
172

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

175
```python { .api }
176
class Urgency(Enum):
177
    Critical = "critical"
178
    Normal = "normal"
179
    Low = "low"
180

181
class Capability(Enum):
182
    APP_NAME = auto()
183
    TITLE = auto()
184
    MESSAGE = auto()
185
    URGENCY = auto()
186
    ICON = auto()
187
    BUTTONS = auto()
188
    REPLY_FIELD = auto()
189
    ATTACHMENT = auto()
190
    SOUND = auto()
191
    THREAD = auto()
192
    TIMEOUT = auto()
193
    # ... additional capabilities
194

195
DEFAULT_ICON: Icon
196
DEFAULT_SOUND: Sound
197
```
198

199
[Enumerations and Constants](./enums-constants.md)