198 lines
7.4 KiB
ReStructuredText
198 lines
7.4 KiB
ReStructuredText
pyst2: A Python Interface to Asterisk
|
|
====================================
|
|
|
|
Pyst2 consists of a set of interfaces and libraries to allow programming of
|
|
Asterisk from python. The library currently supports AGI, AMI, and the parsing
|
|
of Asterisk configuration files. The library also includes debugging facilities
|
|
for AGI.
|
|
|
|
This project has been forked from pyst (http://sf.net/projects/pyst/) because
|
|
it was impossible for me to contact the project maintainer (after several
|
|
attempts), and I'd like to bring the project up-to-date, fix bugs, and make
|
|
it more usable overall.
|
|
|
|
My immediate plans include adding full documentation, re-writing some
|
|
of the core routines, adding a test suite, and accepting pull requests.
|
|
|
|
If you are one of the current maintainers, and would like to take over the
|
|
fork, please contact me: rdegges@gmail.com, so we can get that setup!
|
|
|
|
Requirements
|
|
------------
|
|
|
|
1. six
|
|
|
|
Installation
|
|
------------
|
|
|
|
Download from `Github project page`_.
|
|
|
|
.. _`Github project page`: https://github.com/rdegges/pyst2
|
|
|
|
Installation is the standard python install::
|
|
|
|
git clone https://github.com/rdegges/pyst2.git
|
|
cd pyst2
|
|
python setup.py install --prefix=/usr/local
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
Documentation is currently only in python docstrings, you can use
|
|
pythons built-in help facility::
|
|
|
|
import asterisk
|
|
help (asterisk)
|
|
import asterisk.agi
|
|
help (asterisk.agi)
|
|
import asterisk.manager
|
|
help (asterisk.manager)
|
|
import asterisk.config
|
|
help (asterisk.config)
|
|
|
|
Some notes on platforms: We now specify "platforms = 'Any'" in
|
|
``setup.py``. This means, the manager part of the package will probably
|
|
run on any platform. The agi scripts on the other hand are called
|
|
directly on the host where Asterisk is running. Since Asterisk doesn't
|
|
run on windows platforms (and probably never will) the agi part of the
|
|
package can only be run on Asterisk platforms.
|
|
|
|
Credits
|
|
-------
|
|
|
|
Thanks to Karl Putland for writing the original package.
|
|
Thanks to Matthew Nicholson for maintaining the package for some years
|
|
and for handing over maintenance when he was no longer interested.
|
|
Thanks to Randall Degges for maintaining this for and accepting
|
|
pull requests.
|
|
|
|
Things to do for pyst
|
|
---------------------
|
|
|
|
This is the original changelog merged into the readme file. I'm not so
|
|
sure I really want to change all these things (in particular the
|
|
threaded implementation looks good to me). I will maintain a section
|
|
summarizing the changes in this README. Detailed changes will be
|
|
available in the version control tool (currently git).
|
|
|
|
* ChangeLog:
|
|
The ChangeLog needs to be updated from the monotone logs.
|
|
|
|
* Documentation:
|
|
All of pyst's inline documentation needs to be updated.
|
|
|
|
* manager.py:
|
|
This should be converted to be single threaded. Also there is a race
|
|
condition when a user calls manager.logoff() followed by
|
|
manager.close(). The close() function may still call logoff again if
|
|
the socket thread has not yet cleared the _connected flag.
|
|
|
|
A class should be made for each manager action rather than having a
|
|
function in a manager class. The manager class should be adapted to
|
|
have a send method that know the general format of the classes.
|
|
|
|
Matthew Nicholson writes on the mailinglist (note that I'm not sure I'll do
|
|
this, I'm currently satisfied with the threaded implementation):
|
|
|
|
For pyst 0.3 I am planning to clean up the manager.py. There are
|
|
several know issues with the code. No one has actually reported these
|
|
as problems, but I have personally had trouble with these. Currently
|
|
manager.py runs in several threads, the main program thread, a thread to
|
|
read from the network, and an event distribution thread. This causes
|
|
problems with non thread safe code such as the MySQLdb libraries. This
|
|
design also causes problems when an event handler throws an exception
|
|
that causes the event processing thread to terminate.
|
|
|
|
The second problem is with the way actions are sent. Each action has a
|
|
specific function associated with it in the manager object that takes
|
|
all possible arguments that may ever be passed to that action. This
|
|
makes the api somewhat rigid and the Manager object cluttered.
|
|
|
|
To solve these problems I am basically going to copy the design of my
|
|
Astxx manager library (written in c++) and make it more python like.
|
|
Each action will be a different object with certain methods to handle
|
|
various tasks, with one function in the actual Manager class to send the
|
|
action. This will make the Manager class much smaller and much more
|
|
flexible. The current code will be consolidated into a single threaded
|
|
design with hooks to have the library process events and such. These
|
|
hooks will be called from the host application's main loop.
|
|
|
|
|
|
Upgrading from older versions
|
|
-----------------------------
|
|
|
|
If upgrading from...
|
|
|
|
* 0.2:
|
|
|
|
- ``get_header()`` methods in ``manager.py`` now work like
|
|
``dict.get()`` instead of ``dict[key]``
|
|
|
|
|
|
* 0.1.0:
|
|
|
|
- ``agi.get_variable`` no longer throws an exception, instead it
|
|
returns an empty string when a channel variable is not set.
|
|
- ``manager.quit()`` has be renamed to ``manager.close()``
|
|
|
|
Source Code Repository Access
|
|
-----------------------------
|
|
|
|
The current versions are kept in a Subversion repository on Sourceforge.
|
|
You can check out the trunk with::
|
|
|
|
svn co https://pyst.svn.sourceforge.net/svnroot/pyst/pyst/trunk pyst
|
|
|
|
There is also a 0.2 branch in::
|
|
|
|
https://pyst.svn.sourceforge.net/svnroot/pyst/pyst/branches/0.2
|
|
|
|
which contains unreleased changes after 0.2 (which have been merged into
|
|
trunk *after* changing how manager commands to asterisk are parsed).
|
|
|
|
Released versions are in::
|
|
|
|
https://pyst.svn.sourceforge.net/svnroot/pyst/pyst/tags
|
|
|
|
For versions prior to the 0.2 release when Matthew Nicholson was
|
|
maintaining pyst, the changes are kept in a `monotone`_ repository
|
|
(monotone is a free distributed version control system). Please contact
|
|
Matthew via Sourceforge if you're interested in intermediate versions.
|
|
|
|
.. _`monotone`: http://monotone.ca/
|
|
|
|
prior to that the sources are in the CVS repository on sourceforge.
|
|
|
|
|
|
Changes
|
|
-------
|
|
|
|
Version 0.3: Minor feature enhancements
|
|
|
|
New maintainer Ralf Schlatterbeck, this is my first release, please
|
|
report any problems via the Sourceforge Bug-Tracker or email me
|
|
directly. Thanks to Karl Putland for writing the original package.
|
|
Thanks to Matthew Nicholson for maintaining the package for some years
|
|
and for handing over maintenance when he was no longer interested.
|
|
The parsing of answers from asterisk was completely rewritten. This
|
|
should fix problems people were having with commands returning embedded
|
|
'/' or empty lines. Some new manager commands added.
|
|
|
|
- Add playdtmf manager command
|
|
- add sippeers and sipshowpeer manager commands
|
|
- rewritten manager communication
|
|
- should no longer choke on '/' in answers returned from a manager
|
|
command (fixes SF Bug 2947866)
|
|
- should now correctly parse multi-line output with embedded empty
|
|
lines, e.g. ``mgr.command('dialplan show')``
|
|
- Bug-fix for list manipulation in ``event_dispatch``, thanks to Jan
|
|
Mueller, see mailinglist comment from 2008-04-18
|
|
- Merge unreleased changes from repository of Matthew Nicholson
|
|
in particular a typo in ``agi.py`` for ``set_autohangup``, and change
|
|
of ``get_header`` methods (see Upgrading instructions). The fixed
|
|
``manager.command`` support is already in (with a different
|
|
solution). The unreleased changes are also on the 0.2 branch in the
|
|
subversion repository in case somebody is interested.
|
|
|
|
See the ChangeLog for older changes.
|