Development

Getting set up

Getting the source code

Obelus is developed using Mercurial and its source respository is hosted at BitBucket.

To make a local clone of the repository, use:

$ hg clone https://bitbucket.org/optiflowsrd/obelus

Coding conventions

Obelus follows the PEP 8 coding style. Read it!

Regression tests

The automated test suite is hosted in the obelus.test package. It uses the standard unittest module as well as the third-party mock library (bundled as unittest.mock starting from Python 3.3).

You can run the test suite simply by invoking the obelus.test package:

$ python -m obelus.test

(various options are available, such as -v to print each test name as it is run; use -h to list available options)

Documentation

The documentation uses Sphinx and resides inside the docs directory. To build it, install Sphinx, go inside the docs directory and type:

$ make html

The result will be available in docs/_build/html.

Code coverage testing

To measure which parts of the code are covered by the test suite, use the supplied run_coverage.py script (the coverage library must be installed). HTML-formatted results are then available inside the htmlcov directory: point your browser to the index.html file inside that directory.

All-in-one integration testing: tox

It is actually possible to automate all the above by using the tox utility. Tox will create a series of local environments, fetch the required dependencies for each of them and run the desired command inside each of them. Currently, the actions ran by tox include:

  • running the test suite under Python 2.7, 3.2 and 3.3
  • running the test suite with code coverage enabled, so as to create the coverage report in htmlcov
  • building the documentation and making the result available in docs/_build/html

(this is all described in the tox.ini file at the root of the source tree)

All you have to do is to type this single command:

$ tox

Note that you can select a single “environment” (or action) to run; for example, to only re-build the docs, type:

$ tox -e docs

Contributing

Contributions are welcome. The ecosystem of Python Asterisk libraries is currently fragmented; Obelus’ design ambitions to achieve reusability in more contexts than the usual per-framework, per-programming style segregation.

If you have code to contribute (either a new feature, an enhancement or a bug fix), you can fork the repository on BitBucket and create a pull request with your changes.

If you want to contribute documentation, you can either use the same workflow as for code or (for small changes) open an issue on the tracker with your suggested changes.

If you want to discuss a potential change or problem, please either create an issue on the issue tracker or contact the author by e-mail.

Guidelines

Here are some formal guidelines for code changes:

  • Your change must have unit tests for it
  • Your code must respect PEP 8 and the general coding style of the library
  • Your code must be compatible with Python 2.7, 3.2 and later (running tox helps ensure that, see above)
  • Your code must not break existing tests.

There are also some design principles which new code should abide by:

  • Global state is shunned, because it limits the library’s flexibility and also because it makes testing more painful.
  • Actual I/O (input / output) should be separated into specialized modules or objects, such as the existing adapters.
  • The core classes should be event-driven, and never block waiting on external events.

Avenues for development

If you are looking for ideas or wondering what is currently lacking, here are a bunch of suggestions:

  • Add high-level methods to obelus.agi.AGISession exposing the various AGI commands (as pyst does).
  • Develop unit tests for the Tornado and Twisted adapters.
  • Make the CLI examples more featureful.
  • Investigate if obelus.common.Handler can be made to resemble PEP 3156 Futures (perhaps by reusing Tornado’s _DummyFuture implementation?).
  • Investigate if obelus.common.Handler can be integrated into Tornado and Twisted coroutines (this may or may not be the same question as the previous one).