uaconnect
is a Python library for using the Urban Airship Connect API for streaming mobile
event data to your application.
Tested on Python 2.7 and 3.5, and should work with 3.3+.
For tests, uaconnect
also needs Mock.
To run tests, run:
$ python -m unittest discover
See the Connect Getting Started Guide, as well as the Connect API for more details.
To use the library, instantiate a Consumer
object with the application key,
access token, and an offset recorder. You can then open the connection, and
start reading events.
>>> import uaconnect >>> consumer = uaconnect.Consumer( ... 'application_key', 'access_token', ... uaconnect.FileRecorder('.offset')) >>> consumer.connect() >>> for event in consumer.read(): ... if event is None: ... continue >>> print("Got event: {}".format(event)) >>> consumer.ack(event)
Offset recorders inherit from the abstract base class uaconnect.Recorder
,
implementing read_offset
and write_offset
methods. One recorder is included
in the library, FileRecorder
, which stores the offest on disk. In the
uaconnect.ext.redisrecorder
package there is an example implementation of
using an Redis instance to store the offset.
ack calls should be placed depending on whether in a failure scenario your
app wishes to possibly replay an already handled event, or risk dropping one.
For the latter, call ack
as soon as the event is read; for the former, call
ack
only after the event has been fully handled.
Urban Airship Connect supports a variety of options when connecting to make sure
that you're only consuming the data that you want. uaconnect
makes it easy
to use these connection parameters and filters.
One of the advantages of Urban Airship Connect is that you can resume from a
specific place in the Connect stream. This is done by specifying the offset
that's associated with the event. While uaconnect
automatically tracks
offsets for you with uaconnect.FileRecorder
, you can also explicitly set an
offset.
>>> import uaconnect >>> recorder = uaconnect.FileRecorder(".offset") # or wherever you would like the file to exist >>> recorder.write_offset("8865499359") # a randomly chosen offset >>> recorder.read_offset() '8865499359'
An alternative here is to just write the offset explicitly into the file, or
whatever Recorder
subclass you're using to track offsets.
$ cat .offset 886549935
Now, the next time you connect, it will pick up from that last offset.
Filters are a powerful way of filtering what specific information you'd like to see from the Connect stream. You can filter by event type, device type, latency on an event, or even specific devices or notifications.
For a complete list of filters, and their descriptions, check out the documentation.
Here's a brief example on how to use filters with uaconnect
:
>>> import uaconnect >>> consumer = uaconnect.Consumer( ... 'application_key', 'access_token', ... uaconnect.FileRecorder('.offset')) >>> f = uaconnect.Filter() >>> f.types("PUSH_BODY", "SEND") # only receive PUSH_BODY and SEND events. >>> consumer.add_filter(f) >>> consumer.connect()