High-level Python API

tattler comes with an open-source python SDK.

The high-level API in it allows you to trigger a notification with one line of code:

# high-level API
from tattler.client.tattler_py import send_notification

success, details = send_notification(   \
    'mywebapp', 'password_changed', 'your@email.com', \
    context={'var1': 1, 'var2': 'two'})

if not success:
    print(details)

This calls to notify:

  • scope mywebapp

  • event name password_changed

  • to recipient your@email.com

  • using the given context, i.e. variables that tattler server will expand the respective event template with.

Server address

By default send_notification() looks up the address of the tattler server to contact from environment variable TATTLER_SRV_ADDRESS (see format below), and falls back to defaults 127.0.0.1:11503 if that’s not set or empty.

The address of the server can also be provided explicitly. Here’s a more advanced example:

# high-level API
from tattler.client.tattler_py import send_notification

success, details = send_notification(                   \
    'mywebapp', 'password_changed', 'your@email.com',   \
    srv_addr='192.168.1.1', srv_port=11503,             \
    correlationId='myprog:38ffae84')

This points tattler_client to reach the server at the respective address and port.

This example additionally provides a correlationId. That’s a string identifying the transaction at the client, which tattler will log into its own logs to aid cross-system troubleshooting.

Here’s a brief reference of the function:

Python client to access tattler server

tattler.client.tattler_py.send_notification(scope, event, recipient, context=None, correlationId=None, mode='debug', vectors=None, priority=None, srv_addr=None, srv_port=None)

All-in-one utility to connect to tattler server and send a notification.

If both srv_addr and srv_port are None, they are looked up in envvar ‘TATTLER_SRV_ADDR’, which takes format ‘address:port’ (e.g. ‘192.168.1.1:11503’ or ‘fe80::12:11503’), before defaulting to ‘127.0.0.1’ and 11503 respectively if that’s not given. If you don’t want configuration to be looked up in the environment, set either argument srv_addr or srv_port.

Parameters:

  • scope (str) – The scope name to search the event in.

  • event (str) – The event name to deliver.

  • context (Optional[Mapping[str, str]]) – Optional custom variables (name:value) to use for template expansion.

  • correlationId (Optional[str]) – correlation ID for tattler log when processing this request. Self-generated if missing.

  • mode (str) – Notification mode in ‘debug’, ‘staging’, ‘production’.

  • vectors (Optional[Iterable[str]]) – Restrict delivery to these vectors; ‘None’ delivers to all vectors declared by the event template.

  • priority (Optional[bool]) – Embed this user-visible priority in the notification, where the vector supports it.

  • srv_addr (Optional[str]) – Contact tattler_server at this IP address. Default: 127.0.0.1

  • srv_port (Optional[int]) – Contact tattler_server at this port number. Default: 11503

Return type:

Tuple[bool, Optional[Mapping[str, str]]]

Returns:

Whether delivery succeeded for at least one vector, and delivery details for all.

Additionally, the python client is controlled by the following environment variables:

LOG_LEVEL

Values: debug, info, warning, error.

Default: info.

Only log entries at or higher than this severity.

TATTLER_SERVER_ADDRESS

Values: address:port – address is an IPv4 or IPv6 address.

Default: 127.0.0.1:11503

Contact the server on this address and TCP port.