141 lines
5.5 KiB
Plaintext
141 lines
5.5 KiB
Plaintext
.. image:: http://sflogo.sourceforge.net/sflogo.php?group_id=134329&type=7
|
||
:height: 62
|
||
:width: 210
|
||
:alt: SourceForge.net Logo
|
||
:target: http://sourceforge.net
|
||
|
||
pyst: A Python Interface to Asterisk
|
||
====================================
|
||
|
||
Pyst 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.
|
||
|
||
Installation is the standard python install::
|
||
|
||
tar xvf pyst.tar.gz
|
||
cd pyst
|
||
python setup.py install --prefix=/usr/local
|
||
|
||
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)
|
||
|
||
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.
|
||
|
||
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, the ChangeLog won't be
|
||
maintained any longer. Detailed changes will be available in the version
|
||
control tool (currently svn).
|
||
|
||
* 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 convereted 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()``
|
||
|
||
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
|
||
M<>ller, 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.
|