0
# GNTP
1
2
GNTP (Growl Notification Transport Protocol) is a Python library for sending notifications to Growl-compatible notification systems. It provides both simple fire-and-forget notifications and comprehensive notification management with application registration, custom notification types, and support for icons, priorities, and sticky notifications.
3
4
## Package Information
5
6
- **Package Name**: gntp
7
- **Language**: Python
8
- **Installation**: `pip install gntp`
9
10
## Core Imports
11
12
```python
13
import gntp.notifier
14
```
15
16
For configuration-aware usage:
17
18
```python
19
import gntp.config
20
```
21
22
For low-level protocol access:
23
24
```python
25
import gntp.core
26
```
27
28
## Basic Usage
29
30
```python
31
import gntp.notifier
32
33
# Simple fire-and-forget notification
34
gntp.notifier.mini("Here's a quick message")
35
36
# More complete example with application registration
37
growl = gntp.notifier.GrowlNotifier(
38
applicationName="My Application Name",
39
notifications=["New Updates", "New Messages"],
40
defaultNotifications=["New Messages"],
41
# hostname="computer.example.com", # Defaults to localhost
42
# password="abc123" # Defaults to blank password
43
)
44
45
# Register with Growl (required before sending notifications)
46
growl.register()
47
48
# Send a notification
49
growl.notify(
50
noteType="New Messages",
51
title="You have a new message",
52
description="A longer message description",
53
icon="http://example.com/icon.png",
54
sticky=False,
55
priority=1,
56
)
57
```
58
59
## Architecture
60
61
The GNTP library is organized into several modules providing different levels of abstraction:
62
63
- **High-level API** (`gntp.notifier`): Simple notification functions and full-featured GrowlNotifier class
64
- **Configuration API** (`gntp.config`): Config file-aware versions that read settings from ~/.gntp
65
- **Low-level Protocol** (`gntp.core`): Direct GNTP message construction and parsing
66
- **Error Handling** (`gntp.errors`): Comprehensive exception hierarchy for all error conditions
67
- **Command Line Interface** (`gntp.cli`): Full-featured CLI for sending notifications from shell scripts
68
69
This design enables both simple one-line notifications and complex multi-application notification management while maintaining compatibility with older Python Growl bindings.
70
71
## Capabilities
72
73
### High-Level Notification API
74
75
Simple fire-and-forget notifications and full-featured application registration with comprehensive notification management, including custom types, icons, priorities, and callbacks.
76
77
```python { .api }
78
def mini(description, applicationName='PythonMini', noteType="Message",
79
title="Mini Message", applicationIcon=None, hostname='localhost',
80
password=None, port=23053, sticky=False, priority=None,
81
callback=None, notificationIcon=None, identifier=None,
82
notifierFactory=GrowlNotifier): ...
83
84
class GrowlNotifier(object):
85
def __init__(self, applicationName='Python GNTP', notifications=[],
86
defaultNotifications=None, applicationIcon=None,
87
hostname='localhost', password=None, port=23053): ...
88
def register(self): ...
89
def notify(self, noteType, title, description, icon=None, sticky=False,
90
priority=None, callback=None, identifier=None, custom={}): ...
91
def subscribe(self, id, name, port): ...
92
```
93
94
[High-Level API](./high-level-api.md)
95
96
### Configuration-Aware API
97
98
Enhanced notification API that reads default settings from ~/.gntp configuration file, enabling shared configuration across multiple applications and simplified deployment.
99
100
```python { .api }
101
def mini(description, **kwargs): ...
102
103
class GrowlNotifier(gntp.notifier.GrowlNotifier):
104
def __init__(self, *args, **kwargs): ...
105
```
106
107
[Configuration API](./config-api.md)
108
109
### Low-Level Protocol Implementation
110
111
Direct GNTP message construction, parsing, and validation for applications requiring fine-grained control over protocol details, custom message handling, or integration with other notification systems.
112
113
```python { .api }
114
class GNTPRegister:
115
def __init__(self, data=None, password=None): ...
116
def add_notification(self, name, enabled=True): ...
117
def encode(self): ...
118
119
class GNTPNotice:
120
def __init__(self, data=None, app=None, name=None, title=None, password=None): ...
121
def encode(self): ...
122
123
def parse_gntp(data, password=None): ...
124
```
125
126
[Low-Level Protocol](./protocol.md)
127
128
### Error Handling
129
130
Comprehensive exception hierarchy covering all GNTP error conditions including network failures, authentication errors, parsing issues, and unsupported operations.
131
132
```python { .api }
133
class BaseError(Exception): ...
134
class ParseError(BaseError): ...
135
class AuthError(BaseError): ...
136
class UnsupportedError(BaseError): ...
137
class NetworkError(BaseError): ...
138
```
139
140
[Error Handling](./errors.md)
141
142
### Command Line Interface
143
144
Full-featured command-line interface for sending GNTP notifications from shell scripts and system automation, supporting all notification parameters and configuration file integration.
145
146
```python { .api }
147
def main(): ...
148
149
class ClientParser(OptionParser):
150
def __init__(self): ...
151
def parse_args(self, args=None, values=None): ...
152
```
153
154
[Command Line Interface](./cli.md)
155
156
## Types
157
158
```python { .api }
159
# Configuration dictionary for ~/.gntp file
160
GNTPConfig = dict # Keys: hostname, password, port
161
162
# Custom notification attributes (key-value pairs)
163
CustomAttributes = dict # Keys should be prefixed with X- per GNTP spec
164
165
# Password hash algorithms
166
PasswordHashAlgorithm = str # Values: 'MD5', 'SHA1', 'SHA256', 'SHA512'
167
168
# Priority levels
169
Priority = int # Range: -2 to 2
170
171
# Port number
172
Port = int # Default: 23053
173
174
# Notification data
175
NotificationData = bytes # For binary resources like images
176
```