| | |
|---|
| | | Hacking on Pyramid |
|---|
| | | ================== |
|---|
| | | |
|---|
| | | Here are some guidelines about hacking on Pyramid. |
|---|
| | | Here are some guidelines for hacking on Pyramid. |
|---|
| | | |
|---|
| | | |
|---|
| | | Using a Development Checkout |
|---|
| | | ---------------------------- |
|---|
| | | |
|---|
| | | Below is a quick start on creating a development environment using a Pyramid |
|---|
| | | checkout. |
|---|
| | | You will have to create a development environment to hack on Pyramid, using a |
|---|
| | | Pyramid checkout. We use `tox` to run tests, run test coverage, and build |
|---|
| | | documentation. |
|---|
| | | |
|---|
| | | - Create a new directory somewhere and ``cd`` to it:: |
|---|
| | | tox docs: https://tox.readthedocs.io/en/latest/ |
|---|
| | | tox on PyPI: https://pypi.org/project/tox/ |
|---|
| | | |
|---|
| | | $ mkdir ~/hack-on-pyramid |
|---|
| | | $ cd ~/hack-on-pyramid |
|---|
| | | - Create a new directory somewhere and `cd` to it: |
|---|
| | | |
|---|
| | | - Check out a read-only copy of the Pyramid source:: |
|---|
| | | $ mkdir ~/hack-on-pyramid |
|---|
| | | $ cd ~/hack-on-pyramid |
|---|
| | | |
|---|
| | | $ git clone git://github.com/Pylons/pyramid.git |
|---|
| | | - Check out a read-only copy of the Pyramid source: |
|---|
| | | |
|---|
| | | (alternately, create a writeable fork on GitHub and check that out). |
|---|
| | | $ git clone git://github.com/Pylons/pyramid.git . |
|---|
| | | |
|---|
| | | - Create a virtualenv in which to install Pyramid:: |
|---|
| | | Alternatively, create a writeable fork on GitHub and clone it. |
|---|
| | | |
|---|
| | | $ virtualenv2.6 --no-site-packages env |
|---|
| | | |
|---|
| | | - Install ``setuptools-git`` into the virtualenv (for good measure, as we're |
|---|
| | | using git to do version control):: |
|---|
| | | |
|---|
| | | $ env/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 pyramid |
|---|
| | | $ ../env/bin/python setup.py dev |
|---|
| | | |
|---|
| | | - At that point, you should be able to create new Pyramid projects by using |
|---|
| | | ``pcreate``:: |
|---|
| | | |
|---|
| | | $ cd ../env |
|---|
| | | $ bin/pcreate -s starter starter |
|---|
| | | |
|---|
| | | - And install those projects (also using ``setup.py develop``) into the |
|---|
| | | virtualenv:: |
|---|
| | | |
|---|
| | | $ cd starter |
|---|
| | | $ ../bin/python setup.py develop |
|---|
| | | |
|---|
| | | 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 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, and 3.2 on both UNIX and Windows. |
|---|
| | | - The feature must work fully on the following CPython versions: 2.7, 3.4, 3.5, |
|---|
| | | 3.6, and 3.7 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 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 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). |
|---|
| | | |
|---|
| | | 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. |
|---|
| | | - Pyramid uses Black for code formatting style. |
|---|
| | | https://pypi.org/project/black/ |
|---|
| | | To run Black: |
|---|
| | | |
|---|
| | | - Please do not remove trailing whitespace. Configure your editor to reduce |
|---|
| | | diff noise. |
|---|
| | | $ tox -e black |
|---|
| | | |
|---|
| | | |
|---|
| | | Running Tests |
|---|
| | | -------------- |
|---|
| | | ------------- |
|---|
| | | |
|---|
| | | - To run tests for Pyramid on a single Python version, run ``python setup.py |
|---|
| | | test`` against the Python interpreter from virtualenv into which |
|---|
| | | you've ``setup.py develop``-ed Pyramid. |
|---|
| | | - The `tox.ini` uses `nose` and `coverage`. As such `tox` may be used |
|---|
| | | to run groups of tests or only a specific version of Python. For example, the |
|---|
| | | following command will run tests on Python 3.7 only without coverage: |
|---|
| | | |
|---|
| | | - 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:: |
|---|
| | | $ tox -e py37 |
|---|
| | | |
|---|
| | | $ /usr/bin/easy_install tox |
|---|
| | | $ cd ~/hack-on-pyramid/pyramid |
|---|
| | | $ /usr/bin/tox |
|---|
| | | This command will run tests on the latest versions of Python 2 and 3 with |
|---|
| | | coverage totaled for both versions. |
|---|
| | | |
|---|
| | | $ tox -e py2-cover,py3-cover,coverage |
|---|
| | | |
|---|
| | | - To run individual tests (i.e., during development), you can use `nosetests` |
|---|
| | | syntax as follows, where `$VENV` is an environment variable set to the path |
|---|
| | | to your virtual environment: |
|---|
| | | |
|---|
| | | # run a single test |
|---|
| | | $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName.test_mytestname |
|---|
| | | |
|---|
| | | # run all tests in a class |
|---|
| | | $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName |
|---|
| | | |
|---|
| | | Optionally you can install a nose plugin `nose-selecttests` to run specific |
|---|
| | | tests. |
|---|
| | | https://pypi.org/project/nose-selecttests/ |
|---|
| | | For example, use a regular expression with the `-t` parameter to run tests. |
|---|
| | | |
|---|
| | | # run a single test |
|---|
| | | $ $VENV/bin/nosetests -t test_mytestname |
|---|
| | | |
|---|
| | | - The tests can also be run using `pytest`. |
|---|
| | | https://docs.pytest.org/en/latest/ |
|---|
| | | This is intended as a convenience for people who prefer `pytest`. Run the |
|---|
| | | tests like so: |
|---|
| | | |
|---|
| | | $ $VENV/bin/pip install pytest |
|---|
| | | $ $VENV/bin/pytest --strict pyramid/ |
|---|
| | | |
|---|
| | | To run individual tests (i.e., during development), see "pytest usage - |
|---|
| | | Specifying tests / selecting tests": |
|---|
| | | https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests |
|---|
| | | |
|---|
| | | - Functional tests related to the "scaffolds" (starter, zodb, alchemy) which |
|---|
| | | create a virtual environment, install the scaffold package and its |
|---|
| | | dependencies, start a server, and hit a URL on the server, can be run like |
|---|
| | | so: |
|---|
| | | |
|---|
| | | $ tox -e{py27,py34,py35,py36,py37,pypy}-scaffolds |
|---|
| | | |
|---|
| | | |
|---|
| | | 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``. |
|---|
| | | - The codebase *must* have 100% test statement coverage after each commit. You |
|---|
| | | can test coverage via `tox -epy2-cover,py3-cover,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. |
|---|
| | | documentation in this package which references that API or behavior must be |
|---|
| | | changed to reflect the bug fix, ideally in the same commit that fixes the bug |
|---|
| | | or adds the feature. To build and review docs, use the following steps. |
|---|
| | | |
|---|
| | | To build and review docs (where ``$yourvenv`` refers to the virtualenv you're |
|---|
| | | using to develop Pyramid): |
|---|
| | | 1. In the main Pyramid checkout directory, run `tox -e docs`: |
|---|
| | | |
|---|
| | | 1. Run ``$yourvenv/bin/python setup.py dev docs``. This will cause Sphinx |
|---|
| | | and all development requirements to be installed in your virtualenv. |
|---|
| | | $ tox -e 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 |
|---|
| | | ``make clean html SPHINXBUILD=$yourvenv/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 |
|---|
| | | 2. 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`` |
|---|
| | | - Feature additions and bugfixes must be added to the `CHANGES.rst` |
|---|
| | | 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. |
|---|
| | | |
|---|
| | | |
|---|
