0
# Configuration-Aware API
1

2
The `gntp.config` module provides enhanced versions of the notification API that automatically read default settings from a configuration file. This enables shared configuration across multiple applications and simplified deployment scenarios.
3

4
## Configuration File
5

6
The configuration API reads settings from `~/.gntp` using the following format:
7

8
```ini
9
[gntp]
10
hostname = growl.example.com
11
password = mypassword
12
port = 23053
13
```
14

15
All settings are optional and fall back to the same defaults as the standard API.
16

17
## Capabilities
18

19
### Configuration-Aware Fire-and-Forget Notifications
20

21
Enhanced version of the `mini()` function that reads default settings from the configuration file.
22

23
```python { .api }
24
def mini(description, **kwargs):
25
    """
26
    Single notification function using config-aware GrowlNotifier.
27
    
28
    Reads default hostname, password, and port from ~/.gntp configuration file.
29
    All parameters from gntp.notifier.mini() are supported.
30
    
31
    Parameters:
32
    - description (str): Notification message (required)
33
    - **kwargs: All parameters supported by gntp.notifier.mini()
34
    
35
    Returns:
36
    bool or tuple: True on success, error tuple on failure
37
    """
38
```
39

40
### Configuration-Aware GrowlNotifier
41

42
Enhanced GrowlNotifier class that reads configuration file settings and merges them with provided parameters.
43

44
```python { .api }
45
class GrowlNotifier(gntp.notifier.GrowlNotifier):
46
    """
47
    ConfigParser enhanced GrowlNotifier object.
48
    
49
    Reads default values from ~/.gntp configuration file before applying
50
    constructor parameters. Configuration file settings are overridden by
51
    explicit constructor arguments.
52
    """
53
    
54
    def __init__(self, *args, **kwargs):
55
        """
56
        Initialize config-aware GrowlNotifier.
57
        
58
        Reads ~/.gntp configuration file and uses those values as defaults.
59
        Explicit constructor arguments override configuration file values.
60
        
61
        Parameters:
62
        Same as gntp.notifier.GrowlNotifier, with config file providing defaults
63
        
64
        Configuration Resolution Order:
65
        1. Built-in defaults (hostname='localhost', port=23053, password=None)
66
        2. ~/.gntp configuration file values
67
        3. Constructor arguments (highest priority)
68
        """
69
```
70

71
## Usage Examples
72

73
### Basic Configuration File Usage
74

75
Create `~/.gntp` configuration file:
76

77
```ini
78
[gntp]
79
hostname = growl.mycompany.com
80
password = company-growl-password
81
port = 23053
82
```
83

84
Then use the configuration API:
85

86
```python
87
import gntp.config
88

89
# Uses settings from ~/.gntp automatically
90
gntp.config.mini("Deployment completed successfully!")
91

92
# Config settings are used as defaults, can be overridden
93
gntp.config.mini(
94
    "Critical error occurred",
95
    hostname="emergency-server.com",  # Overrides config file
96
    priority=2
97
)
98
```
99

100
### Application with Shared Configuration
101

102
```python
103
import gntp.config
104

105
# Create notifier using configuration file defaults
106
app = gntp.config.GrowlNotifier(
107
    applicationName="Web Server Monitor",
108
    notifications=["Server Down", "High Load", "Disk Full"],
109
    defaultNotifications=["Server Down", "Disk Full"]
110
    # hostname, password, port read from ~/.gntp
111
)
112

113
# Register and send notifications
114
app.register()
115

116
app.notify(
117
    "High Load",
118
    "Server Load Warning",
119
    "CPU usage is 89% for the last 5 minutes"
120
)
121
```
122

123
### Mixed Configuration and Runtime Settings
124

125
```python
126
import gntp.config
127

128
# Some settings from config file, others specified at runtime
129
app = gntp.config.GrowlNotifier(
130
    applicationName="Backup System",
131
    notifications=["Backup Started", "Backup Completed", "Backup Failed"],
132
    # Use different server than config file for backup notifications
133
    hostname="backup-alerts.company.com",
134
    # But still use password from config file
135
)
136

137
app.register()
138
app.notify("Backup Started", "Daily Backup", "Starting backup of /home")
139
```
140

141
### Handling Missing Configuration File
142

143
```python
144
import gntp.config
145
import logging
146

147
# The config module gracefully handles missing ~/.gntp file
148
# Falls back to standard defaults if file doesn't exist or has no [gntp] section
149

150
logging.basicConfig(level=logging.INFO)
151

152
# This works even if ~/.gntp doesn't exist
153
gntp.config.mini("Application started")
154

155
# You can check if config was loaded by examining log output
156
# "Info reading ~/.gntp config file" appears if file is missing/invalid
157
```
158

159
### Enterprise Deployment Example
160

161
For enterprise deployments, you can create a standard `~/.gntp` file:
162

163
```ini
164
[gntp]
165
hostname = notifications.company.com
166
password = enterprise-password-2023
167
port = 23053
168
```
169

170
Then all applications using `gntp.config` automatically use the enterprise notification server:
171

172
```python
173
import gntp.config
174

175
# Automatically uses enterprise settings
176
build_notifier = gntp.config.GrowlNotifier(
177
    applicationName="CI/CD Pipeline",
178
    notifications=["Build Started", "Build Success", "Build Failed"]
179
)
180

181
deployment_notifier = gntp.config.GrowlNotifier(
182
    applicationName="Deployment System", 
183
    notifications=["Deploy Started", "Deploy Success", "Deploy Failed"]
184
)
185

186
monitoring_notifier = gntp.config.GrowlNotifier(
187
    applicationName="System Monitor",
188
    notifications=["Alert", "Warning", "Info"]
189
)
190

191
# All three use the same enterprise Growl server automatically
192
```
193

194
## Configuration File Format Details
195

196
The configuration file uses Python's ConfigParser format:
197

198
```ini
199
[gntp]
200
# Growl server hostname or IP address
201
hostname = growl.example.com
202

203
# Network password for authentication (optional)
204
password = your-password-here
205

206
# Growl server port number
207
port = 23053
208
```
209

210
### Configuration Resolution
211

212
Settings are resolved in this order (later values override earlier ones):
213

214
1. **Built-in defaults**: `hostname='localhost'`, `port=23053`, `password=None`
215
2. **Configuration file values**: Read from `~/.gntp` file
216
3. **Constructor arguments**: Explicitly passed to GrowlNotifier constructor
217

218
### Error Handling
219

220
The configuration module handles missing or invalid configuration files gracefully:
221

222
- If `~/.gntp` doesn't exist: Uses built-in defaults, logs info message
223
- If file exists but has no `[gntp]` section: Creates empty section, uses defaults
224
- If file has invalid format: Uses built-in defaults, may log warnings
225
- If specific keys are missing: Uses built-in defaults for those keys
226

227
This ensures applications continue working even in environments without configuration files.