Models API Reference¶

This page documents data model classes used in gntplib.

Event Class¶

Defines notification types.

class Event(name, display_name=None, enabled=True, icon=None)[source]¶

Bases: object

Notification type definition.

Events define the types of notifications an application can send. Each event must be registered before notifications of that type can be sent.

name¶: Unique identifier for the notification type

display_name¶: Human-readable name shown in preferences

enabled¶: Whether notifications of this type are enabled by default

icon¶: Optional icon for this notification type

Attributes

name¶: Unique identifier for the event type (required).

display_name¶: Human-readable name shown in preferences (defaults to name).

enabled¶: Whether event is enabled by default (defaults to True).

icon¶: Optional Resource instance for event icon.

Example

from gntplib import Event, Resource

# Simple event
event1 = Event('update')

# With display name
event2 = Event('update', 'Software Update')

# Disabled by default
event3 = Event('debug', 'Debug Message', enabled=False)

# With icon
icon = Resource.from_file('update.png')
event4 = Event('update', icon=icon)

__init__(name, display_name=None, enabled=True, icon=None)[source]¶

Initialize notification event definition.

Parameters:

name (str) – Event identifier (required)
display_name (str | None) – Display name (defaults to name)
enabled (bool) – Enable by default (default: True)
icon (Resource | None) – Optional icon resource

Raises:

GNTPValidationError – If name is empty

Example

>>> event = Event('Update', 'Software Update', enabled=True)

__repr__()[source]¶

Return string representation.

__eq__(other)[source]¶

Check equality based on name.

__hash__()[source]¶

Make Event hashable based on name.

Resource Class¶

Handles binary resources like icons and images.

class Resource(data=None, url=None)[source]¶

Bases: object

Binary resource for GNTP messages (icons, images, etc).

Resources are binary data that can be embedded in GNTP messages or referenced by URL. Each resource has a unique identifier based on its content hash.

data¶: Binary content of the resource

url¶: Optional URL if resource is remote

Attributes

data¶: Binary content of the resource (bytes or None).

url¶: Optional URL string for remote resources.

Methods

classmethod from_file(filepath)[source]¶

Create resource from file.

Parameters:: filepath (str) – Path to file
Returns:: Resource instance with file contents
Raises:: IOError – If file cannot be read
Return type:: Resource

Example

>>> icon = Resource.from_file('icon.png')

classmethod from_url(url)[source]¶

Create resource from URL.

Parameters:: url (str) – URL to resource
Returns:: Resource instance referencing URL
Return type:: Resource

Example

>>> icon = Resource.from_url('https://example.com/icon.png')

unique_value()[source]¶

Get unique hash identifier for resource content.

Returns MD5 hash of resource data as hex bytes.

Returns:: Hex-encoded MD5 hash or None if no data
Return type:: bytes | None

Example

>>> resource = Resource(b'test data')
>>> resource.unique_value()
b'eb733a00c0c9d336e65691a37ab54293'

unique_id()[source]¶

Get unique resource identifier with protocol scheme.

Returns:: Full resource identifier or None if no data
Return type:: bytes | None

Example

>>> resource = Resource(b'test')
>>> resource.unique_id()
b'x-growl-resource://098f6bcd4621d373cade4e832627b4f6'

Example

from gntplib import Resource

# From file
icon = Resource.from_file('app_icon.png')
print(f"Size: {len(icon.data)} bytes")

# From URL
remote_icon = Resource.from_url('https://example.com/icon.png')

# From bytes
with open('image.png', 'rb') as f:
    embedded = Resource(data=f.read())

# Get unique identifier
resource_id = icon.unique_id()  # b'x-growl-resource://...'

__init__(data=None, url=None)[source]¶

Initialize resource with binary data or URL.

Parameters:

data (bytes | None) – Binary content (for embedded resources)
url (str | None) – URL string (for remote resources)

Example

>>> # Embedded resource
>>> with open('icon.png', 'rb') as f:
...     icon = Resource(data=f.read())
>>>
>>> # URL resource
>>> icon = Resource(url='https://example.com/icon.png')

__call__()[source]¶

Get resource data.

Returns:: Binary data of the resource or None if URL-based
Return type:: bytes | None

Example

>>> resource = Resource(b'binary data')
>>> data = resource()

classmethod from_file(filepath)[source]¶

Create resource from file.

Parameters:: filepath (str) – Path to file
Returns:: Resource instance with file contents
Raises:: IOError – If file cannot be read
Return type:: Resource

Example

>>> icon = Resource.from_file('icon.png')

classmethod from_url(url)[source]¶

Create resource from URL.

Parameters:: url (str) – URL to resource
Returns:: Resource instance referencing URL
Return type:: Resource

Example

>>> icon = Resource.from_url('https://example.com/icon.png')

unique_value()[source]¶

Get unique hash identifier for resource content.

Returns MD5 hash of resource data as hex bytes.

Returns:: Hex-encoded MD5 hash or None if no data
Return type:: bytes | None

Example

>>> resource = Resource(b'test data')
>>> resource.unique_value()
b'eb733a00c0c9d336e65691a37ab54293'

unique_id()[source]¶

Get unique resource identifier with protocol scheme.

Returns:: Full resource identifier or None if no data
Return type:: bytes | None

Example

>>> resource = Resource(b'test')
>>> resource.unique_id()
b'x-growl-resource://098f6bcd4621d373cade4e832627b4f6'

__repr__()[source]¶

Return string representation.

__bool__()[source]¶

Check if resource has content.

Notification Class¶

Represents individual notification instances.

class Notification(name, title, text='', id_=None, sticky=False, priority=0, icon=None, coalescing_id=None, callback=None)[source]¶

Bases: object

Individual notification instance.

Represents a single notification to be sent to the GNTP server.

name¶: Event name this notification belongs to

title¶: Notification title

text¶: Notification message body

id_¶: Optional unique identifier

sticky¶: Whether notification stays until dismissed

priority¶: Priority level (-2 to 2)

icon¶: Optional icon resource

coalescing_id¶: ID for grouping/replacing notifications

callback¶: Optional callback handler

Attributes

name¶: Event name (must match registered event).

title¶: Notification title (required).

text¶: Notification message body.

id_¶: Optional unique identifier.

sticky¶: Whether notification stays until dismissed.

priority¶: Priority level (-2 to 2).

icon¶: Optional Resource instance.

coalescing_id¶: ID for grouping/replacing notifications.

callback¶: Optional callback handler.

Properties

property socket_callback: SocketCallback | None¶: Get socket callback if callback is SocketCallback type.

Example

from gntplib.models import Notification, Resource

# Simple notification
notif = Notification('update', 'New Version', 'v2.0 released')

# With all options
icon = Resource.from_file('alert.png')
notif = Notification(
    name='alert',
    title='Critical Alert',
    text='Server is down!',
    id_='alert-001',
    sticky=True,
    priority=2,
    icon=icon,
    coalescing_id='server-alerts'
)

__init__(name, title, text='', id_=None, sticky=False, priority=0, icon=None, coalescing_id=None, callback=None)[source]¶

Initialize notification.

Parameters:

name (str) – Event name
title (str) – Notification title
text (str) – Message text (default: ‘’)
id – Unique notification ID
sticky (bool) – Keep visible until dismissed (default: False)
priority (int) – Priority from -2 to 2 (default: 0)
icon (Resource | None) – Optional icon
coalescing_id (str | None) – Group/replace ID
callback (BaseCallback | None) – Optional callback handler

Raises:

GNTPValidationError – If name or title is empty

Example

>>> notif = Notification(
...     'Update',
...     'New Version',
...     'Version 2.0 is available',
...     priority=1,
...     sticky=True
... )

property socket_callback: SocketCallback | None¶: Get socket callback if callback is SocketCallback type.

__repr__()[source]¶

Return string representation.

Callback Classes¶

SocketCallback¶

Socket-based callback for notification interactions.

class SocketCallback(context='None', context_type='None', on_click=None, on_close=None, on_timeout=None)[source]¶

Bases: BaseCallback

Socket-based callback for notification responses.

Handles different callback events (clicked, closed, timeout) via registered callback functions.

context¶: Callback context value

context_type¶: Type of context

on_click_callback¶: Called when notification is clicked

on_close_callback¶: Called when notification is closed

on_timeout_callback¶: Called when notification times out

Attributes

context¶: Callback context value (default: ‘None’).

context_type¶: Type of context (default: ‘None’).

on_click_callback¶: Function called on click event.

on_close_callback¶: Function called on close event.

on_timeout_callback¶: Function called on timeout event.

Methods

on_click(response)[source]¶

Handle click event.

on_close(response)[source]¶

Handle close event.

on_timeout(response)[source]¶

Handle timeout event.

Example

from gntplib import SocketCallback

def handle_click(response):
    print("Notification clicked!")
    context = response.headers.get('Notification-Callback-Context')
    print(f"Context: {context}")

def handle_close(response):
    print("Notification closed")

callback = SocketCallback(
    context='action-123',
    context_type='user-action',
    on_click=handle_click,
    on_close=handle_close
)

publisher.publish(
    'event',
    'Interactive',
    'Click me!',
    gntp_callback=callback
)

__init__(context='None', context_type='None', on_click=None, on_close=None, on_timeout=None)[source]¶

Initialize socket callback.

Parameters:

context (str) – Context value (default: ‘None’)
context_type (str) – Context type (default: ‘None’)
on_click (Callable | None) – Callback for click events
on_close (Callable | None) – Callback for close events
on_timeout (Callable | None) – Callback for timeout events

Example

>>> def on_clicked(response):
...     print("Notification clicked!")
>>>
>>> callback = SocketCallback(
...     context='notification_1',
...     on_click=on_clicked
... )

on_click(response)[source]¶

Handle click event.

on_close(response)[source]¶

Handle close event.

on_timeout(response)[source]¶

Handle timeout event.

__call__(response)[source]¶

Dispatch to appropriate handler based on callback result.

Parameters:: response (Any) – Response object with callback result
Returns:: Result from handler callback
Return type:: Any

write_into(writer)[source]¶

Write socket callback headers.

__repr__()[source]¶

Return string representation.

URLCallback¶

URL-based callback for notification interactions.

class URLCallback(url)[source]¶

Bases: BaseCallback

URL-based callback for notification responses.

When notification is interacted with, GNTP server will request the URL.

url¶: Callback URL

Attributes

url¶: URL to be called on interaction.

Example

from gntplib.models import URLCallback

callback = URLCallback('https://example.com/notify')

publisher.publish(
    'event',
    'Click to visit',
    'Open website',
    gntp_callback=callback
)

__init__(url)[source]¶

Initialize URL callback.

Parameters:: url (str) – URL to be called on notification interaction

Example

>>> callback = URLCallback('https://example.com/callback')

write_into(writer)[source]¶

Write URL callback headers.

__repr__()[source]¶

Return string representation.