Skip to main content

Python package for using Airship Real-Time Data Streaming

Project description

About

uaconnect is the official Python library for using the Airship Real-Time Data Streaming API (formerly known as Connect).

Questions

The best place to ask questions or report a problem is our support site: http://support.airship.com/

Requirements

Tested on Python 3.6, 3.7, 3.8, and 3.9.

For tests, uaconnect also needs Mock.

Running Tests

To run tests, run:

$ python -m unittest discover

Usage

See the Real-Time Data Streaming Getting Started Guide, as well as the Real-Time Data Streaming API docs for more details.

RTDS Event Consumer

To consume standard events from the RTDS API, instantiate a EventConsumer object with the application key, access token, and an offset recorder. You can then open the connection, and start reading events.

See more about the RTDS Event Stream in our documentation here.

>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     access_token='access_token',
...     recorder=uaconnect.FileRecorder('.offset'))
>>> consumer.connect()
>>> for event in consumer.read():
...     if event is None:
...        continue
>>>     print("Got event: {}".format(event))
>>>     consumer.ack(event)

RTDS Compliance Event Consumer

To consume compliance events from the RTDS API, instantiate a ComplianceConsumer object with the application key, master secret and an offset recorder. You can then open the connection, and start reading events.

See more about the RTDS Compliance Event Stream in the documentation here.

>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     master_secret='master_secret',
...     recorder=uaconnect.FileRecorder('.offset'))
>>> consumer.connect()
>>> for event in consumer.read():
...     if event is None:
...        continue
>>>     print("Got event: {}".format(event))
>>>     consumer.ack(event)

Alternate Data Center Support

When instantiating a EventConsumer or ComplianceConsumer you can pass the optional url argument to explicitly specify the data center your project is located in. Possible values are “US”, “EU”, or an arbitrary base url in the form of http://domain.xyz/. The library will build the URL path properly from there. If no url is specified, “US” is used.

>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     master_secret='master_secret',
...     url='EU',
...     recorder=uaconnect.FileRecorder('.offset'))

Offset recorders

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 offset 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.

Advanced options when connecting

Airship Real-Time Data Streaming 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.

Specifying offsets

One of the advantages of Airship Real-Time Data Streaming is that you can resume from a specific place in the RTDS 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.

If you’d like to manually set the offset for a connection to a known value instead of the recorder’s offset, set resume_offset like so:

>>> consumer.connect(resume_offset='123456789')

Using filters

Filters are a powerful way of filtering what specific information you’d like to see from the RTDS 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.EventConsumer(
...     app_key='application_key',
...     access_token='access_token',
...     recorder=uaconnect.FileRecorder('.offset')
...     )
>>> f = uaconnect.Filter()
>>> f.types("PUSH_BODY", "SEND") # only receive PUSH_BODY and SEND events.
>>> consumer.add_filter(f)
>>> consumer.connect()

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

uaconnect-1.0.2.tar.gz (11.0 kB view details)

Uploaded Source

Built Distribution

uaconnect-1.0.2-py3-none-any.whl (10.3 kB view details)

Uploaded Python 3

File details

Details for the file uaconnect-1.0.2.tar.gz.

File metadata

  • Download URL: uaconnect-1.0.2.tar.gz
  • Upload date:
  • Size: 11.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.16

File hashes

Hashes for uaconnect-1.0.2.tar.gz
Algorithm Hash digest
SHA256 682df7137a39f2f84e912121e1d96c2579b0766d3285711336bde5bb635145ea
MD5 f027af98585002e12ec178bc249169f0
BLAKE2b-256 7a58680736a1563a6815399e106930f97ffbfaa0c5c6f5004c996430fa4acb74

See more details on using hashes here.

File details

Details for the file uaconnect-1.0.2-py3-none-any.whl.

File metadata

  • Download URL: uaconnect-1.0.2-py3-none-any.whl
  • Upload date:
  • Size: 10.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.16

File hashes

Hashes for uaconnect-1.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 986188b6bb3a30374838a4a9d5fb879a320e8329b943ea71b4ac5aaf1de155a7
MD5 3c5af1863ec8405b60c6e5cf4014a283
BLAKE2b-256 ad60b6d4033936494398f51345b2be51ab5bc16f0b3123eda2292c24764d3309

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page