Hacking on Pyramid
|
==================
|
|
Here are some guidelines about hacking on Pyramid.
|
|
Using a Development Checkout
|
----------------------------
|
|
You'll have to create a development environment to hack on Pyramid, using a
|
Pyramid checkout. You can either do this by hand or, if you have ``tox``
|
installed (it's on PyPI), you can (ab)use tox to get a working development
|
environment. Each installation method is described below.
|
|
By Hand
|
+++++++
|
|
- Check out Pyramid from source::
|
|
$ cd ~
|
$ git clone git://github.com/Pylons/pyramid.git hack-on-pyramid
|
$ cd hack-on-pyramid
|
|
- Create a virtualenv in which to install Pyramid::
|
|
$ cd ~/hack-on-pyramid
|
$ virtualenv -ppython2.7 env
|
|
Note that very old versions of virtualenv (virtualenv versions below, say,
|
1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to
|
get a completely isolated environment.
|
|
You can choose which Python version you want to use by passing a ``-p``
|
flag to ``virtualenv``. For example, ``virtualenv -ppython2.7``
|
chooses the Python 2.7 interpreter to be installed.
|
|
From here on in within these instructions, the ``~/hack-on-pyramid/env``
|
virtual environment you created above will be referred to as ``$VENV``.
|
To use the instructions in the steps that follow literally, use the
|
``export VENV=~/hack-on-pyramid/env`` command.
|
|
- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
|
using git to do version control)::
|
|
$ $VENV/bin/easy_install setuptools-git
|
|
- Install Pyramid from the checkout into the virtualenv using ``setup.py
|
dev``. ``setup.py dev`` is an alias for "setup.py develop" which also
|
installs testing requirements such as nose and coverage. Running
|
``setup.py dev`` *must* be done while the current working directory is the
|
``pyramid`` checkout directory::
|
|
$ cd ~/hack-on-pyramid
|
$ $VENV/bin/python setup.py dev
|
|
- At that point, you should be able to create new Pyramid projects by using
|
``pcreate``::
|
|
$ cd $VENV
|
$ bin/pcreate -s starter starter
|
|
- And install those projects (also using ``setup.py develop``) into the
|
virtualenv::
|
|
$ cd $VENV/starter
|
$ $VENV/bin/python setup.py develop
|
|
Using Tox
|
+++++++++
|
|
Alternatively, if you already have ``tox`` installed, there is an easier
|
way to get going.
|
|
- Create a new directory somewhere and ``cd`` to it::
|
|
$ mkdir ~/hack-on-pyramid
|
$ cd ~/hack-on-pyramid
|
|
- Check out a read-only copy of the Pyramid source::
|
|
$ git clone git://github.com/Pylons/pyramid.git .
|
|
(alternately, create a writeable fork on GitHub and check that out).
|
|
Since Pyramid is a framework and not an application, it can be
|
convenient to work against a sample application, preferably in its own
|
virtualenv. A quick way to achieve this is to (ab-)use ``tox``
|
(http://tox.readthedocs.org/en/latest/) with a custom configuration
|
file that's part of the checkout::
|
|
tox -c hacking-tox.ini
|
|
This will create a python-2.7 based virtualenv named ``env27`` (Pyramid's
|
``.gitconfig` ignores all top-level folders that start with ``env`` specifically
|
for this use case) and inside that a simple pyramid application named
|
``hacking`` that you can then fire up like so::
|
|
cd env27/hacking
|
../bin/pserve development.ini
|
|
Adding Features
|
---------------
|
|
In order to add a feature to Pyramid:
|
|
- The feature must be documented in both the API and narrative
|
documentation (in ``docs/``).
|
|
- The feature must work fully on the following CPython versions: 2.6,
|
2.7, 3.2, and 3.3 on both UNIX and Windows.
|
|
- The feature must work on the latest version of PyPy.
|
|
- The feature must not cause installation or runtime failure on App Engine.
|
If it doesn't cause installation or runtime failure, but doesn't actually
|
*work* on these platforms, that caveat should be spelled out in the
|
documentation.
|
|
- The feature must not depend on any particular persistence layer
|
(filesystem, SQL, etc).
|
|
- The feature must not add unnecessary dependencies (where
|
"unnecessary" is of course subjective, but new dependencies should
|
be discussed).
|
|
The above requirements are relaxed for scaffolding dependencies. If a
|
scaffold has an install-time dependency on something that doesn't work on a
|
particular platform, that caveat should be spelled out clearly in *its*
|
documentation (within its ``docs/`` directory).
|
|
Coding Style
|
------------
|
|
- PEP8 compliance. Whitespace rules are relaxed: not necessary to put
|
2 newlines between classes. But 80-column lines, in particular, are
|
mandatory. See
|
http://docs.pylonsproject.org/en/latest/community/codestyle.html for more
|
information.
|
|
- Please do not remove trailing whitespace. Configure your editor to reduce
|
diff noise. See https://github.com/Pylons/pyramid/issues/788 for more.
|
|
Running Tests
|
--------------
|
|
- To run all tests for Pyramid on a single Python version, run ``nosetests``
|
from your development virtualenv (See *Using a Development Checkout* above).
|
|
- To run individual tests (i.e. during development) you can use a regular
|
expression with the ``-t`` parameter courtesy of the `nose-selecttests
|
<https://pypi.python.org/pypi/nose-selecttests/>`_ plugin that's been
|
installed (along with nose itself) via ``python setup.py dev``. The
|
easiest usage is to simply provide the verbatim name of the test you're
|
working on.
|
|
- To run the full set of Pyramid tests on all platforms, install ``tox``
|
(http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console
|
script will be installed into the scripts location for that Python. While
|
``cd``'ed to the Pyramid checkout root directory (it contains ``tox.ini``),
|
invoke the ``tox`` console script. This will read the ``tox.ini`` file and
|
execute the tests on multiple Python versions and platforms; while it runs,
|
it creates a virtualenv for each version/platform combination. For
|
example::
|
|
$ sudo /usr/bin/easy_install tox
|
$ cd ~/hack-on-pyramid/
|
$ /usr/bin/tox
|
|
- The tests can also be run using ``pytest`` (http://pytest.org/). This is
|
intended as a convenience for people who are more used or fond of ``pytest``.
|
Run the tests like so::
|
|
$ $VENV/bin/easy_install pytest
|
$ py.test --strict pyramid/
|
|
Test Coverage
|
-------------
|
|
- The codebase *must* have 100% test statement coverage after each commit.
|
You can test coverage via ``tox -e coverage``, or alternately by installing
|
``nose`` and ``coverage`` into your virtualenv (easiest via ``setup.py
|
dev``) , and running ``setup.py nosetests --with-coverage``.
|
|
Documentation Coverage and Building HTML Documentation
|
------------------------------------------------------
|
|
If you fix a bug, and the bug requires an API or behavior modification, all
|
documentation in this package which references that API or behavior must
|
change to reflect the bug fix, ideally in the same commit that fixes the bug
|
or adds the feature.
|
|
To build and review docs (where ``$VENV`` refers to the virtualenv you're
|
using to develop Pyramid):
|
|
1. After following the steps above in "Using a Development Checkout", cause
|
Sphinx and all development requirements to be installed in your
|
virtualenv::
|
|
$ cd ~/hack-on-pyramid
|
$ $VENV/bin/python setup.py docs
|
|
2. Update all git submodules from the top-level of your Pyramid checkout, like
|
so::
|
|
$ git submodule update --init --recursive
|
|
This will checkout theme subrepositories and prevent error conditions when
|
HTML docs are generated.
|
|
3. cd to the ``docs`` directory within your Pyramid checkout and execute
|
the ``make`` command with some flags::
|
|
$ cd ~/hack-on-pyramid/pyramid/docs
|
$ make clean html SPHINXBUILD=$VENV/bin/sphinx-build
|
|
The ``SPHINXBUILD=...`` hair is there in order to tell it to use the
|
virtualenv Python, which will have both Sphinx and Pyramid (for API
|
documentation generation) installed.
|
|
4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML
|
rendering.
|
|
Change Log
|
----------
|
|
- Feature additions and bugfixes must be added to the ``CHANGES.txt``
|
file in the prevailing style. Changelog entries should be long and
|
descriptive, not cryptic. Other developers should be able to know
|
what your changelog entry means.
|
