The source code is maintained in the Dataflake Git repository. To check out the trunk:
$ git clone https://git.dataflake.org/git/dataflake.ldapconnection
You can also browse the code online at http://git.dataflake.org/cgit/dataflake.ldapconnection
For bug reports, suggestions or questions please use the Launchpad bug tracker at https://bugs.launchpad.net/dataflake.ldapconnection .
Note
Please ensure that all tests are passing before you submit your code. If possible, your submission should include new tests for new features or bug fixes, although it is possible that you may have tested your new code by updating existing tests.
If you got a read-only checkout from the Git repository, and you have made a change you would like to share, the best route is to let Git help you make a patch file:
$ git diff > dataflake.ldapconnection-cool_feature.patch
You can then upload that patch file as an attachment to a Launchpad bug report.
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/virtualpy
Next, get this package registered as a “development egg” in the environment:
$ /tmp/virtualpy/bin/python setup.py develop
Finally, run the tests using the build-in setuptools testrunner:
$ /tmp/virtualpy/bin/python setup.py test
running test
...
test_escape_dn (dataflake.ldapconnection.tests.test_utils.UtilsTest) ... ok
----------------------------------------------------------------------
Ran 88 tests in 0.058s
OK
If you have the nose package installed in the virtualenv, you can use its testrunner too:
$ /tmp/virtualpy/bin/easy_install nose
...
$ /tmp/virtualpy/bin/python setup.py nosetests
running nosetests
......................................................................
...............................
----------------------------------------------------------------------
Ran 101 tests in 0.162s
OK
or:
$ /tmp/virtualpy/bin/nosetests
......................................................................
...............................
----------------------------------------------------------------------
Ran 101 tests in 0.160s
OK
If you have the coverage package installed in the virtualenv, you can see how well the tests cover the code:
$ /tmp/virtualpy/bin/easy_install nose coverage
...
$ /tmp/virtualpy/bin/python setup.py nosetests \
--with-coverage --cover-package=dataflake.ldapconnection
running nosetests
...
Name Stmts Exec Cover Missing
-------------------------------------------------------------------
dataflake.ldapconnection 1 1 100%
dataflake.ldapconnection.connection 246 244 99% 214-215
dataflake.ldapconnection.interfaces 10 10 100%
dataflake.ldapconnection.utils 7 7 100%
-------------------------------------------------------------------
TOTAL 264 262 99%
----------------------------------------------------------------------
Ran 101 tests in 0.226s
OK
dataflake.ldapconnection 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/virtualpy/bin/easy_install Sphinx
...
$ cd docs
$ PATH=/tmp/virtualpy/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:
$ PATH=/tmp/virtualpy/bin:$PATH make doctest
sphinx-build -b doctest -d _build/doctrees . _build/doctest
...
running tests...
Doctest summary
===============
0 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.
dataflake.ldapconnection ships with its own buildout.cfg file and bootstrap.py for setting up a development buildout:
$ python bootstrap.py
...
Generated script '.../bin/buildout'
$ bin/buildout
...
Once you have a buildout, the tests can be run as follows:
$ bin/test --all
Running tests at all levels
Running zope.testing.testrunner.layer.UnitTests tests:
Set up zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
Running:
.....................................................................
.........................
Ran 94 tests with 0 failures and 0 errors in 0.042 seconds.
Tearing down left over layers:
Tear down zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
The dataflake.ldapconnection buildout installs the Sphinx scripts required to build the documentation, including testing its code snippets:
$ bin/docbuilder.sh
rm -rf _build/*
sphinx-build -b doctest -d _build/doctrees . _build/doctest
Making output directory...
Running Sphinx v1.1.3
...
running tests...
Doctest summary
===============
0 tests
0 failures in tests
0 failures in setup code
build succeeded.
Testing of doctests in the sources finished, look at the results in \
.../docs/_build/doctest/output.txt.
.../bin/sphinx-build -b html -d .../docs/_build/doctrees \
.../docs .../docs/_build/html
...
build succeeded.
Build finished. The HTML pages are in .../docs/_build/html.
To build the documentation as PDF you first need to ensure your system has a latex2pdf binary installed.
$ bin/pdfbuilder.sh
sphinx-build -b latex -d _build/doctrees . _build/latex
Making output directory...
Running Sphinx v1.1.3
...
Output written on dataflake.ldapconnection.pdf (23 pages, 128015 bytes).
Transcript written on dataflake.ldapconnection.log.
These instructions assume that you have a development sandbox set up using zc.buildout as the scripts used here are generated by the buildout.
The first thing to do when making a release is to check that the ReST to be uploaded to PyPI is valid:
$ bin/docpy setup.py --long-description | bin/rst2 html \
--link-stylesheet \
--stylesheet=http://www.python.org/styles/styles.css > desc.html
Once you’re certain everything is as it should be, the following will build the distribution, upload it to PyPI, register the metadata with PyPI and upload the Sphinx documentation to PyPI:
$ bin/buildout -o
$ bin/docbuilder.sh
$ bin/pdfbuilder.sh
$ bin/docpy setup.py sdist register upload upload_sphinx \
--upload-dir=docs/_build/html
The bin/buildout step will make sure the correct package information is used.