Skip to main content

Library for accessing the Asterisk REST Interface

Project description

ORIGINAL REP : [asterisk/ari-py](https://github.com/asterisk/ari-py.git)

About

This package contains the Python client library for the Asterisk REST Interface. It builds upon the Swagger.py library, providing an improved, Asterisk-specific API over the API generated by Swagger.py

Usage

Install from source using the setup.py script.

$ pip install codet-ari

API

An ARI client can be created simply by the codet-ari.connect method. This will create a client based on the Swagger API downloaded from Asterisk.

The API is modeled into the Repository Pattern, as you would find in Domain Driven Design. Each Swagger Resource (a.k.a. API declaration) is mapped into a Repository object, which is provided as a field on the client (client.channels, client.bridges).

Responses from Asterisk are mapped into first-class objects, akin to Domain Objects in the Repository Pattern. These are provided both on the responses to RESTful API calls, and for fields from events received over the WebSocket.

Making REST calls

Each Repository Object provides methods which invoke the non-instance specific operations of the associated Swagger resource (bridges.list(), channels.get()). Instance specific methods are also provided, which require identity parameters to be passed along (channels.get(channelId=id)).

Instance specific methods are also provided on the Domain Objects (some_channel.hangup()).

Registering event callbacks

Asterisk may send asyncronous messages over a WebSocket to indicate events of interest to the application.

The Client object has an on_event method, which can be used to subscribe for specific events from Asterisk.

The first-class objects also have ‘on_event’ methods, which can subscribe to Stasis events relating to that object.

Object lifetime

The Repository Objects exist for the lifetime of the client that owns them.

Domain Objects are ephemeral, and not tied to the lifetime of the underlying object in Asterisk. Pratically, this means that if you call channels.get('1234') several times, you may get a different object back every time.

You may hold onto an instance of a Domain Object, but you should consider it to be stale. The data contained in the object may be out of date, but the methods on the object should still behave properly.

If you invoke a method on a stale Domain Object that no longer exists in Asterisk, you will get a HTTPError exception (404 Not Found).

Caveats

The dynamic methods exposed by Repository and Domain objects are, effectively, remote procedure calls. The current implementation is synchronous, which means that if anything were to happen to slow responses (slow network, packet loss, system load, etc.), then the entire application could be affected.

Examples

import ari

client = ari.connect('http://localhost:8088/', 'hey', 'peekaboo')

def on_dtmf(channel, event):
    digit = event['digit']
    if digit == '#':
        channel.play(media='sound:goodbye')
        channel.continueInDialplan()
    elif digit == '*':
        channel.play(media='sound:asterisk-friend')
    else:
        channel.play(media='sound:digits/%s' % digit)


def on_start(channel, event):
    channel.on_event('ChannelDtmfReceived', on_dtmf)
    channel.answer()
    channel.play(media='sound:hello-world')


client.on_channel_event('StasisStart', on_start)
client.run(apps="hello")

Development

The code is documented using Sphinx, which allows IntelliJ IDEA to do a better job at inferring types for autocompletion.

To keep things isolated, I also recommend installing (and using) virtualenv.

$ sudo pip install virtualenv
$ mkdir -p ~/virtualenv
$ virtualenv ~/virtualenv/ari
$ . ~/virtualenv/ari/bin/activate

Setuptools is used for building. Nose is used for unit testing, with the coverage plugin installed to generated code coverage reports. Pass --with-coverage to generate the code coverage report. HTML versions of the reports are put in cover/index.html.

$ ./setup.py develop   # prep for development (install deps, launchers, etc.)
$ ./setup.py test # run unit tests
$ ./setup.py bdist_egg # build distributable

TODO

  • Create asynchronous bindings that can be used with Twisted, Tornado, etc.

  • Add support for Python 3

License

Copyright (c) 2013-2014, Digium, Inc. All rights reserved.

Swagger.py is licensed with a BSD 3-Clause License.

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

codet-ari-0.0.1.tar.gz (27.9 kB view details)

Uploaded Source

Built Distribution

codet_ari-0.0.1-py3.5.egg (19.2 kB view details)

Uploaded Source

File details

Details for the file codet-ari-0.0.1.tar.gz.

File metadata

  • Download URL: codet-ari-0.0.1.tar.gz
  • Upload date:
  • Size: 27.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for codet-ari-0.0.1.tar.gz
Algorithm Hash digest
SHA256 29c36e3f44252c58488f7b273e52a2f59551cb8bbadfb1d994b43d039d89de08
MD5 562ed8490d43bc8a9191749b17ccff98
BLAKE2b-256 e3f08efac58bc9193dc8510839eddad6e39c823ee7ef71e4ef2f129c94383d28

See more details on using hashes here.

Provenance

File details

Details for the file codet_ari-0.0.1-py3.5.egg.

File metadata

File hashes

Hashes for codet_ari-0.0.1-py3.5.egg
Algorithm Hash digest
SHA256 0923ba93acc255b68cfeeb7a49d2555b9f3e4cb354bcf10293ebed5f56426d13
MD5 e5951eeb79e0c653378f2558f3be7055
BLAKE2b-256 bc1647c786f8b9389266c06819a60fa54af419d79b3a82a94571e9c786ffdcd2

See more details on using hashes here.

Provenance

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