For Developers

If you would like to contribute to ECget directly, these instructions should help you get started. Bug reports and feature requests are all welcome through the Bitbucket project.

Changes to ECget should be submitted as pull requests on Bitbucket project.

Bugs should be files under the Bitbucket project.

Note

Before contributing new features to ECget, please consider whether they should be implemented as an extension instead. The architecture is highly pluggable precisely to keep the core small.

Development Environment

ECget is developed under Python 3.3 and tested under Python 2.7 and Python 3.2. Setting up a Python 3.3 virtualenv via pyvenv is a little tricky because pyvenv doesn’t install/include pip and setuptools. These commands should result in a viable, working Python 3.3 virtual environment:

pyvenv-3.3 ecget
cd ecget
(ecget)$ . bin/activate
(ecget)$ curl -O https://raw.github.com/pypa/pip/master/contrib/get-pip.py
(ecget)$ python3.3 get-pip.py

Thanks to Richard Jones for those commands.

After cloning the source code repo from the Bitbucket project, the Python packages at the versions used for development at tip can be installed with:

(ecget)$ pip install -r requirements.txt

Install the ECget package for development with:

(ecget)$ cd ecget
(ecget)$ pip install -e .

or

(ecget)$ cd ecget
(ecget)$ python setup.py develop

Note

Because ECget uses setuptools entry points for plug-in discovery it is necessary to install the package whenever entry points are changed or added in setup.py.

Building Documentation

The documentation for ECget is written in reStructuredText and converted to HTML using Sphinx. The build itself is driven by make. Installing the development packages via the requirements.txt file as described above will install Sphinx. Once that has been done use:

(ecget)$ (cd docs && make clean html)
rm -rf _build/*
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.2.1
loading pickled environment... done
building [html]: targets for 3 source files that are out of date
updating environment: 3 added, 0 changed, 0 removed
reading sources... [100%] install
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] install
writing additional files... (0 module code pages) genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

to generate the HTML version of the documentation. The output ends up in ./docs/_build/html/ in your development directory.

Running Tests

The test suite for ECget uses pytest, coverage, and tox. Installing the development packages via the requirements.txt file as described in the Development Environment section above will install those packages and their dependencies.

Use the py.test command from the top level directory of the Mercurial repository to run the test suite in the development environment:

(ecget)$ py.test
======================================= test session starts ========================================
platform darwin -- Python 3.3.2 -- pytest-2.5.1
collected 1 items

tests/test_SOG_formatters.py .

===================================== 1 passed in 0.13 seconds =====================================

To gather test coverage data use coverage run -m py.test and view the coverage report with coverage report:

(ecget)$ coverage report
Name                        Stmts   Miss Branch BrMiss  Cover   Missing
-----------------------------------------------------------------------
ecget/SOG_formatters            9      0      4      2    85%
ecget/__init__                  0      0      0      0   100%
ecget/main                     12     12      2      2     0%   22-45
ecget/river                   110    110     24     24     0%   18-229
tests/test_SOG_formatters       9      0      0      0   100%
-----------------------------------------------------------------------
TOTAL                         140    122     30     28    12%

The default coverage run and report option values are set in the .coveragerc file.

Use the tox command to run the tests under Python 3.3, 3.2, and 2.7.

Note

You must have all of those versions of Python installed on your system for tox to succeed.

To run the tests under a single version of Python, specify the appropriate environment when running tox:

(ecget)$ tox -e py27