0
# Core Notification API
1

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

4
## Capabilities
5

6
### DesktopNotifier (Async API)
7

8
The main asynchronous notification API class that provides non-blocking notification operations with full callback support requiring a running event loop.
9

10
```python { .api }
11
class DesktopNotifier:
12
    def __init__(
13
        self, 
14
        app_name: str = "Python", 
15
        app_icon: Icon | None = DEFAULT_ICON, 
16
        notification_limit: int | None = None
17
    ) -> None:
18
        """
19
        Initialize desktop notifier.
20
        
21
        Parameters:
22
        - app_name: Name to identify the application in notification center
23
        - app_icon: Default icon for notifications
24
        - notification_limit: Deprecated, no longer has effect
25
        """
26
    
27
    @property
28
    def app_name(self) -> str:
29
        """The application name"""
30
    
31
    @app_name.setter  
32
    def app_name(self, value: str) -> None: ...
33
    
34
    @property
35
    def app_icon(self) -> Icon | None:
36
        """The application icon"""
37
    
38
    @app_icon.setter
39
    def app_icon(self, value: Icon | None) -> None: ...
40
```
41

42
### Authorization Management
43

44
Methods for requesting and checking notification permissions, automatically handling platform-specific authorization requirements.
45

46
```python { .api }
47
async def request_authorisation(self) -> bool:
48
    """
49
    Request authorization to send notifications.
50
    
51
    On platforms like macOS/iOS, shows permission dialog on first call.
52
    Automatically called when sending first notification.
53
    
54
    Returns:
55
    bool: Whether authorization was granted
56
    """
57

58
async def has_authorisation(self) -> bool:
59
    """
60
    Check if authorized to send notifications.
61
    
62
    Returns:
63
    bool: Current authorization status
64
    """
65
```
66

67
### Notification Sending
68

69
Core methods for dispatching notifications with comprehensive parameter support and automatic platform adaptation.
70

71
```python { .api }
72
async def send(
73
    self,
74
    title: str,
75
    message: str,
76
    urgency: Urgency = Urgency.Normal,
77
    icon: Icon | None = None,
78
    buttons: Sequence[Button] = (),
79
    reply_field: ReplyField | None = None,
80
    on_dispatched: Callable[[], Any] | None = None,
81
    on_clicked: Callable[[], Any] | None = None,
82
    on_dismissed: Callable[[], Any] | None = None,
83
    attachment: Attachment | None = None,
84
    sound: Sound | None = None,
85
    thread: str | None = None,
86
    timeout: int = -1
87
) -> str:
88
    """
89
    Send desktop notification with all options.
90
    
91
    Parameters:
92
    - title: Notification title
93
    - message: Notification message body
94
    - urgency: Priority level (Critical, Normal, Low)
95
    - icon: Custom notification icon
96
    - buttons: Interactive buttons (up to platform limit)
97
    - reply_field: Text input field for user responses
98
    - on_dispatched: Callback when notification is sent
99
    - on_clicked: Callback when notification is clicked
100
    - on_dismissed: Callback when notification is dismissed
101
    - attachment: File attachment for preview
102
    - sound: Notification sound
103
    - thread: Grouping identifier for related notifications
104
    - timeout: Display duration in seconds (-1 for system default)
105
    
106
    Returns:
107
    str: Unique notification identifier
108
    """
109

110
async def send_notification(self, notification: Notification) -> str:
111
    """
112
    Send a Notification object.
113
    
114
    Parameters:
115
    - notification: Pre-constructed Notification instance
116
    
117
    Returns:
118
    str: Unique notification identifier
119
    """
120
```
121

122
### Notification Management
123

124
Methods for querying, clearing, and managing active notifications in the system notification center.
125

126
```python { .api }
127
async def get_current_notifications(self) -> list[str]:
128
    """
129
    Get identifiers of all currently displayed notifications for this app.
130
    
131
    Returns:
132
    list[str]: List of notification identifiers
133
    """
134

135
async def clear(self, identifier: str) -> None:
136
    """
137
    Remove specific notification from notification center.
138
    
139
    Parameters:
140
    - identifier: Notification identifier from send() or send_notification()
141
    """
142

143
async def clear_all(self) -> None:
144
    """
145
    Remove all currently displayed notifications for this app.
146
    """
147
```
148

149
### Capability Detection
150

151
Method for querying platform-specific feature support to enable adaptive behavior across different operating systems.
152

153
```python { .api }
154
async def get_capabilities(self) -> frozenset[Capability]:
155
    """
156
    Query which features are supported by current platform.
157
    
158
    Returns:
159
    frozenset[Capability]: Set of supported capability flags
160
    """
161
```
162

163
### Global Callback Properties
164

165
Class-level callback handlers that apply to all notifications when individual notification callbacks are not specified.
166

167
```python { .api }
168
@property
169
def on_dispatched(self) -> Callable[[str], Any] | None:
170
    """
171
    Global callback when notification is sent to notification server.
172
    Handler receives notification identifier as argument.
173
    """
174

175
@on_dispatched.setter
176
def on_dispatched(self, handler: Callable[[str], Any] | None) -> None: ...
177

178
@property  
179
def on_clicked(self) -> Callable[[str], Any] | None:
180
    """
181
    Global callback when notification is clicked.
182
    Handler receives notification identifier as argument.
183
    """
184

185
@on_clicked.setter
186
def on_clicked(self, handler: Callable[[str], Any] | None) -> None: ...
187

188
@property
189
def on_dismissed(self) -> Callable[[str], Any] | None:
190
    """
191
    Global callback when notification is dismissed.
192
    Handler receives notification identifier as argument.
193
    """
194

195
@on_dismissed.setter
196
def on_dismissed(self, handler: Callable[[str], Any] | None) -> None: ...
197

198
@property
199
def on_button_pressed(self) -> Callable[[str, str], Any] | None:
200
    """
201
    Global callback when notification button is pressed.
202
    Handler receives notification identifier and button identifier as arguments.
203
    """
204

205
@on_button_pressed.setter
206
def on_button_pressed(self, handler: Callable[[str, str], Any] | None) -> None: ...
207

208
@property
209
def on_replied(self) -> Callable[[str, str], Any] | None:
210
    """
211
    Global callback when user replies via reply field.
212
    Handler receives notification identifier and reply text as arguments.
213
    """
214

215
@on_replied.setter
216
def on_replied(self, handler: Callable[[str, str], Any] | None) -> None: ...
217
```
218

219
### DesktopNotifierSync (Sync API)
220

221
Synchronous wrapper providing blocking equivalents of all DesktopNotifier methods for use in non-async contexts.
222

223
```python { .api }
224
class DesktopNotifierSync:
225
    def __init__(
226
        self, 
227
        app_name: str = "Python", 
228
        app_icon: Icon | None = DEFAULT_ICON, 
229
        notification_limit: int | None = None
230
    ) -> None:
231
        """
232
        Initialize synchronous desktop notifier.
233
        
234
        Warning: Callbacks may not work on macOS/Linux without running event loop.
235
        
236
        Parameters: Same as DesktopNotifier
237
        """
238
    
239
    # Properties (same as DesktopNotifier)
240
    @property
241
    def app_name(self) -> str: ...
242
    
243
    @app_name.setter
244
    def app_name(self, value: str) -> None: ...
245
    
246
    @property  
247
    def app_icon(self) -> Icon | None: ...
248
    
249
    @app_icon.setter
250
    def app_icon(self, value: Icon | None) -> None: ...
251
    
252
    # Methods (blocking versions of DesktopNotifier methods)
253
    def request_authorisation(self) -> bool: ...
254
    def has_authorisation(self) -> bool: ...
255
    def send(self, title: str, message: str, **kwargs) -> str: ...
256
    def send_notification(self, notification: Notification) -> str: ...
257
    def get_current_notifications(self) -> list[str]: ...
258
    def clear(self, identifier: str) -> None: ...
259
    def clear_all(self) -> None: ...
260
    def get_capabilities(self) -> frozenset[Capability]: ...
261
    
262
    # Global callback properties (same interface as DesktopNotifier)
263
    @property
264
    def on_dispatched(self) -> Callable[[str], Any] | None: ...
265
    
266
    @on_dispatched.setter  
267
    def on_dispatched(self, handler: Callable[[str], Any] | None) -> None: ...
268
    
269
    # ... (all other callback properties same as DesktopNotifier)
270
```
271

272
## Usage Examples
273

274
### Basic Async Usage
275

276
```python
277
import asyncio
278
from desktop_notifier import DesktopNotifier
279

280
async def main():
281
    notifier = DesktopNotifier(app_name="My App")
282
    
283
    # Check authorization
284
    if not await notifier.has_authorisation():
285
        authorized = await notifier.request_authorisation()
286
        if not authorized:
287
            print("Notification permission denied")
288
            return
289
    
290
    # Send notification
291
    notification_id = await notifier.send(
292
        title="Task Complete",
293
        message="Your background task has finished successfully"
294
    )
295
    
296
    print(f"Sent notification: {notification_id}")
297

298
asyncio.run(main())
299
```
300

301
### Sync API Usage
302

303
```python
304
from desktop_notifier import DesktopNotifierSync
305

306
# Create synchronous notifier
307
notifier = DesktopNotifierSync(app_name="My App")
308

309
# Send notification (blocks until complete)
310
notification_id = notifier.send(
311
    title="Sync Notification", 
312
    message="This was sent synchronously"
313
)
314

315
print(f"Sent notification: {notification_id}")
316
```
317

318
### Event Loop Integration (macOS)
319

320
```python
321
import asyncio
322
import platform
323

324
# Required for macOS callback support
325
if platform.system() == "Darwin":
326
    from rubicon.objc.eventloop import EventLoopPolicy
327
    asyncio.set_event_loop_policy(EventLoopPolicy())
328

329
async def main():
330
    notifier = DesktopNotifier(app_name="Event Loop App")
331
    
332
    # Set global callbacks
333
    notifier.on_clicked = lambda nid: print(f"Notification {nid} clicked")
334
    notifier.on_dismissed = lambda nid: print(f"Notification {nid} dismissed")
335
    
336
    await notifier.send("Test", "Click or dismiss me!")
337
    
338
    # Keep event loop running to handle callbacks
339
    await asyncio.sleep(30)
340

341
asyncio.run(main())
342
```