Developer Documentation AKA ‘Hacking’ the Library

This document describes the process for “hacking” the Python Fat Cookie Library.

Getting the Source

The easiest way to get the source is to use subversion on utforge (EID Required). From a command line run:

$ svn co https://utforge.its.utexas.edu/repos/PythonFatCookie/trunk python-cookie

This will create a folder called python-cookie in the current directory will the latest version of the source. The source files are arranged roughly like this:

• docs/
  • build/html/ – documentation rendered in html
  • source/ – documentation in reStructuredText
  • Makefile – sphinx documentation make file
• pycookie/
  • __init__.py – pycookie.get_version(), Static FC Variables
  • cookie.py – pycookie.FatCookie Class and FatCookieException
  • helpers.py – pycookie.helpers.Role Class and functions that clean the data before the FatCookie class is saved.
• test/
  • test_cookie.py – Fat Cookie Library tests

You can also browse the source on utforge (EID required) without downloading it.

Running the Fat Cookie Test Suite

The test suite has been tested on Linux, Mac 10.5 and Windows all running python 2.5. In order to submit a feature request with a patch you’ll need to make sure the tests continue to pass along with new tests for your feature.

To run the tests simply type the command:

$ cd (pycookie_src_folder)/test/
$ python test_cookie.py

You should see the following output:

.....................
----------------------------------------------------------------------
Ran 21 tests in 0.011s

OK

The test suite uses the python standard unittest suite. If you are unfamiliar with this please read up about it first. Basically the tests just attempt to call a function and verify the results, or verify an exception was raised.

Building the Fat Cookie Library Documentation

Note

The documentation requires that you have sphinx installed properly please refer to the Dependencies.

The documentation source is all contained in the ./docs/source/ directory and is written in reStructuredText with the help of sphinx. This allows the documentation to be read without any special tools and also makes the marked up version available as a pretty web page. You can view the Python Fat Cookie Library Documentation online.

Using Make

If you have make install simply run the following command in the docs directory:

$ make html

or to make pdf’s (you will need pdflatex):

$ make latex
$ cd build/latex
$ make all-pdf

View the output in ./docs/build/html/

Using the command line

If you don’t have make you can build the docs with the sphinx-build command:

$ sphinx-build ./docs/source ./docs/build/html

or for latex:

$ sphinx-build -b latex ./docs/source ./docs/build/latex