Hacking on zope.exceptions
¶
Getting the Code¶
The main repository for zope.exceptions
is in the Zope Foundation
Github repository:
You can get a read-only checkout from there:
$ git clone https://github.com/zopefoundation/zope.exceptions.git
or fork it and get a writeable checkout of your fork:
$ git clone git@github.com/jrandom/zope.exceptions.git
The project also mirrors the trunk from the Github repository as a Bazaar branch on Launchpad:
https://code.launchpad.net/zope.exceptions
You can branch the trunk from there using Bazaar:
$ bzr branch lp:zope.exceptions
Working in a virtualenv
¶
Installing¶
If you use the virtualenv
package to create lightweight Python
development environments, you can run the tests using nothing more
than the python
binary in a virtualenv. First, create a scratch
environment:
$ /path/to/virtualenv --no-site-packages /tmp/hack-zope.exceptions
Next, get this package registered as a “development egg” in the environment:
$ /tmp/hack-zope.exceptions/bin/python setup.py develop
Running the tests¶
Run the tests using the build-in setuptools
testrunner:
$ /tmp/hack-zope.exceptions/bin/python setup.py test -q
running test
...---------------------------------------------------------------------
----------------------------------------------------------------------
Ran 72 tests in 0.017s
OK
If you have the nose
package installed in the virtualenv, you can
use its testrunner too:
$ /tmp/hack-zope.exceptions/bin/easy_install nose
...
$ /tmp/hack-zope.exceptions/bin/python setup.py nosetests
running nosetests
........................................................................
----------------------------------------------------------------------
Ran 73 tests in 0.010s
OK
or:
$ /tmp/hack-zope.exceptions/bin/nosetests
........................................................................
----------------------------------------------------------------------
Ran 73 tests in 0.011s
OK
If you have the coverage
pacakge installed in the virtualenv,
you can see how well the tests cover the code:
$ /tmp/hack-zope.exceptions/bin/easy_install nose coverage
...
$ /tmp/hack-zope.exceptions/bin/python setup.py nosetests \
--with coverage --cover-package=zope.exceptions
running nosetests
...
.........................................................................
Name Stmts Miss Cover Missing
------------------------------------------------------------------
zope.exceptions 10 0 100%
zope.exceptions.exceptionformatter 171 0 100%
zope.exceptions.interfaces 18 0 100%
zope.exceptions.log 13 0 100%
------------------------------------------------------------------
TOTAL 212 0 100%
----------------------------------------------------------------------
OK
Building the documentation¶
zope.exceptions
uses the nifty Sphinx
documentation system
for building its docs. Using the same virtualenv you set up to run the
tests, you can build the docs:
$ /tmp/hack-zope.exceptions/bin/easy_install Sphinx
...
$ cd docs
$ PATH=/tmp/hack-zope.exceptions/bin:$PATH make html
sphinx-build -b html -d _build/doctrees . _build/html
...
build succeeded.
Build finished. The HTML pages are in _build/html.
You can also test the code snippets in the documentation:
$ bin/sphinx-build -b docs/doctest -d docs/_build/doctrees docs docs/_build/doctest
...
12 tests in 1 items.
12 passed and 0 failed.
Test passed.
Doctest summary
===============
12 tests
0 failures in tests
0 failures in setup code
build succeeded.
Testing of doctests in the sources finished, look at the \
results in _build/doctest/output.txt.
Using zc.buildout
¶
Setting up the buildout¶
zope.exceptions
ships with its own buildout.cfg
file and
bootstrap.py
for setting up a development buildout:
$ /path/to/python2.6 bootstrap.py
...
Generated script '.../bin/buildout'
$ bin/buildout
Develop: '/home/jrandom/projects/Zope/BTK/exceptions/.'
...
Generated script '.../bin/sphinx-quickstart'.
Generated script '.../bin/sphinx-build'.
Running the tests¶
Run the tests:
$ bin/test --all
Running zope.testing.testrunner.layer.UnitTests tests:
Set up zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
Ran 2 tests with 0 failures and 0 errors in 0.000 seconds.
Tearing down left over layers:
Tear down zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
Using tox
¶
Running Tests on Multiple Python Versions¶
tox is a Python-based test automation
tool designed to run tests against multiple Python versions. It creates
a virtualenv
for each configured version, installs the current package
and configured dependencies into each virtualenv
, and then runs the
configured commands.
zope.exceptions
configures the following tox
environments via
its tox.ini
file:
The
py26
,py27
,py33
,py34
, andpypy
environments builds avirtualenv
withpypy
, installszope.exceptions
and dependencies, and runs the tests viapython setup.py test -q
.The
coverage
environment builds avirtualenv
withpython2.6
, installszope.exceptions
, installsnose
andcoverage
, and runsnosetests
with statement coverage.The
docs
environment builds a virtualenv withpython2.6
, installszope.exceptions
, installsSphinx
and dependencies, and then builds the docs and exercises the doctest snippets.
This example requires that you have a working python2.6
on your path,
as well as installing tox
:
$ tox -e py26
GLOB sdist-make: .../zope.interface/setup.py
py26 sdist-reinst: .../zope.interface/.tox/dist/zope.interface-4.0.2dev.zip
py26 runtests: commands[0]
...---------------------------------------------------------------------
----------------------------------------------------------------------
Ran 72 tests in 0.000s
OK
___________________________________ summary ____________________________________
py26: commands succeeded
congratulations :)
Running tox
with no arguments runs all the configured environments,
including building the docs and testing their snippets:
$ tox
GLOB sdist-make: .../zope.interface/setup.py
py26 sdist-reinst: .../zope.interface/.tox/dist/zope.interface-4.0.2dev.zip
py26 runtests: commands[0]
...
Doctest summary
===============
12 tests
0 failures in tests
0 failures in setup code
0 failures in cleanup code
build succeeded.
___________________________________ summary ____________________________________
py26: commands succeeded
py27: commands succeeded
py32: commands succeeded
pypy: commands succeeded
coverage: commands succeeded
docs: commands succeeded
congratulations :)
Contributing to zope.exceptions
¶
Submitting a Bug Report¶
zope.exceptions
tracks its bugs on Github:
Please submit bug reports and feature requests there.