API reference¶

For users¶

class apns_worker.ApnsManager(key_path, cert_path, environment=u'production', backend_path=u'apns_worker.backend.threaded.Backend', message_grace=5, error_handler=None)¶

Top-level object for sending Apple push notifications.

One instance of this object manages a single connection to the Apple push notification service and a single queue of notifications to send. For most purposes, a single global instance should be sufficient. For high volumes, it may be worthwhile to create multiple instances and distribute messages across them.

Parameters:

key_path (str) – Path to your PEM-encoded APNs client key.
cert_path (str) – Path to your PEM-encoded APNs client certificate.
environment (str) – APNs environment: ‘sandbox’ or ‘production’.
backend_path (str) – Module path to a subclass of apns_worker.backend.base.Backend. The backend provides the network access and concurrency.
message_grace (int) – Number of seconds to hold on to a delivered message before assuming that it was successful.
error_handler – An optional function to process delivery errors. The function should take one argument, which will be an Error.

flush_messages()¶

Wait until all queued messages have been delivered.

This will not return until all messages have been presumed successful (according to the delivery grace period).

The only reason to call this is to make sure the queue is empty before allowing a process to terminate.

get_feedback(callback)¶

Start retrieving tokens from the APNs feedback service.

This will deliver Feedback items to the callback asynchronously.

Parameters:	callback – A function that takes a single `Feedback` object. The callback will be called zero or more times.

send_aps(tokens, alert=None, badge=None, sound=None, content_available=None, category=None)¶

A convenience API to send a standard notification.

If you’re sending a simple notification with a standard payload, you can use this shortcut API instead of constructing a Message manually. Specify any arguments that you wish to include in the ‘aps’ dictionary of the payload.

Parameters:	tokens (list of str) – alert (str or dictionary) – badge (int) – sound (str) – content_available (bool) – category (str) –

send_message(message)¶

Queues a message for delivery.

Parameters:	message (`Message`) –

class apns_worker.Message(tokens, payload, expiration=None, priority=None)¶

A single push notification to be sent to one or more devices.

Parameters:	tokens (list) – A list of hex-encoded device tokens. payload (dict) – Payload dictionary. expiration (datetime) – An expiration time (optional). If this is a naive datetime, it is assumed to be UTC. priority (int) – Notification priority (optional). According to the current docs, 10 = send now and 5 = send when convenient.

This validates arguments fairly aggressively and may raise standard exceptions.

class apns_worker.Error¶

Represents a delivery error returned by APNs.

These are only generated for unrecoverable errors that the client might want to know about.

status¶: The APNs status code.

description¶: A human-readable description of the error.

message¶: The Message that generated the error.

token¶: The specific device token that generated the error.

ERR_NO_PAYLOAD = 4¶

ERR_NO_TOKEN = 2¶

ERR_NO_TOPIC = 3¶

ERR_PAYLOAD_SIZE = 7¶

ERR_PROCESSING = 1¶

ERR_TOKEN_INVAL = 8¶

ERR_TOKEN_SIZE = 5¶

ERR_TOPIC_SIZE = 6¶

ERR_UNKNOWN = 255¶

class apns_worker.Feedback¶

A single record from the APNs feedback service.

token¶: A hex-encoded device token that can not receive notifications.

when¶: The time at which this device stopped receiving notifications as a naive UTC datetime. If the device was registered with your service after this time, you can ignore this feedback.

For backend developers¶

class apns_worker.backend.base.Backend(queue, environment, key_path, cert_path, error_handler)¶

Base class for APNs backends.

The arguments to __init__ are unspecified and subject to change. If a subclass wishes to add its own initialization, it must accept any arguments and pass them to the superclass.

Backend instances will have key parameters set as instance attributes.

queue¶: Our NotificationQueue.

environment¶: The APNs environment to talk to (‘sandbox’ or ‘production’).

key_path¶: Path to our PEM-encoded TLS client key.

cert_path¶: Path to our PEM-encoded TLS client certificate.

delivery_error(error)¶

Reports a permanent error delivering a message.

Parameters:	token (str) – The specific token that failed.

queue_lock()¶

Override this.

Returns an object compatible with threading.Lock. Subclasses that don’t require locking may return a dummy lock.

queue_notify()¶

Override this.

Notifies listeners that the queue may have new items available.

This is always called while the object returned by queue_lock() is acquired, making it compatible with condition variable semantics.

sleep(seconds)¶

Override this.

Sleeps for the given number of seconds.

start()¶

Override this.

Starts processing notifications.

start_feedback(callback)¶

Override this.

Opens the APNs feedback connection. The callback will be called zero or more times with a Feedback object as the single argument.

stop()¶

Override this.

Stops processing notifications.

class apns_worker.queue.NotificationQueue(grace)¶

A special queue for Notification objects.

When a notification is claimed from the queue, we retain a reference to it with an expiration. Once expired, sent notifications are eventually purged. However, if a delivery failure is subsequently detected, the backtrack() method can be used to rewind the queue to the first notification that failed.

Parameters:	grace (int) – Seconds to leave a claimed notification in the queue before purging it.

append(message)¶

Queues a message for delivery.

Parameters:	message (`Message`) – A single message to queue for delivery.

backtrack(ident)¶

Returns claimed notifications to the queue.

All notifications after ident are known to have failed and need to be re-queued. All notifications before ident are now known to have succeeded.

Parameters:	ident (int) – Ident of the first failed (or last successful) notification.
Returns:	The notification with the given ident, if found.
Return type:	`Notification` or None.

claim()¶

Returns the next notification to be sent.

The returned notification is provisionally removed from the queue, but can be restored with a timely call to backtrack() or unclaim().

Return type:	`Notification`.

has_unclaimed()¶

Returns True if the queue has any unclaimed items.

Return type:	bool

is_empty()¶

Returns True if the queue has no items.

This includes claimed and unclaimed items. Use this with purge_expired() to wait for a decommissioned queue to drain.

Return type:	bool

purge_expired()¶

Permanently removes notifications that have expired.

This is called auomatically as oppotunities arise, but can also be called manually, for instance to drain the queue for termination.

Returns:	A recommended number of seconds to wait until the next call.
Return type:	float

unclaim(notification)¶

Restores the most recently claimed notification to the queue.

Returns:	True if the notification could be unclaimed, False otherwise.
Return type:	bool

class apns_worker.data.Notification(message, encoded_token, ident)¶

An internal representation of a single notification to send.

Parameters:	message (`apns_worker.Message`) – The original message. encoded_token (bytes) – Binary representation of a device token. ident (int) – 32-bit notification identifier.

frame()¶

Renders this notification to an APNs frame.

Returns:	A complete frame, ready to be put on the wire.
Return type:	bytes

token¶

This notification’s hex-encoded token.

Return type:	str