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
```