jwt_apns_client package

Submodules

jwt_apns_client.cli module

jwt_apns_client.jwt_apns_client module

jwt_apns_client/jwt_apns_client

Client for handling HTTP/2 and JWT based connections to Apple’s APNs.

class jwt_apns_client.jwt_apns_client.APNSConnection(*args, **kwargs)

Bases: object

Manages a connection to APNs

Variables:

• algorithm (str) – The algorithm to use for the jwt. Defaults to ES256.
• team_id (str) – The app team id
• apns_key_id (str) – The apns key id
• apns_key_path (str) – Path to file with the apns auth key
• api_version (int) – The API version. Default is 3
• topic (str) – The APNs topic
• environment (str) – development or production. Default is development.
• api_host (str) – The host for the API. If not specified then defaults to the standard host for the specified environment.
• api_port (int) – The port to make the http2 connection on. Default is 443.
• provider_token (str) – The base64 encoded jwt provider token

close(error_code=None)

Close the HTTP/2 connection with optional error code

connection

get_payload_data(alert=None, badge=None, sound=None, content=None, category=None, thread=None)

Builds the payload dict.

More information about these values may be found in Apple’s documentation at https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html

Parameters:

• alert – May be a Alert instance or a string
• badge (int) – Include to modify the badge of the app’s icon
• sound (str) – The name of a sound in the app’s bundle or Librar/Sounds folder.
• content (int) – Set to 1 for a silent notification.
• category (str) – String which represents the notification’s type. This should correspond with a value in the identifier property of one of the app’s registered categories.
• thread (str) – An app specific identifier for grouping notifications.

Returns:

The payload as a dict ready for conversion to json in a request.

get_request_headers(token=None, topic=None, priority=10, expiration=0)

See details on topic, expiration, priority values, etc. at https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html#//apple_ref/doc/uid/TP40008194-CH11-SW1

Parameters:

• token – the jwt token
• topic – the message topic
• (int) (expiration) – the message priority. 10 for immediate, 5 to consider power consumption. Default is 10.
• (int) – The message expiration. Default is 0.

Returns:

A dict of the http request headers

get_request_payload(alert=None, badge=None, sound=None, content=None, category=None, thread=None)

Returns the request payload as utf-8 encoded json

More information about these values may be found in Apple’s documentation at https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html

Parameters:

• alert – May be a Alert instance or a string
• badge (int) – Include to modify the badge of the app’s icon
• sound (str) – The name of a sound in the app’s bundle or Librar/Sounds folder.
• content (int) – Set to 1 for a silent notification.
• category (str) – String which represents the notification’s type. This should correspond with a value in the identifier property of one of the app’s registered categories.
• thread (str) – An app specific identifier for grouping notifications.

Returns:

The JSON encoded request payload

get_secret()

get_token_headers(algorithm=None, apns_key_id=None)

Build headers for the JWT token

Parameters:

• algorithm (str) – The algorithm to use for the jwt. Defaults to ES256, which is required by the APNs.
• apns_key_id (str) – The apns key id

Returns:

Dict of headers for the JWT token

make_provider_token(issuer=None, issued_at=None, algorithm=None, secret=None, headers=None)

Build the jwt token for the connection.

Apple returns an error if the provider token is updated too often, so we don’t want to constantly build new ones.

Parameters:

• issuer (str) – JWT issuer. Generally the team id. Defaults to self.team_id
• issued_at (time.time) – A time object specifying when the token was issued. Defaults to time.time()
• algorithm (str) – The algorithm to use for the jwt. Defaults to ES256, which is required by the APNs.
• secret (str) – The APNs key. If None then defaults to self.secret.
• headers (dict) – The JWT token headers

Returns:

JWT encoded token

send_notification(device_registration_id, **kwargs)

Send a push notification using http2. Creates a new connection or reuses an existing connection if possible.

Parameters:

• device_registration_id (str) – The registration id of the device to send the notification to
• alert – May be a Alert instance or a string
• badge (int) – Include to modify the badge of the app’s icon
• sound (str) – The name of a sound in the app’s bundle or Librar/Sounds folder.
• content (int) – Set to 1 for a silent notification.
• category (str) – String which represents the notification’s type. This should correspond with a value in the identifier property of one of the app’s registered categories.
• thread (str) – An app specific identifier for grouping notifications.

Returns:

A jwt_apns_client.jwt_apns_client.NotificationResponse

class jwt_apns_client.jwt_apns_client.APNSEnvironments

Bases: object

Class to act as enum of APNs Environments

DEV = u'dev'

PROD = u'prod'

class jwt_apns_client.jwt_apns_client.Alert(*args, **kwargs)

Bases: object

An APNs Alert. APNs Payloads can take a dict, which will be built from this object or just a single string.

More information on the data may be found in Apple’s documentation at https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html

Variables:

• title (str) – The alert title
• body (str) – The alert body
• title_loc_key (str) – Localizable string for the title
• title_loc_args ([str]) – Variable string values to appear in place for format specifiers in title_loc_key
• action_loc_key (str) – String to get localized title for the View button in the app.
• loc_key (str) – Key to an alert-message string in app’s Localizable.strings.
• loc_args ([str]) – Variable string values for format specifiers in loc_key
• launch_image (str) – Filename of an image in the app bundle to be used as a launch image.

get_payload_dict()

Returns the APNs payload data from the object instance as a dictionary suitable for encoding as JSON for use in API requests.

class jwt_apns_client.jwt_apns_client.NotificationResponse(status=200, reason=u'', host=u'', port=443, path=u'', payload=None, headers=None, *args, **kwargs)

Bases: object

Encapsulate a response to sending a notification using the API.

Variables:

• status (int) – The HTTP status code of the response
• reason (str) – Reason if specified
• payload (str) – The JSON payload
• headers (dict) – response headers
• host (str) – Host the request was made to
• port (int) – The port the request was made to
• path (str) – Path of the HTTP request

jwt_apns_client.utils module

jwt_apns_client/utils

General utility classes and functions

class jwt_apns_client.utils.APNSReasons

Bases: object

Constants for the various reason strings returned by APNs on error.

This is not currently an exhaustive list, this is just the ones we currently care about for handling

BAD_CERTIFICATE = u'BadCertificate'

BAD_CERT_ENVIRONMENT = u'BadCertificateEnvironment'

BAD_COLLAPSE_ID = u'BadCollapseId'

BAD_DEVICE_TOKEN = u'BadDeviceToken'

BAD_EXPIRATION_DATE = u'BadExpirationDate'

BAD_MESSAGE_ID = u'BadMessageId'

BAD_PATH = u'BadPath'

BAD_PRIORITY = u'BadPriority'

BAD_TOPIC = u'BadTopic'

DEVICE_TOKEN_NOT_FOR_TOPIC = u'DeviceTokenNotForTopic'

DUPLICATE_HEADERs = u'DuplicateHeaders'

EXPIRED_PROVIDER_TOKEN = u'ExpiredProviderToken'

FORBIDDEN = u'Forbidden'

IDLE_TIMEOUT = u'IdleTimeout'

INTERNAL_SERVER_ERROR = u'InternalServerError'

INVALID_PROVIDER_TOKEN = u'InvalidProviderToken'

METHOD_NOT_ALLOWED = u'MethodNotAllowed'

MISSING_DEVICE_TOKEN = u'MissingDeviceToken'

MISSING_PROVIDER_TOKEN = u'MissingProviderToken'

MISSING_TOPIC = u'MissingTopic'

PAYLOAD_EMPTY = u'PayloadEmpty'

PAYLOAD_TOO_LARGE = u'PayloadTooLarge'

PROVIDER_TOKEN_UPDATES = u'TooManyProviderTokenUpdates'

SERVICE_UNAVAILABLE = u'ServiceUnavailable'

SHUTDOWN = u'Shutdown'

TOO_MANY_REQUESTS = u'TooManyRequests'

TOPIC_DISALLOWED = u'TopicDisallowed'

UNREGISTERED = u'Unregistered'

jwt_apns_client.utils.make_provider_token(issuer, secret, issued_at=None, headers=None)

Build the jwt token for the connection.

Apple returns an error if the provider token is updated too often, so we don’t want to constantly build new ones.

Parameters:

• issuer – The issuer to use for the jwt token
• issued_at – Time as unix epoch the token was issued at. Defaults to time.time().
• headers – The jwt headers to use as a dict. Includes the algorithm and key id.
• algorithm – The hashing algorithm used. Should be the same as used in the headers. If not specified then the value will be taken from headers[‘alg’]

Returns:

JWT encoded token

Module contents