view | history | commit | commitdiff
Steve Piercy
2017-06-02 d34e108a059b42e01afaeebb037ec73b2a2e2e31
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 ~
813b7c 34     $ cookiecutter gh:Pylons/pyramid-cookiecutter-zodb --checkout 1.8-branch
e53e13 35
3e6b60 36 On Windows
SP 37 ^^^^^^^^^^
38
a651b3 39 .. code-block:: doscon
3e6b60 40
beb4f1 41     c:\> cd \
813b7c 42     c:\> cookiecutter gh:Pylons/pyramid-cookiecutter-zodb --checkout 1.8-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
51a39b 48 .. code-block:: text
c60224 49
51a39b 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
eb3531 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:
183     :lines: 22-26
c60224 184
SP 185 .. literalinclude:: src/installation/setup.py
beb4f1 186     :language: python
SP 187     :lineno-match:
188     :lines: 46-48
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:
382    http://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/
383
384 .. _pyramid_tm:
385    http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
386
387 .. _pyramid_zodbconn:
388    http://docs.pylonsproject.org/projects/pyramid-zodbconn/en/latest/
389
390 .. _transaction:
391    http://zodb.readthedocs.org/en/latest/transactions.html