| | |
| | | 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, you can use it to set up a working development environment. |
| | | 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. |
| | | |
| | | tox docs: http://tox.readthedocs.org/en/latest/ |
| | | tox docs: https://tox.readthedocs.io/en/latest/ |
| | | tox on PyPI: https://pypi.org/project/tox/ |
| | | |
| | | Each installation method is described below. |
| | | |
| | | |
| | | By Hand |
| | | +++++++ |
| | | |
| | | - While logged into your GitHub account, navigate to the Pyramid repo on |
| | | GitHub. |
| | | |
| | | https://github.com/Pylons/pyramid |
| | | |
| | | - Fork and clone the Pyramid repository to your GitHub account by clicking |
| | | the "Fork" button. |
| | | |
| | | - Clone your fork of Pyramid from your GitHub account to your local computer, |
| | | substituting your account username and specifying the destination as |
| | | "hack-on-pyramid". |
| | | |
| | | $ cd ~ |
| | | $ git clone git@github.com:USERNAME/pyramid.git hack-on-pyramid |
| | | $ cd hack-on-pyramid |
| | | # Configure remotes such that you can pull changes from the Pyramid |
| | | # repository into your local repository. |
| | | $ git remote add upstream https://github.com/Pylons/pyramid.git |
| | | # fetch and merge changes from upstream into master |
| | | $ git fetch upstream |
| | | $ git merge upstream/master |
| | | |
| | | Now your local repo is set up such that you will push changes to your GitHub |
| | | repo, from which you can submit a pull request. |
| | | |
| | | - Create a virtual environment in which to install Pyramid: |
| | | |
| | | $ cd ~/hack-on-pyramid |
| | | $ python3 -m venv env |
| | | |
| | | 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 Pyramid from the checkout into the virtual environment, where the |
| | | current working directory is the `pyramid` checkout directory. We will |
| | | install Pyramid in editable (development) mode as well as its testing |
| | | requirements. |
| | | |
| | | $ cd ~/hack-on-pyramid |
| | | $ $VENV/bin/pip install -e ".[testing,docs]" |
| | | |
| | | - Optionally create a new Pyramid project using `pcreate`: |
| | | |
| | | $ cd $VENV |
| | | $ bin/pcreate -s starter starter |
| | | |
| | | - ...and install the new project into the virtual environment: |
| | | |
| | | $ cd $VENV/starter |
| | | $ $VENV/bin/pip install -e . |
| | | |
| | | |
| | | 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: |
| | | |
| | |
| | | $ git clone git://github.com/Pylons/pyramid.git . |
| | | |
| | | Alternatively, create a writeable fork on GitHub and clone it. |
| | | |
| | | Since Pyramid is a framework and not an application, it can be convenient to |
| | | work against a sample application, preferably in its own virtual environment. A |
| | | quick way to achieve this is to use `tox` with a custom configuration file |
| | | that is part of the checkout: |
| | | |
| | | $ tox -c hacking-tox.ini |
| | | |
| | | This will create a python-2.7 based virtual environment named `env27` |
| | | (Pyramid's `.gitconfig` ignores all top-level folders that start with `env` |
| | | specifically in our use case), and inside that a simple pyramid application |
| | | named `hacking` that you can then fire up like so: |
| | | |
| | | $ cd env27/hacking |
| | | $ ../bin/pip install -e ".[testing,docs]" |
| | | $ ../bin/pserve development.ini |
| | | |
| | | |
| | | Adding Features |
| | |
| | | Coding Style |
| | | ------------ |
| | | |
| | | - PEP8 compliance. Whitespace rules are relaxed: not necessary to put two |
| | | newlines between classes. But 79-column lines, in particular, are mandatory. |
| | | See https://pylonsproject.org/community-coding-style-standards.html for more |
| | | information. |
| | | - 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. See https://github.com/Pylons/pyramid/issues/788 for more. |
| | | $ tox -e black |
| | | |
| | | |
| | | Running Tests |
| | | ------------- |
| | | |
| | | - To run all tests for Pyramid on a single Python version from your development |
| | | virtual environment (See *Using a Development Checkout* above), run |
| | | `nosetests`: |
| | | - 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: |
| | | |
| | | $ $VENV/bin/nosetests |
| | | $ tox -e py37 |
| | | |
| | | 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: |
| | | 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` |
| | | ( https://pypi.org/project/nose-selecttests/ ), and use a regular |
| | | expression with the `-t` parameter to run tests. |
| | | 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 `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 2.7 only without coverage: |
| | | |
| | | $ tox -e py27 |
| | | |
| | | 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 the full set of Pyramid tests on all platforms, install `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 virtual environment |
| | | for each version/platform combination. For example: |
| | | |
| | | $ sudo /usr/bin/pip 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 to or fond of |
| | | `pytest`. Run the tests like so: |
| | | - 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/py.test --strict pyramid/ |
| | | $ $VENV/bin/pytest --strict pyramid/ |
| | | |
| | | To run individual tests (i.e., during development), see "py.test usage - |
| | | To run individual tests (i.e., during development), see "pytest usage - |
| | | Specifying tests / selecting tests": |
| | | http://pytest.org/latest/usage.html#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: |
| | | |
| | | $ ./scaffoldtests.sh |
| | | |
| | | Alternatively: |
| | | |
| | | $ tox -e{py27,py34,py35,pyt36,py37,pypy}-scaffolds |
| | | $ 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 `./coverage.sh` (which itself just executes `tox |
| | | -epy2-cover,py3-cover,coverage`). |
| | | can test coverage via `tox -epy2-cover,py3-cover,coverage`. |
| | | |
| | | |
| | | Documentation Coverage and Building HTML Documentation |
| | |
| | | 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. |
| | | |
| | | 1. In the main Pyramid checkout directory, run `./builddocs.sh` (which just |
| | | turns around and runs `tox -e docs`): |
| | | 1. In the main Pyramid checkout directory, run `tox -e docs`: |
| | | |
| | | $ ./builddocs.sh |
| | | $ tox -e docs |
| | | |
| | | 2. Open the `docs/_build/html/index.html` file to see the resulting HTML |
| | | rendering. |