commit | author | age
|
49f5c4
|
1 |
Hacking on Pyramid |
CM |
2 |
================== |
|
3 |
|
93b6cd
|
4 |
Here are some guidelines for hacking on Pyramid. |
49f5c4
|
5 |
|
84b496
|
6 |
|
051e27
|
7 |
Using a Development Checkout |
CM |
8 |
---------------------------- |
|
9 |
|
8cc783
|
10 |
You will have to create a development environment to hack on Pyramid, using a |
SP |
11 |
Pyramid checkout. We use `tox` to run tests, run test coverage, and build |
|
12 |
documentation. |
081699
|
13 |
|
8cc783
|
14 |
tox docs: https://tox.readthedocs.io/en/latest/ |
081699
|
15 |
tox on PyPI: https://pypi.org/project/tox/ |
051e27
|
16 |
|
081699
|
17 |
- Create a new directory somewhere and `cd` to it: |
051e27
|
18 |
|
84b496
|
19 |
$ mkdir ~/hack-on-pyramid |
SP |
20 |
$ cd ~/hack-on-pyramid |
051e27
|
21 |
|
93b6cd
|
22 |
- Check out a read-only copy of the Pyramid source: |
051e27
|
23 |
|
84b496
|
24 |
$ git clone git://github.com/Pylons/pyramid.git . |
051e27
|
25 |
|
e39cc8
|
26 |
Alternatively, create a writeable fork on GitHub and clone it. |
84b496
|
27 |
|
051e27
|
28 |
|
49f5c4
|
29 |
Adding Features |
CM |
30 |
--------------- |
|
31 |
|
|
32 |
In order to add a feature to Pyramid: |
4f25f4
|
33 |
|
84b496
|
34 |
- The feature must be documented in both the API and narrative documentation |
081699
|
35 |
(in `docs/`). |
4f25f4
|
36 |
|
c8a5e0
|
37 |
- The feature must work fully on the following CPython versions: 2.7, 3.4, 3.5, |
482075
|
38 |
3.6, and 3.7 on both UNIX and Windows. |
a3ff61
|
39 |
|
a5c810
|
40 |
- The feature must work on the latest version of PyPy. |
4f25f4
|
41 |
|
84b496
|
42 |
- The feature must not depend on any particular persistence layer (filesystem, |
SP |
43 |
SQL, etc). |
4f25f4
|
44 |
|
84b496
|
45 |
- The feature must not add unnecessary dependencies (where "unnecessary" is of |
SP |
46 |
course subjective, but new dependencies should be discussed). |
4f25f4
|
47 |
|
84b496
|
48 |
The above requirements are relaxed for scaffolding dependencies. If a scaffold |
SP |
49 |
has an install-time dependency on something that doesn't work on a particular |
|
50 |
platform, that caveat should be spelled out clearly in *its* documentation |
081699
|
51 |
(within its `docs/` directory). |
4f25f4
|
52 |
|
49f5c4
|
53 |
|
CM |
54 |
Coding Style |
|
55 |
------------ |
|
56 |
|
8cc783
|
57 |
- Pyramid uses Black for code formatting style. |
SP |
58 |
https://pypi.org/project/black/ |
|
59 |
To run Black: |
49f5c4
|
60 |
|
8cc783
|
61 |
$ tox -e black |
cdcea9
|
62 |
|
84b496
|
63 |
|
a3ff61
|
64 |
Running Tests |
8edd76
|
65 |
------------- |
a3ff61
|
66 |
|
8cc783
|
67 |
- The `tox.ini` uses `nose` and `coverage`. As such `tox` may be used |
SP |
68 |
to run groups of tests or only a specific version of Python. For example, the |
|
69 |
following command will run tests on Python 3.7 only without coverage: |
50f23d
|
70 |
|
8cc783
|
71 |
$ tox -e py37 |
SP |
72 |
|
|
73 |
This command will run tests on the latest versions of Python 2 and 3 with |
|
74 |
coverage totaled for both versions. |
|
75 |
|
|
76 |
$ tox -e py2-cover,py3-cover,coverage |
84b496
|
77 |
|
081699
|
78 |
- To run individual tests (i.e., during development), you can use `nosetests` |
8cc783
|
79 |
syntax as follows, where `$VENV` is an environment variable set to the path |
SP |
80 |
to your virtual environment: |
8edd76
|
81 |
|
SP |
82 |
# run a single test |
|
83 |
$ $VENV/bin/nosetests pyramid.tests.test_module:ClassName.test_mytestname |
|
84 |
|
|
85 |
# run all tests in a class |
|
86 |
$ $VENV/bin/nosetests pyramid.tests.test_module:ClassName |
|
87 |
|
8cc783
|
88 |
Optionally you can install a nose plugin `nose-selecttests` to run specific |
SP |
89 |
tests. |
|
90 |
https://pypi.org/project/nose-selecttests/ |
|
91 |
For example, use a regular expression with the `-t` parameter to run tests. |
8edd76
|
92 |
|
SP |
93 |
# run a single test |
|
94 |
$ $VENV/bin/nosetests -t test_mytestname |
a3ff61
|
95 |
|
8cc783
|
96 |
- The tests can also be run using `pytest`. |
SP |
97 |
https://docs.pytest.org/en/latest/ |
|
98 |
This is intended as a convenience for people who prefer `pytest`. Run the |
|
99 |
tests like so: |
7a2df2
|
100 |
|
84b496
|
101 |
$ $VENV/bin/pip install pytest |
8fcf0f
|
102 |
$ $VENV/bin/pytest --strict pyramid/ |
84b496
|
103 |
|
8fcf0f
|
104 |
To run individual tests (i.e., during development), see "pytest usage - |
84b496
|
105 |
Specifying tests / selecting tests": |
8cc783
|
106 |
https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests |
7a2df2
|
107 |
|
109b2a
|
108 |
- Functional tests related to the "scaffolds" (starter, zodb, alchemy) which |
84b496
|
109 |
create a virtual environment, install the scaffold package and its |
SP |
110 |
dependencies, start a server, and hit a URL on the server, can be run like |
|
111 |
so: |
109b2a
|
112 |
|
eadaee
|
113 |
$ tox -e{py27,py34,py35,py36,py37,pypy}-scaffolds |
84b496
|
114 |
|
109b2a
|
115 |
|
49f5c4
|
116 |
Test Coverage |
CM |
117 |
------------- |
|
118 |
|
aa1c9b
|
119 |
- The codebase *must* have 100% test statement coverage after each commit. You |
eadaee
|
120 |
can test coverage via `tox -epy2-cover,py3-cover,coverage`. |
84b496
|
121 |
|
49f5c4
|
122 |
|
c7fcdf
|
123 |
Documentation Coverage and Building HTML Documentation |
CM |
124 |
------------------------------------------------------ |
49f5c4
|
125 |
|
c7fcdf
|
126 |
If you fix a bug, and the bug requires an API or behavior modification, all |
93b6cd
|
127 |
documentation in this package which references that API or behavior must be |
SP |
128 |
changed to reflect the bug fix, ideally in the same commit that fixes the bug |
aa1c9b
|
129 |
or adds the feature. To build and review docs, use the following steps. |
49f5c4
|
130 |
|
eadaee
|
131 |
1. In the main Pyramid checkout directory, run `tox -e docs`: |
995155
|
132 |
|
eadaee
|
133 |
$ tox -e docs |
995155
|
134 |
|
081699
|
135 |
2. Open the `docs/_build/html/index.html` file to see the resulting HTML |
c7fcdf
|
136 |
rendering. |
84b496
|
137 |
|
319806
|
138 |
|
49f5c4
|
139 |
Change Log |
CM |
140 |
---------- |
|
141 |
|
081699
|
142 |
- Feature additions and bugfixes must be added to the `CHANGES.rst` |
49f5c4
|
143 |
file in the prevailing style. Changelog entries should be long and |
CM |
144 |
descriptive, not cryptic. Other developers should be able to know |
|
145 |
what your changelog entry means. |