0
# Enumerations and Constants
1
2
Urgency levels, capability flags, and default resource constants for customizing notification behavior and querying platform support.
3
4
## Capabilities
5
6
### Urgency
7
8
Enumeration defining notification urgency levels that affect display behavior, stickiness, and system integration.
9
10
```python { .api }
11
class Urgency(Enum):
12
Critical = "critical"
13
"""
14
Critical urgency level for important system alerts.
15
16
- May bypass do-not-disturb settings
17
- Often displayed with prominent visual styling (red, flashing)
18
- Typically remains visible until explicitly dismissed
19
- Used for: System errors, security alerts, urgent messages
20
"""
21
22
Normal = "normal"
23
"""
24
Normal urgency level for standard notifications.
25
26
- Default urgency level if not specified
27
- Standard system notification appearance and behavior
28
- Respects user's do-not-disturb and notification settings
29
- Auto-dismisses after system timeout period
30
- Used for: Regular app notifications, informational messages
31
"""
32
33
Low = "low"
34
"""
35
Low urgency level for informational notifications.
36
37
- Less prominent visual styling
38
- May be suppressed during focused work modes
39
- Shorter display timeout on some platforms
40
- Used for: Background task completion, non-critical updates
41
"""
42
```
43
44
### Capability
45
46
Enumeration of notification features supported across different platforms, used for capability detection and adaptive behavior.
47
48
```python { .api }
49
class Capability(Enum):
50
APP_NAME = auto()
51
"""Support for custom application name in notifications"""
52
53
TITLE = auto()
54
"""Support for notification title text"""
55
56
MESSAGE = auto()
57
"""Support for notification message body text"""
58
59
URGENCY = auto()
60
"""Support for urgency level specification (Critical, Normal, Low)"""
61
62
ICON = auto()
63
"""Support for custom notification icons"""
64
65
ICON_FILE = auto()
66
"""Support for file-based notification icons (path/URI)"""
67
68
ICON_NAME = auto()
69
"""Support for system-named notification icons"""
70
71
BUTTONS = auto()
72
"""Support for interactive notification buttons"""
73
74
REPLY_FIELD = auto()
75
"""Support for text input fields in notifications"""
76
77
ATTACHMENT = auto()
78
"""Support for file attachments with preview"""
79
80
ON_DISPATCHED = auto()
81
"""Support for dispatch event callbacks"""
82
83
ON_CLICKED = auto()
84
"""Support for notification click callbacks"""
85
86
ON_DISMISSED = auto()
87
"""Support for notification dismissal callbacks"""
88
89
SOUND = auto()
90
"""Support for custom notification sounds"""
91
92
SOUND_FILE = auto()
93
"""Support for file-based notification sounds"""
94
95
SOUND_NAME = auto()
96
"""Support for system-named notification sounds"""
97
98
THREAD = auto()
99
"""Support for notification grouping/threading"""
100
101
TIMEOUT = auto()
102
"""Support for custom notification timeout durations"""
103
```
104
105
### Default Constants
106
107
Pre-configured resource constants providing sensible defaults for common notification scenarios.
108
109
```python { .api }
110
DEFAULT_ICON: Icon
111
"""
112
Default Python icon included with the desktop-notifier package.
113
114
This icon is used when no custom icon is specified for the DesktopNotifier
115
instance or individual notifications. Points to a bundled Python logo icon
116
suitable for cross-platform use.
117
"""
118
119
DEFAULT_SOUND: Sound
120
"""
121
Default system notification sound appropriate for the current platform.
122
123
Resolves to:
124
- macOS: System default notification sound
125
- Windows: Default Windows notification sound
126
- Linux: Default freedesktop notification sound
127
- Other platforms: System default or silent fallback
128
"""
129
```
130
131
## Usage Examples
132
133
### Capability Detection
134
135
```python
136
from desktop_notifier import DesktopNotifier, Capability
137
import asyncio
138
139
async def check_platform_capabilities():
140
notifier = DesktopNotifier(app_name="Capability Test")
141
142
# Get all supported capabilities for current platform
143
capabilities = await notifier.get_capabilities()
144
145
print("Supported features on this platform:")
146
for capability in capabilities:
147
print(f" - {capability.name}")
148
149
# Check for specific features
150
if Capability.BUTTONS in capabilities:
151
print("✓ Interactive buttons are supported")
152
else:
153
print("✗ Interactive buttons not supported")
154
155
if Capability.REPLY_FIELD in capabilities:
156
print("✓ Reply fields are supported")
157
else:
158
print("✗ Reply fields not supported")
159
160
if Capability.ATTACHMENT in capabilities:
161
print("✓ File attachments are supported")
162
else:
163
print("✗ File attachments not supported")
164
165
asyncio.run(check_platform_capabilities())
166
```
167
168
### Adaptive Notification Behavior
169
170
```python
171
from desktop_notifier import DesktopNotifier, Capability, Urgency, Button
172
import asyncio
173
174
async def send_adaptive_notification():
175
notifier = DesktopNotifier(app_name="Adaptive App")
176
capabilities = await notifier.get_capabilities()
177
178
# Base notification
179
title = "Task Complete"
180
message = "Your data processing job has finished successfully"
181
urgency = Urgency.Normal
182
183
# Add buttons only if supported
184
buttons = []
185
if Capability.BUTTONS in capabilities:
186
buttons = [
187
Button(title="View Results", on_pressed=lambda: print("Opening results")),
188
Button(title="Dismiss", on_pressed=lambda: print("Dismissed"))
189
]
190
191
# Add sound only if supported
192
sound = None
193
if Capability.SOUND in capabilities:
194
from desktop_notifier import DEFAULT_SOUND
195
sound = DEFAULT_SOUND
196
197
# Send notification with platform-appropriate features
198
await notifier.send(
199
title=title,
200
message=message,
201
urgency=urgency,
202
buttons=buttons,
203
sound=sound,
204
on_clicked=lambda: print("Notification clicked") if Capability.ON_CLICKED in capabilities else None
205
)
206
207
asyncio.run(send_adaptive_notification())
208
```
209
210
### Urgency Level Examples
211
212
```python
213
from desktop_notifier import DesktopNotifier, Urgency
214
import asyncio
215
216
async def demonstrate_urgency_levels():
217
notifier = DesktopNotifier(app_name="Urgency Demo")
218
219
# Low priority notification (background task)
220
await notifier.send(
221
title="Backup Complete",
222
message="Scheduled backup finished at 2:30 AM",
223
urgency=Urgency.Low
224
)
225
226
# Normal priority notification (default)
227
await notifier.send(
228
title="Email Received",
229
message="New message from your colleague",
230
urgency=Urgency.Normal # Can be omitted as it's default
231
)
232
233
# Critical priority notification (urgent action needed)
234
await notifier.send(
235
title="Security Alert",
236
message="Unusual login attempt detected from new location",
237
urgency=Urgency.Critical,
238
timeout=0, # Make it sticky
239
buttons=[
240
Button(title="Review", on_pressed=lambda: print("Opening security review")),
241
Button(title="Block", on_pressed=lambda: print("Blocking suspicious activity"))
242
]
243
)
244
245
asyncio.run(demonstrate_urgency_levels())
246
```
247
248
### Using Default Resources
249
250
```python
251
from desktop_notifier import DesktopNotifier, DEFAULT_ICON, DEFAULT_SOUND
252
from desktop_notifier import Icon, Sound
253
from pathlib import Path
254
255
# Using package defaults
256
notifier_with_defaults = DesktopNotifier(
257
app_name="Default Resources App",
258
app_icon=DEFAULT_ICON # Uses bundled Python icon
259
)
260
261
# Custom notifier with fallback to defaults
262
custom_icon_path = Path("./app-icon.png")
263
app_icon = Icon(path=custom_icon_path) if custom_icon_path.exists() else DEFAULT_ICON
264
265
notifier_with_fallback = DesktopNotifier(
266
app_name="Fallback App",
267
app_icon=app_icon
268
)
269
270
# Send notification with default sound
271
async def send_with_defaults():
272
await notifier_with_defaults.send(
273
title="Using Defaults",
274
message="This notification uses the default Python icon and system sound",
275
sound=DEFAULT_SOUND
276
)
277
278
import asyncio
279
asyncio.run(send_with_defaults())
280
```
281
282
### Platform-Specific Capability Mapping
283
284
```python
285
import platform
286
from desktop_notifier import DesktopNotifier, Capability
287
import asyncio
288
289
async def show_platform_differences():
290
notifier = DesktopNotifier(app_name="Platform Info")
291
capabilities = await notifier.get_capabilities()
292
293
system = platform.system()
294
print(f"\nNotification capabilities on {system}:")
295
296
# Common capabilities across platforms
297
always_supported = {
298
Capability.APP_NAME, Capability.TITLE, Capability.MESSAGE,
299
Capability.URGENCY, Capability.ON_DISPATCHED
300
}
301
302
# Platform-specific feature availability
303
platform_features = {
304
"Darwin": { # macOS
305
"Strong support": [Capability.BUTTONS, Capability.REPLY_FIELD,
306
Capability.ATTACHMENT, Capability.SOUND_NAME],
307
"Limited support": [Capability.TIMEOUT],
308
"No support": []
309
},
310
"Windows": { # Windows 10+
311
"Strong support": [Capability.BUTTONS, Capability.ATTACHMENT,
312
Capability.SOUND_NAME, Capability.THREAD],
313
"Limited support": [Capability.REPLY_FIELD],
314
"No support": [Capability.TIMEOUT]
315
},
316
"Linux": { # freedesktop.org compliant
317
"Strong support": [Capability.ICON_NAME, Capability.TIMEOUT,
318
Capability.URGENCY],
319
"Limited support": [Capability.BUTTONS, Capability.SOUND_NAME],
320
"No support": [Capability.REPLY_FIELD, Capability.ATTACHMENT]
321
}
322
}
323
324
if system in platform_features:
325
for support_level, features in platform_features[system].items():
326
print(f"\n{support_level}:")
327
for feature in features:
328
status = "✓" if feature in capabilities else "✗"
329
print(f" {status} {feature.name}")
330
331
asyncio.run(show_platform_differences())
332
```