Async API Reference

Asynchronous API using Tornado framework.

Publisher & Subscriber

AsyncPublisher

class AsyncPublisher(name, event_defs, icon=None, io_loop=None, **kwargs)

Bases: Publisher

Asynchronous GNTP notification publisher.

Same as Publisher but uses AsyncGNTPClient for non-blocking operations. Requires Tornado.

Example

>>> import asyncio
>>> from gntplib.async_gntp import AsyncPublisher
>>> from gntplib import Event
>>>
>>> async def main():
...     pub = AsyncPublisher('MyApp', [Event('test')])
...     pub.register()
...     pub.publish('test', 'Title', 'Message')
>>>
>>> asyncio.run(main())

__init__(name, event_defs, icon=None, io_loop=None, **kwargs)

Initialize async publisher.

Parameters:

• name (str) – Application name

• event_defs (List[str | Tuple[str, bool] | Event]) – Event definitions

• icon (Any | None) – Optional app icon (can be AsyncResource)

• io_loop (IOLoop | None) – Tornado IOLoop (default: current loop)

• **kwargs – Additional client arguments

Raises:

ImportError – If Tornado is not installed

AsyncSubscriber

class AsyncSubscriber(id_, name, hub, password, port=23053, io_loop=None, **kwargs)

Bases: Subscriber

Asynchronous GNTP notification subscriber.

Same as Subscriber but uses AsyncGNTPClient for non-blocking operations. Requires Tornado.

Example

>>> import asyncio
>>> from gntplib.async_gntp import AsyncSubscriber
>>>
>>> async def main():
...     sub = AsyncSubscriber('id', 'name', 'hub.example.com', 'pass')
...     sub.subscribe()
>>>
>>> asyncio.run(main())

__init__(id_, name, hub, password, port=23053, io_loop=None, **kwargs)

Initialize async subscriber.

Parameters:

• id – Unique subscriber ID

• name (str) – Subscriber name

• hub (str | Tuple[str, int]) – Hub address

• password (str) – Hub password

• port (int) – Subscriber port (default: 23053)

• io_loop (IOLoop | None) – Tornado IOLoop (default: current loop)

• **kwargs – Additional client arguments

Raises:

ImportError – If Tornado is not installed

Client & Connection

AsyncGNTPClient

class AsyncGNTPClient(io_loop=None, **kwargs)

Bases: GNTPClient

Asynchronous GNTP client using Tornado.

Extends GNTPClient with async resource fetching capabilities.

io_loop

Tornado IOLoop instance

__init__(io_loop=None, **kwargs)

Initialize async client.

Parameters:

• io_loop (IOLoop | None) – Tornado IOLoop (default: current loop)

• **kwargs – Additional arguments for GNTPClient

Raises:

ImportError – If Tornado is not installed

async process_request(request, callback, **kwargs)

Process request asynchronously.

If request contains AsyncResource instances, fetches them before sending the request.

Parameters:

• request (Any) – GNTP request to process

• callback (Any) – Callback when operation completes

• **kwargs – Additional connection arguments

AsyncGNTPConnection

class AsyncGNTPConnection(address, timeout, final_callback, socket_callback=None, io_loop=None)

Bases: BaseGNTPConnection

Asynchronous GNTP connection using Tornado IOStream.

Provides non-blocking socket communication with GNTP server.

stream

Tornado IOStream for async socket operations

__init__(address, timeout, final_callback, socket_callback=None, io_loop=None)

Initialize async connection.

Parameters:

• address (Tuple[str, int]) – (host, port) tuple

• timeout (float) – Connection timeout in seconds

• final_callback (Any) – Callback when operation completes

• socket_callback (Any | None) – Optional socket event callback

• io_loop (IOLoop | None) – Tornado IOLoop (default: current loop)

Raises:

ImportError – If Tornado is not installed

write_message(message)

Send message to server asynchronously.

Parameters:

message (bytes) – Message bytes to send

read_message(callback)

Read message from server asynchronously.

Parameters:

callback (Any) – Function to call with received message

close()

Close the stream.

Resources

AsyncResource

class AsyncResource(url)

Bases: Resource

Resource that will be fetched asynchronously from URL.

Use this class when you want to fetch icons or images from remote URLs asynchronously before sending the notification.

url

URL to fetch resource from

data

Resource data (populated after fetch)

__init__(url)

Initialize async resource.

Parameters:

url (str) – URL to fetch resource from

Example

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

__repr__()

Return string representation.

Utility Functions

async fetch_async_resources_in_parallel(async_resources)

Fetch multiple AsyncResource URLs in parallel.

Uses asyncio.gather to fetch all resources concurrently. Failed fetches are logged but don’t stop the function.

Parameters:

async_resources (List[AsyncResource]) – List of AsyncResource instances

Returns:

Same list with data populated

Return type:

List[AsyncResource]

Example

>>> resources = [
...     AsyncResource('https://example.com/icon1.png'),
...     AsyncResource('https://example.com/icon2.png')
... ]
>>> await fetch_async_resources_in_parallel(resources)

collect_async_resources(request)

Collect all AsyncResource instances from a request.

Traverses the request object to find all AsyncResource instances that need to be fetched before the request can be sent.

Parameters:

request (Any) – GNTP request object

Returns:

List of unique AsyncResource instances

Return type:

List[AsyncResource]

Example

>>> from gntplib import Event
>>> from gntplib.requests import RegisterRequest
>>> icon = AsyncResource('https://example.com/icon.png')
>>> request = RegisterRequest('MyApp', icon, [Event('test')])
>>> resources = collect_async_resources(request)