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
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).