Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

Tree [8b8882] master /
History



File Date Author Commit
asterisk 2014-07-23 Matthias Urlichs Matthias Urlichs [9c354d] Py3 exception syntax
debian 2014-07-23 Matthias Urlichs Matthias Urlichs [8b8882] Fix debian/rules
rpm 2006-06-05 Matthew Nicholson Matthew Nicholson [191a9f] Bump version numbers to 0.1.0.
test 2014-04-19 Ralf Schlatterbeck Ralf Schlatterbeck [7f3e19] Make manager run with python3.3
.gitignore 2014-07-23 Matthias Urlichs Matthias Urlichs [1d1538] Ignore build files etc.
ChangeLog 2014-04-15 Ralf Schlatterbeck Ralf Schlatterbeck [eb12f9] Add note that Changlog is no longer maintained
MANIFEST.in 2014-04-17 Ralf Schlatterbeck Ralf Schlatterbeck [9a963e] Complete renaming of README, Releasetools
Makefile 2014-04-17 Ralf Schlatterbeck Ralf Schlatterbeck [9a963e] Complete renaming of README, Releasetools
README.rst 2014-04-15 Ralf Schlatterbeck Ralf Schlatterbeck [b87fcd] Changes for new GIT repository
run_tests.py 2013-05-29 Ralf Schlatterbeck Ralf Schlatterbeck [ac9d88] Start python3 compatibility
setup.py 2014-04-17 Ralf Schlatterbeck Ralf Schlatterbeck [9a963e] Complete renaming of README, Releasetools

Read Me

SourceForge.net Logo

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.

News: The source code is now in a GIT repository on Sourceforge. To check out anonymously into the local directory pyst, use:

git clone git://git.code.sf.net/p/pyst/code pyst

Thanks to Eric S. Raymond's reposurgeon, it was possible to unite the old CVS repository, the monotone repository used until 0.2 (and a little beyond 0.2) and the recent subversion repository into one git repository that contains the whole history and cleans up some artefacts.

A note on maintenance and forks: The current maintainer is Ralf Schlatterbeck. I've contacted maintainers of forks to try to join forces. For any questions, please contact me via rsc@runtux.com or my sourceforge user.

Download from Sourceforge project page.

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)

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 in which case they are limited to the platforms asterisk is running on. Alternatively, you can use the fastagi mechanism of asterisk which calls the agi scripts on a remote host. In the latter case this host can be any platform where python runs.

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 also to the people in the sourceforge project and those who just report bugs: Antoine Brenner, Max Nesterov, Sven Uebelacker

... and to unnamed contributors to earlier releases.

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.

  • 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 GIT repository on Sourceforge. You can check out the trunk with:

git clone git://git.code.sf.net/p/pyst/code pyst

There is a monotone-after-0.2 branch which contains unreleased changes after 0.2 which were committed to the monotone repository after the Release of Version 0.2 (which have been merged into trunk after changing how manager commands to asterisk are parsed).

Released versions are tagged, see the tags in the web-interface on Sourceforge (or use local git commands to find out)

https://sourceforge.net/p/pyst/code/ci/master/tree/

For versions up to 0.6 the code was kept in a Subversion repository in Sourceforge. This has been incorporated into the current GIT repository (after cleaning up some subversion artefacts).

For versions prior to the 0.2 release when Matthew Nicholson was maintaining pyst, the changes were kept in a monotone repository (monotone is a free distributed version control system). This repository has also been incorporated into the GIT repository.

prior to that the sources are in the CVS repository on sourceforge which has also been incorporated into the GIT repository.

Changes

Version 0.6: Minor feature enhancements

The asterisk management interface emulator asterisk/astemu now can be used for unit-tests of applications using asterisk.manager. We're using this in the regression test (see test directory). But this way it is usable by others.

  • Factor asterisk emulator from regression test into own module

Version 0.5: Small install change

Fix setup.py to include download_url. This makes it installable using intall tools like pip.

  • Add download_url to setup.py
  • Fix svn url after SourceForge upgrade

Version 0.4: Minor feature enhancements

Small feature extensions to AGI and Manager modules. Add a regression test which now covers some aspects of the manager API.

  • Handle events with several fields with the same name (e.g. 'Variable' in the 'AgentCalled' event. Thanks to Max Nesterov for the suggestion, implementation differs from the suggestion in SF patch 3290869. For a use-case see the give SF patch and the regression test case test_agent_event.
  • Allow to use AGI module in FastAGI way via TCP connection. This change allows you to specify the socket streams instead sys.stdin/sys.stdout streams. Thanks to Max Nesterov for the patch. Applies SF patch 3047290.
  • Add regression test framework and some test cases for manager API.
  • The generated ActionID for the manager interface now includes the process-ID, this allows several concurrent processes using the manager API.

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.