or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfig-api.mderrors.mdhigh-level-api.mdindex.mdprotocol.md
tile.json

tessl/pypi-gntp

Growl Notification Transport Protocol for Python

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/gntp@1.0.x

To install, run

npx @tessl/cli install tessl/pypi-gntp@1.0.0

index.mddocs/

GNTP

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.

Package Information

  • Package Name: gntp
  • Language: Python
  • Installation: pip install gntp

Core Imports

import gntp.notifier

For configuration-aware usage:

import gntp.config

For low-level protocol access:

import gntp.core

Basic Usage

import gntp.notifier

# Simple fire-and-forget notification
gntp.notifier.mini("Here's a quick message")

# More complete example with application registration
growl = gntp.notifier.GrowlNotifier(
    applicationName="My Application Name",
    notifications=["New Updates", "New Messages"],
    defaultNotifications=["New Messages"],
    # hostname="computer.example.com",  # Defaults to localhost
    # password="abc123"  # Defaults to blank password
)

# Register with Growl (required before sending notifications)
growl.register()

# Send a notification
growl.notify(
    noteType="New Messages",
    title="You have a new message",
    description="A longer message description",
    icon="http://example.com/icon.png",
    sticky=False,
    priority=1,
)

Architecture

The GNTP library is organized into several modules providing different levels of abstraction:

  • High-level API (gntp.notifier): Simple notification functions and full-featured GrowlNotifier class
  • Configuration API (gntp.config): Config file-aware versions that read settings from ~/.gntp
  • Low-level Protocol (gntp.core): Direct GNTP message construction and parsing
  • Error Handling (gntp.errors): Comprehensive exception hierarchy for all error conditions
  • Command Line Interface (gntp.cli): Full-featured CLI for sending notifications from shell scripts

This design enables both simple one-line notifications and complex multi-application notification management while maintaining compatibility with older Python Growl bindings.

Capabilities

High-Level Notification API

Simple fire-and-forget notifications and full-featured application registration with comprehensive notification management, including custom types, icons, priorities, and callbacks.

def mini(description, applicationName='PythonMini', noteType="Message", 
         title="Mini Message", applicationIcon=None, hostname='localhost', 
         password=None, port=23053, sticky=False, priority=None, 
         callback=None, notificationIcon=None, identifier=None, 
         notifierFactory=GrowlNotifier): ...

class GrowlNotifier(object):
    def __init__(self, applicationName='Python GNTP', notifications=[], 
                 defaultNotifications=None, applicationIcon=None, 
                 hostname='localhost', password=None, port=23053): ...
    def register(self): ...
    def notify(self, noteType, title, description, icon=None, sticky=False, 
               priority=None, callback=None, identifier=None, custom={}): ...
    def subscribe(self, id, name, port): ...

High-Level API

Configuration-Aware API

Enhanced notification API that reads default settings from ~/.gntp configuration file, enabling shared configuration across multiple applications and simplified deployment.

def mini(description, **kwargs): ...

class GrowlNotifier(gntp.notifier.GrowlNotifier):
    def __init__(self, *args, **kwargs): ...

Configuration API

Low-Level Protocol Implementation

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.

class GNTPRegister:
    def __init__(self, data=None, password=None): ...
    def add_notification(self, name, enabled=True): ...
    def encode(self): ...

class GNTPNotice:
    def __init__(self, data=None, app=None, name=None, title=None, password=None): ...
    def encode(self): ...

def parse_gntp(data, password=None): ...

Low-Level Protocol

Error Handling

Comprehensive exception hierarchy covering all GNTP error conditions including network failures, authentication errors, parsing issues, and unsupported operations.

class BaseError(Exception): ...
class ParseError(BaseError): ...
class AuthError(BaseError): ...
class UnsupportedError(BaseError): ...
class NetworkError(BaseError): ...

Error Handling

Command Line Interface

Full-featured command-line interface for sending GNTP notifications from shell scripts and system automation, supporting all notification parameters and configuration file integration.

def main(): ...

class ClientParser(OptionParser):
    def __init__(self): ...
    def parse_args(self, args=None, values=None): ...

Command Line Interface

Types

# Configuration dictionary for ~/.gntp file
GNTPConfig = dict  # Keys: hostname, password, port

# Custom notification attributes (key-value pairs)
CustomAttributes = dict  # Keys should be prefixed with X- per GNTP spec

# Password hash algorithms
PasswordHashAlgorithm = str  # Values: 'MD5', 'SHA1', 'SHA256', 'SHA512'

# Priority levels
Priority = int  # Range: -2 to 2

# Port number
Port = int  # Default: 23053

# Notification data
NotificationData = bytes  # For binary resources like images