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