About
This package contains the Python >= 3.5 asynchronous client library for the Asterisk REST Interface. It builds upon the swaggerpy3 library, providing an improved, Asterisk-specific API over the API generated by swaggerpy3.
Usage
Install from source using the setup.py script.
$ sudo python3 setup.py install
API
An ARI client can be created simply by the 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).
Examples
#!/usr/bin/env python3
import aripy3
import asyncio
import logging
logging.basicConfig(level=logging.DEBUG)
async def on_dtmf(channel, event):
digit = event['digit']
if digit == '#':
await channel.play(media='sound:goodbye')
await channel.continueInDialplan()
elif digit == '*':
await channel.play(media='sound:asterisk-friend')
else:
await channel.play(media='sound:digits/%s' % digit)
async def on_start(channel, event):
channel = channel['channel']
await channel.on_event('ChannelDtmfReceived', on_dtmf)
await channel.answer()
await channel.play(media='sound:hello-world')
async def main():
ari = await aripy3.connect('http://localhost:8088/', 'admin', 'admin')
await ari.on_channel_event('StasisStart', on_start)
await ari.run(apps="phoenix")
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
loop.run_forever()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 pip3 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.
$ python3 setup.py develop # prep for development (install deps, launchers, etc.) $ python3 setup.py nosetests # run unit tests $ python3 setup.py bdist_egg # build distributable
TODO
Fix the 'on_channel_start' channel variable.
License
Copyright (c) 2013-2014, Digium, Inc. All rights reserved.
Copyright (c) 2018, AVOXI, Inc. All rights reserved.
aripy3 is licensed with a BSD 3-Clause License.