Scribd
Upload
42 views

Hacker

The document provides guidelines for contributing to the Pyramid framework, including setting up a development environment, adding features, coding style, running tests, ensuring test coverage, building documentation, and updating the change log. Developers should clone the Pyramid source, install tox, add fully tested and documented features compatible across Python and platform versions, follow code formatting rules, and document all changes.

Uploaded by

Wilton
Copyright
© © All Rights Reserved
Available Formats
Download as TXT, PDF, TXT or read online on Scribd
42 views

Hacker

The document provides guidelines for contributing to the Pyramid framework, including setting up a development environment, adding features, coding style, running tests, ensuring test coverage, building documentation, and updating the change log. Developers should clone the Pyramid source, install tox, add fully tested and documented features compatible across Python and platform versions, follow code formatting rules, and document all changes.

Uploaded by

Wilton
Copyright
© © All Rights Reserved
Available Formats
Download as TXT, PDF, TXT or read online on Scribd
You are on page 1/ 3

Hacking on Pyramid

==================

Here are some guidelines for hacking on Pyramid.

Using a Development 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.

tox docs: https://tox.readthedocs.io/en/latest/


tox on PyPI: https://pypi.org/project/tox/

- 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 .

Alternatively, create a writeable fork on GitHub and clone it.

- Make sure that `tox` is installed, either in your path, or locally. Examples
below assume that `tox` was installed with:

$ pip3 install --user tox


$ export TOX=$(python3 -c 'import site; print(site.USER_BASE + "/bin")')/tox

Feel free to use whatever is your favorite method for installation. One
popular method uses `pipx` (https://github.com/pipxproject/pipx).

Before you file a pull request, we recommend that you run your proposed
change through `tox`. `tox` will fully validate that all tests work, all
supported formats of documentation will build and their doctests pass, and
test coverage is 100%, across all supported versions of Python. `tox` will
only run builds for Python versions that you have installed and made
available to `tox`. Setting up that environment is outside the scope of this
document.

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: 3.7, 3.8, 3.9,
3.10, and 3.11 on both UNIX and Windows.

- The feature must work on the latest version of PyPy3.

- 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).

Coding Style
------------

- Pyramid uses Black (https://pypi.org/project/black/) and isort


(https://pypi.org/project/isort/) for code formatting style.
To run formatters:

$ $TOX -e format

- Pyramid uses flake8 (https://pypi.org/project/flake8/) to enforce PEP8 style


guidelines.
To run flake8, as well as running checks for Black and isort:

$ $TOX -e lint

Black, isort, and flake8 versions are pinned for stability and reproducibility.

Running Tests
-------------

- The `tox.ini` uses `pytest` 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 the same version of Python that `tox` is
installed with:

$ $TOX -e py

To run `tox` for Python 3.10 explicitly, you may use:

$ $TOX -e py310

- To run individual tests (i.e., during development), you can use `pytest`
syntax as follows, where `$VENV` is an environment variable set to the path
to your virtual environment:

# run a single test


$ $TOX -e py --
tests/test_httpexceptions.py::TestHTTPMethodNotAllowed::test_it_with_default_body_t
mpl

# run all tests in a class


$ $TOX -e py -- tests/test_httpexceptions.py::TestHTTPMethodNotAllowed

- For more information on how to use pytest, please refer to the pytest
documentation for selecting tests:
https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests

Test Coverage
-------------

- The codebase *must* have 100% test statement coverage after each commit. You
can test coverage via `tox -e py310`.
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 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.

1. In the main Pyramid checkout directory, run `tox -e docs`:

$ $TOX -e docs

2. Open the `.tox/docs/html/index.html` file to see the resulting HTML


rendering.

Change Log
----------

- 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.

You might also like