view | history | commit | commitdiff
Steve Piercy
2016-11-29 968bebc0d1cbb6d85eb446b41c0f4560383c3022
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
3e6b60 18 Create directory to contain the project
SP 19 ---------------------------------------
e53e13 20
3e6b60 21 We need a workspace for our project files.
e53e13 22
3e6b60 23 On UNIX
SP 24 ^^^^^^^
e53e13 25
c60224 26 .. code-block:: bash
e53e13 27
3e6b60 28     $ mkdir ~/pyramidtut
e53e13 29
3e6b60 30 On Windows
SP 31 ^^^^^^^^^^
32
a651b3 33 .. code-block:: doscon
3e6b60 34
SP 35    c:\> mkdir pyramidtut
c60224 36
3e6b60 37
SP 38 Create and use a virtual Python environment
39 -------------------------------------------
40
d67566 41 Next let's create a virtual environment workspace for our project.  We will use
SP 42 the ``VENV`` environment variable instead of the absolute path of the virtual
c60224 43 environment.
3e6b60 44
SP 45 On UNIX
46 ^^^^^^^
47
c60224 48 .. code-block:: bash
3e6b60 49
SP 50    $ export VENV=~/pyramidtut
d67566 51    $ python3 -m venv $VENV
3e6b60 52
SP 53 On Windows
54 ^^^^^^^^^^
55
a651b3 56 .. code-block:: doscon
3e6b60 57
SP 58    c:\> set VENV=c:\pyramidtut
59
c60224 60 Each version of Python uses different paths, so you will need to adjust the
3e6b60 61 path to the command for your Python version.
SP 62
63 Python 2.7:
64
a651b3 65 .. code-block:: doscon
3e6b60 66
SP 67    c:\> c:\Python27\Scripts\virtualenv %VENV%
68
c8a5e0 69 Python 3.6:
3e6b60 70
a651b3 71 .. code-block:: doscon
3e6b60 72
d67566 73    c:\> c:\Python35\Scripts\python -m venv %VENV%
3e6b60 74
c60224 75
da6244 76 Upgrade ``pip`` and ``setuptools`` in the virtual environment
SP 77 -------------------------------------------------------------
3e6b60 78
SP 79 On UNIX
80 ^^^^^^^
81
c60224 82 .. code-block:: bash
3e6b60 83
da6244 84     $ $VENV/bin/pip install --upgrade pip setuptools
3e6b60 85
SP 86 On Windows
87 ^^^^^^^^^^
88
a651b3 89 .. code-block:: doscon
3e6b60 90
da6244 91    c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
3e6b60 92
c60224 93
SP 94 Install Pyramid into the virtual Python environment
3e6b60 95 ---------------------------------------------------
SP 96
97 On UNIX
98 ^^^^^^^
99
ac4d2c 100 .. parsed-literal::
c60224 101
ac4d2c 102    $ $VENV/bin/pip install "pyramid==\ |release|\ "
c60224 103
SP 104 On Windows
105 ^^^^^^^^^^
106
ac4d2c 107 .. parsed-literal::
c60224 108
ac4d2c 109    c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
SP 110
c60224 111
SP 112 Change directory to your virtual Python environment
113 ---------------------------------------------------
114
115 Change directory to the ``pyramidtut`` directory, which is both your workspace
116 and your virtual environment.
117
118 On UNIX
119 ^^^^^^^
120
121 .. code-block:: bash
3e6b60 122
SP 123    $ cd pyramidtut
124
125 On Windows
126 ^^^^^^^^^^
127
a651b3 128 .. code-block:: doscon
3e6b60 129
SP 130    c:\> cd pyramidtut
131
9591e9 132
3e6b60 133 .. _making_a_project:
SP 134
135 Making a project
c60224 136 ----------------
3e6b60 137
SP 138 Your next step is to create a project.  For this tutorial, we will use
139 the :term:`scaffold` named ``zodb``, which generates an application
140 that uses :term:`ZODB` and :term:`traversal`.
141
c60224 142 :app:`Pyramid` supplies a variety of scaffolds to generate sample projects. We
SP 143 will use ``pcreate``, a script that comes with Pyramid, to create our project
144 using a scaffold.
3e6b60 145
c60224 146 By passing ``zodb`` into the ``pcreate`` command, the script creates the files
SP 147 needed to use ZODB. By passing in our application name ``tutorial``, the script
148 inserts that application name into all the required files.
3e6b60 149
SP 150 The below instructions assume your current working directory is "pyramidtut".
151
152 On UNIX
c60224 153 ^^^^^^^
3e6b60 154
c60224 155 .. code-block:: bash
3e6b60 156
SP 157    $ $VENV/bin/pcreate -s zodb tutorial
158
159 On Windows
c60224 160 ^^^^^^^^^^
e53e13 161
a651b3 162 .. code-block:: doscon
e53e13 163
f73f0e 164    c:\pyramidtut> %VENV%\Scripts\pcreate -s zodb tutorial
e53e13 165
c60224 166 .. note:: If you are using Windows, the ``zodb`` scaffold may not deal
SP 167    gracefully with installation into a location that contains spaces in the
d67566 168    path. If you experience startup problems, try putting both the virtual
SP 169    environment and the project into directories that do not contain spaces in
170    their paths.
c60224 171
4466bb 172
3e6b60 173 .. _installing_project_in_dev_mode_zodb:
e53e13 174
3e6b60 175 Installing the project in development mode
c60224 176 ------------------------------------------
e53e13 177
c60224 178 In order to do development on the project easily, you must "register" the
SP 179 project as a development egg in your workspace using the ``pip install -e .``
180 command. In order to do so, change directory to the ``tutorial`` directory that
181 you created in :ref:`making_a_project`, and run the ``pip install -e .``
d67566 182 command using the virtual environment Python interpreter.
e53e13 183
3e6b60 184 On UNIX
c60224 185 ^^^^^^^
e53e13 186
c60224 187 .. code-block:: bash
e53e13 188
3e6b60 189    $ cd tutorial
c60224 190    $ $VENV/bin/pip install -e .
e53e13 191
3e6b60 192 On Windows
c60224 193 ^^^^^^^^^^
e53e13 194
a651b3 195 .. code-block:: doscon
e53e13 196
3e6b60 197    c:\pyramidtut> cd tutorial
c60224 198    c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e .
3e6b60 199
c60224 200 The console will show ``pip`` checking for packages and installing missing
SP 201 packages. Success executing this command will show a line like the following:
3e6b60 202
c60224 203 .. code-block:: bash
SP 204
205    Successfully installed BTrees-4.2.0 Chameleon-2.24 Mako-1.0.4 \
206    MarkupSafe-0.23 Pygments-2.1.3 ZConfig-3.1.0 ZEO-4.2.0b1 ZODB-4.2.0 \
207    ZODB3-3.11.0 mock-2.0.0 pbr-1.8.1 persistent-4.1.1 pyramid-chameleon-0.3 \
208    pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2 pyramid-tm-0.12.1 \
209    pyramid-zodbconn-0.7 six-1.10.0 transaction-1.4.4 tutorial waitress-0.8.10 \
210    zc.lockfile-1.1.0 zdaemon-4.1.0 zodbpickle-0.6.0 zodburi-2.0
211
212
9591e9 213 .. _install-testing-requirements-zodb:
c60224 214
SP 215 Install testing requirements
216 ----------------------------
217
218 In order to run tests, we need to install the testing requirements. This is
ebbe68 219 done through our project's ``setup.py`` file, in the ``tests_require`` and
db13c8 220 ``extras_require`` stanzas, and by issuing the command below for your
c60224 221 operating system.
SP 222
223 .. literalinclude:: src/installation/setup.py
224    :language: python
225    :linenos:
226    :lineno-start: 22
227    :lines: 22-26
228
229 .. literalinclude:: src/installation/setup.py
230    :language: python
231    :linenos:
232    :lineno-start: 45
233    :lines: 45-47
234
235 On UNIX
236 ^^^^^^^
237
238 .. code-block:: bash
239
240    $ $VENV/bin/pip install -e ".[testing]"
241
242 On Windows
243 ^^^^^^^^^^
244
a651b3 245 .. code-block:: doscon
c60224 246
SP 247    c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e ".[testing]"
248
e53e13 249
CM 250 .. _running_tests:
251
3e6b60 252 Run the tests
c60224 253 -------------
e53e13 254
c60224 255 After you've installed the project in development mode as well as the testing
9591e9 256 requirements, you may run the tests for the project. The following commands
SP 257 provide options to py.test that specify the module for which its tests shall be
258 run, and to run py.test in quiet mode.
e53e13 259
3e6b60 260 On UNIX
c60224 261 ^^^^^^^
e53e13 262
c60224 263 .. code-block:: bash
e53e13 264
779b31 265    $ $VENV/bin/py.test -q
e53e13 266
3e6b60 267 On Windows
c60224 268 ^^^^^^^^^^
e53e13 269
a651b3 270 .. code-block:: doscon
e53e13 271
779b31 272    c:\pyramidtut\tutorial> %VENV%\Scripts\py.test -q
e53e13 273
c60224 274 For a successful test run, you should see output that ends like this:
3e6b60 275
c60224 276 .. code-block:: bash
SP 277
278    .
279    1 passed in 0.24 seconds
280
3e6b60 281
SP 282 Expose test coverage information
c60224 283 --------------------------------
e53e13 284
c60224 285 You can run the ``py.test`` command to see test coverage information. This
SP 286 runs the tests in the same way that ``py.test`` does, but provides additional
287 "coverage" information, exposing which lines of your project are covered by the
e53e13 288 tests.
CM 289
d67566 290 We've already installed the ``pytest-cov`` package into our virtual
SP 291 environment, so we can run the tests with coverage.
c60224 292
3e6b60 293 On UNIX
c60224 294 ^^^^^^^
e53e13 295
c60224 296 .. code-block:: bash
e53e13 297
779b31 298    $ $VENV/bin/py.test --cov --cov-report=term-missing
e53e13 299
3e6b60 300 On Windows
c60224 301 ^^^^^^^^^^
e53e13 302
a651b3 303 .. code-block:: doscon
e53e13 304
779b31 305    c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov \
SP 306        --cov-report=term-missing
e53e13 307
c60224 308 If successful, you will see output something like this:
3e6b60 309
c60224 310 .. code-block:: bash
3e6b60 311
c60224 312    ======================== test session starts ========================
c8a5e0 313    platform Python 3.6.0, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
c60224 314    rootdir: /Users/stevepiercy/projects/pyramidtut/tutorial, inifile:
SP 315    plugins: cov-2.2.1
316    collected 1 items
3e6b60 317
c60224 318    tutorial/tests.py .
c8a5e0 319    ------------------ coverage: platform Python 3.6.0 ------------------
c60224 320    Name                   Stmts   Miss  Cover   Missing
SP 321    ----------------------------------------------------
322    tutorial/__init__.py      12      7    42%   7-8, 14-18
323    tutorial/models.py        10      6    40%   9-14
324    tutorial/tests.py         12      0   100%
325    tutorial/views.py          4      0   100%
326    ----------------------------------------------------
327    TOTAL                     38     13    66%
328
329    ===================== 1 passed in 0.31 seconds ======================
330
331 Our package doesn't quite have 100% test coverage.
332
e53e13 333
779b31 334 .. _test_and_coverage_scaffold_defaults_zodb:
SP 335
336 Test and coverage scaffold defaults
337 -----------------------------------
338
339 Scaffolds include configuration defaults for ``py.test`` and test coverage.
340 These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
341 the root of your package. Without these defaults, we would need to specify the
342 path to the module on which we want to run tests and coverage.
343
344 On UNIX
345 ^^^^^^^
346
347 .. code-block:: bash
348
349    $ $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q
350
351 On Windows
352 ^^^^^^^^^^
353
354 .. code-block:: doscon
355
356    c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
357        --cov-report=term-missing tutorial\tests.py -q
358
359 py.test follows :ref:`conventions for Python test discovery
360 <pytest:test discovery>`, and the configuration defaults from the scaffold
361 tell ``py.test`` where to find the module on which we want to run tests and
362 coverage.
363
364 .. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
365    ``py.test -h`` to see its full set of options.
366
367
218ad4 368 .. _wiki-start-the-application:
PP 369
3e6b60 370 Start the application
c60224 371 ---------------------
f84651 372
1644ef 373 Start the application. See :ref:`what_is_this_pserve_thing` for more
MM 374 information on ``pserve``.
f84651 375
3e6b60 376 On UNIX
c60224 377 ^^^^^^^
f84651 378
c60224 379 .. code-block:: bash
f84651 380
3e6b60 381    $ $VENV/bin/pserve development.ini --reload
f84651 382
3e6b60 383 On Windows
c60224 384 ^^^^^^^^^^
f84651 385
a651b3 386 .. code-block:: doscon
f84651 387
3e6b60 388    c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload
f84651 389
e909e6 390 .. note::
K 391
392    Your OS firewall, if any, may pop up a dialog asking for authorization
393    to allow python to accept incoming network connections.
394
edc20e 395 If successful, you will see something like this on your console:
SP 396
397 .. code-block:: text
3e6b60 398
9591e9 399    Starting subprocess with file monitor
SP 400    Starting server in PID 82349.
401    serving on http://127.0.0.1:6543
3e6b60 402
SP 403 This means the server is ready to accept requests.
404
e53e13 405
c60224 406 Visit the application in a browser
SP 407 ----------------------------------
408
409 In a browser, visit http://localhost:6543/. You will see the generated
410 application's default page.
2c9f3c 411
CM 412 One thing you'll notice is the "debug toolbar" icon on right hand side of the
413 page.  You can read more about the purpose of the icon at
414 :ref:`debug_toolbar`.  It allows you to get information about your
415 application while you develop.
e53e13 416
c60224 417
3e6b60 418 Decisions the ``zodb`` scaffold has made for you
c60224 419 ------------------------------------------------
e53e13 420
197997 421 Creating a project using the ``zodb`` scaffold makes the following
b3b713 422 assumptions:
CM 423
c60224 424 - You are willing to use :term:`ZODB` as persistent storage.
b3b713 425
c60224 426 - You are willing to use :term:`traversal` to map URLs to code.
b3b713 427
9591e9 428 - You want to use pyramid_zodbconn_, pyramid_tm_, and the transaction_ packages
SP 429   to manage connections and transactions with :term:`ZODB`.
430
431 - You want to use pyramid_chameleon_ to render your templates. Different
432   templating engines can be used, but we had to choose one to make this
433   tutorial. See :ref:`available_template_system_bindings` for some options.
434
b3b713 435 .. note::
CM 436
9591e9 437    :app:`Pyramid` supports any persistent storage mechanism (e.g., an SQL
SP 438    database or filesystem files). It also supports an additional mechanism to
439    map URLs to code (:term:`URL dispatch`). However, for the purposes of this
440    tutorial, we'll only be using :term:`traversal` and :term:`ZODB`.
441
442 .. _pyramid_chameleon:
443    http://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/
444
445 .. _pyramid_tm:
446    http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
447
448 .. _pyramid_zodbconn:
449    http://docs.pylonsproject.org/projects/pyramid-zodbconn/en/latest/
450
451 .. _transaction:
452    http://zodb.readthedocs.org/en/latest/transactions.html