Airship Python Library

urbanairship is a Python library for using the Airship web service in support of our messaging product lines and related features.

Installation

Using pip:

$ pip install urbanairship

Using the library

The library is intended to be used with the small footprint of a single import. To get started, import the package, and create an Airship object representing a single Airship project.

import urbanairship as ua
airship = ua.client.BasicAuthClient('<app key>', '<master secret>')

push = airship.Push(airship=airship)
push.audience = ua.ios_channel('074e84a2-9ed9-4eee-9ca4-cc597bfdbef3')
push.notification = ua.notification(ios=ua.ios(alert='Hello from Python', badge=1))
push.device_types = ua.device_types('ios')
push.send()

The library uses requests for communication with the Airship API, providing connection pooling and strict SSL checking. The Airship object is threadsafe, and can be instantiated once and reused in multiple threads.

Authentication Clients

The library supports authentication via 1 of 3 client classes:

  • BasicAuthClient - This is the same as the deprecated Airship client class for using Key/Secret authentication.

  • BearerTokenClient - This client takes a token argument with an Airship-generated bearer token in addition to the key and other configuration options.

  • OAuthClient - This client requests an OAuth bearer token using the client_id and JWT assertion and automatically refreshes tokens as needed from the Airship OAuth2 provider. Please see the OAuth2 section of the Airship API documentation for more on this authentication method. If you prefer to handle token refresh yourself, the access_token returned from the Airship OAuth2 proivder can be used with the BearerTokenClient.

More about these methods, including examples of instantiation can be found on the Airship docs site.

EU Base URL

When creating an instance of urbanairship.Airship, an optional argument may be added to specify use of Airship’s EU data center. This is required for projects based in our EU data center. If no location argument is passed, the US data center will be used.

import urbanairship as ua
eu_airship = ua.Airship(key='<app_key>', secret='<master_secret>', location='eu')

Logging

urbanairship uses the standard logging module for integration into an application’s existing logging. If you do not have logging configured otherwise, your application can set it up like so:

import logging
logging.basicConfig()

If you’re having trouble with the Airship API, you can turn on verbose debug logging.

logging.getLogger('urbanairship').setLevel(logging.DEBUG)

As of Python 2.7, DeprecationWarning warnings are silenced by default. To enable them, use the warnings module:

import warnings
warnings.simplefilter('default')

Exceptions

class urbanairship.AirshipFailure(error: str | None, error_code: str | int | None, details: str | None, response: str | None, *args: Any)

Raised when we get an error response from the server.

Parameters:

args – For backwards compatibility, *args includes the status and response body.

class urbanairship.Unauthorized

Raised when we get a 401 from the server

class urbanairship.ConnectionFailure

Raised when there’s a connection failure.

Development

The library source code is available on GitHub.

Tests can be run with nose:

nosetests --with-doctest

Contents

Indices and tables