commit | author | age
|
93a7a1
|
1 |
.. _wiki_installation: |
SP |
2 |
|
e53e13
|
3 |
============ |
CM |
4 |
Installation |
|
5 |
============ |
|
6 |
|
3e6b60
|
7 |
Before you begin |
c60224
|
8 |
---------------- |
e53e13
|
9 |
|
3e6b60
|
10 |
This tutorial assumes that you have already followed the steps in |
f573cd
|
11 |
:ref:`installing_chapter`, except **do not create a virtual environment or |
SP |
12 |
install Pyramid**. Thereby you will satisfy the following requirements. |
e53e13
|
13 |
|
c60224
|
14 |
* A Python interpreter is installed on your operating system. |
d67566
|
15 |
* You've satisfied the :ref:`requirements-for-installing-packages`. |
c60224
|
16 |
|
e53e13
|
17 |
|
beb4f1
|
18 |
Install cookiecutter |
SP |
19 |
-------------------- |
|
20 |
We will use a :term:`cookiecutter` to create a Python package project from a Python package project template. See `Cookiecutter Installation <https://cookiecutter.readthedocs.io/en/latest/installation.html>`_ for instructions. |
e53e13
|
21 |
|
beb4f1
|
22 |
|
SP |
23 |
Generate a Pyramid project from a cookiecutter |
|
24 |
---------------------------------------------- |
|
25 |
|
|
26 |
We will create a Pyramid project in your home directory for UNIX or at the root for Windows. It is assumed you know the path to where you installed ``cookiecutter``. Issue the following commands and override the defaults in the prompts as follows. |
e53e13
|
27 |
|
3e6b60
|
28 |
On UNIX |
SP |
29 |
^^^^^^^ |
e53e13
|
30 |
|
c60224
|
31 |
.. code-block:: bash |
e53e13
|
32 |
|
beb4f1
|
33 |
$ cd ~ |
1aa283
|
34 |
$ cookiecutter gh:Pylons/pyramid-cookiecutter-zodb --checkout 1.9-branch |
e53e13
|
35 |
|
3e6b60
|
36 |
On Windows |
SP |
37 |
^^^^^^^^^^ |
|
38 |
|
a651b3
|
39 |
.. code-block:: doscon |
3e6b60
|
40 |
|
beb4f1
|
41 |
c:\> cd \ |
1aa283
|
42 |
c:\> cookiecutter gh:Pylons/pyramid-cookiecutter-zodb --checkout 1.9-branch |
beb4f1
|
43 |
|
SP |
44 |
On all operating systems |
|
45 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
|
46 |
If prompted for the first item, accept the default ``yes`` by hitting return. |
|
47 |
|
2cd381
|
48 |
.. code-block:: text |
c60224
|
49 |
|
2cd381
|
50 |
You've cloned ~/.cookiecutters/pyramid-cookiecutter-zodb before. |
SP |
51 |
Is it okay to delete and re-clone it? [yes]: yes |
|
52 |
project_name [Pyramid Scaffold]: myproj |
6ff6fa
|
53 |
repo_name [myproj]: tutorial |
3e6b60
|
54 |
|
beb4f1
|
55 |
Change directory into your newly created project |
SP |
56 |
------------------------------------------------ |
|
57 |
|
|
58 |
On UNIX |
|
59 |
^^^^^^^ |
|
60 |
|
|
61 |
.. code-block:: bash |
|
62 |
|
|
63 |
$ cd tutorial |
|
64 |
|
|
65 |
On Windows |
|
66 |
^^^^^^^^^^ |
|
67 |
|
|
68 |
.. code-block:: doscon |
|
69 |
|
|
70 |
c:\> cd tutorial |
|
71 |
|
|
72 |
|
|
73 |
Set and use a ``VENV`` environment variable |
3e6b60
|
74 |
------------------------------------------- |
SP |
75 |
|
beb4f1
|
76 |
We will set the ``VENV`` environment variable to the absolute path of the virtual environment, and use it going forward. |
3e6b60
|
77 |
|
SP |
78 |
On UNIX |
|
79 |
^^^^^^^ |
|
80 |
|
c60224
|
81 |
.. code-block:: bash |
3e6b60
|
82 |
|
beb4f1
|
83 |
$ export VENV=~/tutorial |
3e6b60
|
84 |
|
SP |
85 |
On Windows |
|
86 |
^^^^^^^^^^ |
|
87 |
|
a651b3
|
88 |
.. code-block:: doscon |
3e6b60
|
89 |
|
640ba7
|
90 |
c:\tutorial> set VENV=c:\tutorial |
3e6b60
|
91 |
|
beb4f1
|
92 |
|
SP |
93 |
Create a virtual environment |
|
94 |
---------------------------- |
|
95 |
|
|
96 |
On UNIX |
|
97 |
^^^^^^^ |
|
98 |
|
|
99 |
.. code-block:: bash |
|
100 |
|
|
101 |
$ python3 -m venv $VENV |
|
102 |
|
|
103 |
On Windows |
|
104 |
^^^^^^^^^^ |
|
105 |
|
7ed8e2
|
106 |
Each version of Python uses different paths, so you might need to adjust the path to the command for your Python version. Recent versions of the Python 3 installer for Windows now install a Python launcher. |
3e6b60
|
107 |
|
SP |
108 |
Python 2.7: |
|
109 |
|
a651b3
|
110 |
.. code-block:: doscon |
3e6b60
|
111 |
|
640ba7
|
112 |
c:\tutorial> c:\Python27\Scripts\virtualenv %VENV% |
3e6b60
|
113 |
|
c8a5e0
|
114 |
Python 3.6: |
3e6b60
|
115 |
|
a651b3
|
116 |
.. code-block:: doscon |
3e6b60
|
117 |
|
7ed8e2
|
118 |
c:\tutorial> python -m venv %VENV% |
3e6b60
|
119 |
|
c60224
|
120 |
|
beb4f1
|
121 |
Upgrade packaging tools in the virtual environment |
SP |
122 |
-------------------------------------------------- |
3e6b60
|
123 |
|
SP |
124 |
On UNIX |
|
125 |
^^^^^^^ |
|
126 |
|
c60224
|
127 |
.. code-block:: bash |
3e6b60
|
128 |
|
da6244
|
129 |
$ $VENV/bin/pip install --upgrade pip setuptools |
3e6b60
|
130 |
|
SP |
131 |
On Windows |
|
132 |
^^^^^^^^^^ |
|
133 |
|
a651b3
|
134 |
.. code-block:: doscon |
3e6b60
|
135 |
|
640ba7
|
136 |
c:\tutorial> %VENV%\Scripts\pip install --upgrade pip setuptools |
c60224
|
137 |
|
4466bb
|
138 |
|
3e6b60
|
139 |
.. _installing_project_in_dev_mode_zodb: |
e53e13
|
140 |
|
3e6b60
|
141 |
Installing the project in development mode |
c60224
|
142 |
------------------------------------------ |
e53e13
|
143 |
|
beb4f1
|
144 |
In order to do development on the project easily, you must "register" the project as a development egg in your workspace. We will install testing requirements at the same time. We do so with the following command. |
e53e13
|
145 |
|
3e6b60
|
146 |
On UNIX |
c60224
|
147 |
^^^^^^^ |
e53e13
|
148 |
|
c60224
|
149 |
.. code-block:: bash |
e53e13
|
150 |
|
beb4f1
|
151 |
$ $VENV/bin/pip install -e ".[testing]" |
e53e13
|
152 |
|
3e6b60
|
153 |
On Windows |
c60224
|
154 |
^^^^^^^^^^ |
e53e13
|
155 |
|
a651b3
|
156 |
.. code-block:: doscon |
e53e13
|
157 |
|
640ba7
|
158 |
c:\tutorial> %VENV%\Scripts\pip install -e ".[testing]" |
3e6b60
|
159 |
|
beb4f1
|
160 |
On all operating systems |
SP |
161 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
|
162 |
|
|
163 |
The console will show ``pip`` checking for packages and installing missing packages. Success executing this command will show a line like the following: |
3e6b60
|
164 |
|
c60224
|
165 |
.. code-block:: bash |
SP |
166 |
|
beb4f1
|
167 |
Successfully installed BTrees-4.3.1 Chameleon-3.0 Mako-1.0.6 \ |
SP |
168 |
MarkupSafe-0.23 PasteDeploy-1.5.2 Pygments-2.1.3 WebOb-1.6.3 \ |
|
169 |
WebTest-2.0.23 ZConfig-3.1.0 ZEO-5.0.4 ZODB-5.1.1 ZODB3-3.11.0 \ |
|
170 |
beautifulsoup4-4.5.1 coverage-4.2 mock-2.0.0 pbr-1.10.0 persistent-4.2.2 \ |
|
171 |
py-1.4.31 pyramid-1.7.3 pyramid-chameleon-0.3 pyramid-debugtoolbar-3.0.5 \ |
2d5234
|
172 |
pyramid-mako-1.0.2 pyramid-tm-1.1.1 pyramid-zodbconn-0.7 pytest-3.0.5 \ |
SP |
173 |
pytest-cov-2.4.0 repoze.lru-0.6 six-1.10.0 transaction-2.0.3 \ |
|
174 |
translationstring-1.3 tutorial venusian-1.0 waitress-1.0.1 \ |
|
175 |
zc.lockfile-1.2.1 zdaemon-4.2.0 zodbpickle-0.6.0 zodburi-2.0 \ |
|
176 |
zope.deprecation-4.2.0 zope.interface-4.3.3 |
c60224
|
177 |
|
beb4f1
|
178 |
Testing requirements are defined in our project's ``setup.py`` file, in the ``tests_require`` and ``extras_require`` stanzas. |
c60224
|
179 |
|
SP |
180 |
.. literalinclude:: src/installation/setup.py |
beb4f1
|
181 |
:language: python |
SP |
182 |
:lineno-match: |
909ae0
|
183 |
:lines: 24-28 |
c60224
|
184 |
|
SP |
185 |
.. literalinclude:: src/installation/setup.py |
beb4f1
|
186 |
:language: python |
SP |
187 |
:lineno-match: |
909ae0
|
188 |
:lines: 48-50 |
c60224
|
189 |
|
e53e13
|
190 |
|
CM |
191 |
.. _running_tests: |
|
192 |
|
3e6b60
|
193 |
Run the tests |
c60224
|
194 |
------------- |
e53e13
|
195 |
|
c60224
|
196 |
After you've installed the project in development mode as well as the testing |
9591e9
|
197 |
requirements, you may run the tests for the project. The following commands |
SP |
198 |
provide options to py.test that specify the module for which its tests shall be |
|
199 |
run, and to run py.test in quiet mode. |
e53e13
|
200 |
|
3e6b60
|
201 |
On UNIX |
c60224
|
202 |
^^^^^^^ |
e53e13
|
203 |
|
c60224
|
204 |
.. code-block:: bash |
e53e13
|
205 |
|
779b31
|
206 |
$ $VENV/bin/py.test -q |
e53e13
|
207 |
|
3e6b60
|
208 |
On Windows |
c60224
|
209 |
^^^^^^^^^^ |
e53e13
|
210 |
|
a651b3
|
211 |
.. code-block:: doscon |
e53e13
|
212 |
|
640ba7
|
213 |
c:\tutorial> %VENV%\Scripts\py.test -q |
e53e13
|
214 |
|
c60224
|
215 |
For a successful test run, you should see output that ends like this: |
3e6b60
|
216 |
|
c60224
|
217 |
.. code-block:: bash |
SP |
218 |
|
|
219 |
. |
|
220 |
1 passed in 0.24 seconds |
|
221 |
|
3e6b60
|
222 |
|
SP |
223 |
Expose test coverage information |
c60224
|
224 |
-------------------------------- |
e53e13
|
225 |
|
c60224
|
226 |
You can run the ``py.test`` command to see test coverage information. This |
SP |
227 |
runs the tests in the same way that ``py.test`` does, but provides additional |
beb4f1
|
228 |
:term:`coverage` information, exposing which lines of your project are covered by the |
e53e13
|
229 |
tests. |
CM |
230 |
|
d67566
|
231 |
We've already installed the ``pytest-cov`` package into our virtual |
SP |
232 |
environment, so we can run the tests with coverage. |
c60224
|
233 |
|
3e6b60
|
234 |
On UNIX |
c60224
|
235 |
^^^^^^^ |
e53e13
|
236 |
|
c60224
|
237 |
.. code-block:: bash |
e53e13
|
238 |
|
779b31
|
239 |
$ $VENV/bin/py.test --cov --cov-report=term-missing |
e53e13
|
240 |
|
3e6b60
|
241 |
On Windows |
c60224
|
242 |
^^^^^^^^^^ |
e53e13
|
243 |
|
a651b3
|
244 |
.. code-block:: doscon |
e53e13
|
245 |
|
7ed8e2
|
246 |
c:\tutorial> %VENV%\Scripts\py.test --cov --cov-report=term-missing |
e53e13
|
247 |
|
c60224
|
248 |
If successful, you will see output something like this: |
3e6b60
|
249 |
|
c60224
|
250 |
.. code-block:: bash |
3e6b60
|
251 |
|
beb4f1
|
252 |
======================== test session starts ======================== |
SP |
253 |
platform Python 3.6.0, pytest-3.0.5, py-1.4.31, pluggy-0.4.0 |
|
254 |
rootdir: /Users/stevepiercy/tutorial, inifile: |
|
255 |
plugins: cov-2.4.0 |
|
256 |
collected 1 items |
3e6b60
|
257 |
|
d5662c
|
258 |
tutorial/tests.py . |
SP |
259 |
------------------ coverage: platform Python 3.6.0 ------------------ |
|
260 |
Name Stmts Miss Cover Missing |
|
261 |
------------------------------------------------------- |
|
262 |
tutorial/__init__.py 14 9 36% 7-8, 14-20 |
|
263 |
tutorial/models.py 10 6 40% 9-14 |
|
264 |
tutorial/views.py 4 0 100% |
|
265 |
------------------------------------------------------- |
|
266 |
TOTAL 28 15 46% |
c60224
|
267 |
|
d5662c
|
268 |
===================== 1 passed in 0.31 seconds ====================== |
c60224
|
269 |
|
SP |
270 |
Our package doesn't quite have 100% test coverage. |
|
271 |
|
e53e13
|
272 |
|
beb4f1
|
273 |
.. _test_and_coverage_cookiecutter_defaults_zodb: |
779b31
|
274 |
|
beb4f1
|
275 |
Test and coverage cookiecutter defaults |
SP |
276 |
--------------------------------------- |
779b31
|
277 |
|
beb4f1
|
278 |
Cookiecutters include configuration defaults for ``py.test`` and test coverage. |
779b31
|
279 |
These configuration files are ``pytest.ini`` and ``.coveragerc``, located at |
SP |
280 |
the root of your package. Without these defaults, we would need to specify the |
|
281 |
path to the module on which we want to run tests and coverage. |
|
282 |
|
|
283 |
On UNIX |
|
284 |
^^^^^^^ |
|
285 |
|
|
286 |
.. code-block:: bash |
|
287 |
|
|
288 |
$ $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q |
|
289 |
|
|
290 |
On Windows |
|
291 |
^^^^^^^^^^ |
|
292 |
|
|
293 |
.. code-block:: doscon |
|
294 |
|
640ba7
|
295 |
c:\tutorial> %VENV%\Scripts\py.test --cov=tutorial tutorial\tests.py -q |
779b31
|
296 |
|
SP |
297 |
py.test follows :ref:`conventions for Python test discovery |
beb4f1
|
298 |
<pytest:test discovery>`, and the configuration defaults from the cookiecutter |
779b31
|
299 |
tell ``py.test`` where to find the module on which we want to run tests and |
SP |
300 |
coverage. |
|
301 |
|
|
302 |
.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke |
|
303 |
``py.test -h`` to see its full set of options. |
|
304 |
|
|
305 |
|
218ad4
|
306 |
.. _wiki-start-the-application: |
PP |
307 |
|
3e6b60
|
308 |
Start the application |
c60224
|
309 |
--------------------- |
f84651
|
310 |
|
1644ef
|
311 |
Start the application. See :ref:`what_is_this_pserve_thing` for more |
MM |
312 |
information on ``pserve``. |
f84651
|
313 |
|
3e6b60
|
314 |
On UNIX |
c60224
|
315 |
^^^^^^^ |
f84651
|
316 |
|
c60224
|
317 |
.. code-block:: bash |
f84651
|
318 |
|
3e6b60
|
319 |
$ $VENV/bin/pserve development.ini --reload |
f84651
|
320 |
|
3e6b60
|
321 |
On Windows |
c60224
|
322 |
^^^^^^^^^^ |
f84651
|
323 |
|
a651b3
|
324 |
.. code-block:: doscon |
f84651
|
325 |
|
640ba7
|
326 |
c:\tutorial> %VENV%\Scripts\pserve development.ini --reload |
f84651
|
327 |
|
e909e6
|
328 |
.. note:: |
K |
329 |
|
|
330 |
Your OS firewall, if any, may pop up a dialog asking for authorization |
|
331 |
to allow python to accept incoming network connections. |
|
332 |
|
edc20e
|
333 |
If successful, you will see something like this on your console: |
SP |
334 |
|
|
335 |
.. code-block:: text |
3e6b60
|
336 |
|
beb4f1
|
337 |
Starting subprocess with file monitor |
SP |
338 |
Starting server in PID 44078. |
|
339 |
Serving on http://localhost:6543 |
|
340 |
Serving on http://localhost:6543 |
3e6b60
|
341 |
|
SP |
342 |
This means the server is ready to accept requests. |
|
343 |
|
e53e13
|
344 |
|
c60224
|
345 |
Visit the application in a browser |
SP |
346 |
---------------------------------- |
|
347 |
|
|
348 |
In a browser, visit http://localhost:6543/. You will see the generated |
|
349 |
application's default page. |
2c9f3c
|
350 |
|
CM |
351 |
One thing you'll notice is the "debug toolbar" icon on right hand side of the |
|
352 |
page. You can read more about the purpose of the icon at |
|
353 |
:ref:`debug_toolbar`. It allows you to get information about your |
|
354 |
application while you develop. |
e53e13
|
355 |
|
c60224
|
356 |
|
beb4f1
|
357 |
Decisions the ``zodb`` cookiecutter has made for you |
SP |
358 |
---------------------------------------------------- |
e53e13
|
359 |
|
beb4f1
|
360 |
Creating a project using the ``zodb`` cookiecutter makes the following |
b3b713
|
361 |
assumptions: |
CM |
362 |
|
beb4f1
|
363 |
- You are willing to use :term:`ZODB` for persistent storage. |
b3b713
|
364 |
|
c60224
|
365 |
- You are willing to use :term:`traversal` to map URLs to code. |
b3b713
|
366 |
|
9591e9
|
367 |
- You want to use pyramid_zodbconn_, pyramid_tm_, and the transaction_ packages |
SP |
368 |
to manage connections and transactions with :term:`ZODB`. |
|
369 |
|
|
370 |
- You want to use pyramid_chameleon_ to render your templates. Different |
|
371 |
templating engines can be used, but we had to choose one to make this |
|
372 |
tutorial. See :ref:`available_template_system_bindings` for some options. |
|
373 |
|
b3b713
|
374 |
.. note:: |
CM |
375 |
|
9591e9
|
376 |
:app:`Pyramid` supports any persistent storage mechanism (e.g., an SQL |
SP |
377 |
database or filesystem files). It also supports an additional mechanism to |
|
378 |
map URLs to code (:term:`URL dispatch`). However, for the purposes of this |
|
379 |
tutorial, we'll only be using :term:`traversal` and :term:`ZODB`. |
|
380 |
|
|
381 |
.. _pyramid_chameleon: |
19d341
|
382 |
https://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/ |
9591e9
|
383 |
|
SP |
384 |
.. _pyramid_tm: |
19d341
|
385 |
https://docs.pylonsproject.org/projects/pyramid-tm/en/latest/ |
9591e9
|
386 |
|
SP |
387 |
.. _pyramid_zodbconn: |
19d341
|
388 |
https://docs.pylonsproject.org/projects/pyramid-zodbconn/en/latest/ |
9591e9
|
389 |
|
SP |
390 |
.. _transaction: |
7b1612
|
391 |
https://zodb.readthedocs.io/en/latest/transactions.html |