view | history | commit | commitdiff
Steve Piercy
2017-06-02 d34e108a059b42e01afaeebb037ec73b2a2e2e31
commit | author | age
640d77 1 .. _wiki2_installation:
SP 2
e26700 3 ============
CM 4 Installation
5 ============
6
3e6b60 7 Before you begin
8571f2 8 ----------------
07c189 9
7a8b0d 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.
e26700 13
a7dd05 14 * A Python interpreter is installed on your operating system.
d67566 15 * You've satisfied the :ref:`requirements-for-installing-packages`.
8571f2 16
07c189 17
b29848 18 Install SQLite3 and its development packages
SP 19 --------------------------------------------
3e6b60 20
b29848 21 If you used a package manager to install your Python or if you compiled your Python from source, then you must install SQLite3 and its development packages.  If you downloaded your Python as an installer from https://www.python.org, then you already have it installed and can skip this step.
SP 22
23 If you need to install the SQLite3 packages, then, for example, using the Debian system and ``apt-get``, the command would be the following:
24
25 .. code-block:: bash
26
27     $ sudo apt-get install libsqlite3-dev
28
29
30 Install cookiecutter
31 --------------------
32 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.
33
34
35 Generate a Pyramid project from a cookiecutter
36 ----------------------------------------------
37
38 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.
3e6b60 39
SP 40 On UNIX
41 ^^^^^^^
42
25fed6 43 .. code-block:: bash
3e6b60 44
b29848 45     $ cd ~
813b7c 46     $ cookiecutter gh:Pylons/pyramid-cookiecutter-alchemy --checkout 1.8-branch
3e6b60 47
SP 48 On Windows
49 ^^^^^^^^^^
50
a651b3 51 .. code-block:: doscon
3e6b60 52
b29848 53     c:\> cd \
813b7c 54     c:\> cookiecutter gh:Pylons/pyramid-cookiecutter-alchemy --checkout 1.8-branch
b29848 55
SP 56 On all operating systems
57 ^^^^^^^^^^^^^^^^^^^^^^^^
58 If prompted for the first item, accept the default ``yes`` by hitting return.
59
51a39b 60 .. code-block:: text
8571f2 61
51a39b 62     You've cloned ~/.cookiecutters/pyramid-cookiecutter-alchemy before.
SP 63     Is it okay to delete and re-clone it? [yes]: yes
64     project_name [Pyramid Scaffold]: myproj
eb3531 65     repo_name [myproj]: tutorial
3e6b60 66
b29848 67 Change directory into your newly created project
SP 68 ------------------------------------------------
69
70 On UNIX
71 ^^^^^^^
72
73 .. code-block:: bash
74
75     $ cd tutorial
76
77 On Windows
78 ^^^^^^^^^^
79
80 .. code-block:: doscon
81
82     c:\> cd tutorial
83
84
85 Set and use a ``VENV`` environment variable
7a8b0d 86 -------------------------------------------
e26700 87
b29848 88 We will set the ``VENV`` environment variable to the absolute path of the virtual environment, and use it going forward.
7a8b0d 89
70cc73 90 On UNIX
SP 91 ^^^^^^^
7a8b0d 92
25fed6 93 .. code-block:: bash
7a8b0d 94
b29848 95     $ export VENV=~/tutorial
7a8b0d 96
70cc73 97 On Windows
SP 98 ^^^^^^^^^^
7a8b0d 99
a651b3 100 .. code-block:: doscon
7a8b0d 101
b29848 102     c:\tutorial> set VENV=c:\tutorial
7a8b0d 103
b29848 104
SP 105 Create a virtual environment
106 ----------------------------
107
108 On UNIX
109 ^^^^^^^
110
111 .. code-block:: bash
112
113     $ python3 -m venv $VENV
114
115 On Windows
116 ^^^^^^^^^^
117
7ed8e2 118 Each version of Python uses different paths, so you will 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.
7a8b0d 119
SP 120 Python 2.7:
121
a651b3 122 .. code-block:: doscon
7a8b0d 123
b29848 124     c:\tutorial> c:\Python27\Scripts\virtualenv %VENV%
7a8b0d 125
c8a5e0 126 Python 3.6:
7a8b0d 127
a651b3 128 .. code-block:: doscon
7a8b0d 129
7ed8e2 130     c:\tutorial> python -m venv %VENV%
25fed6 131
SP 132
b29848 133 Upgrade packaging tools in the virtual environment
SP 134 --------------------------------------------------
a7dd05 135
SP 136 On UNIX
137 ^^^^^^^
138
139 .. code-block:: bash
140
da6244 141     $ $VENV/bin/pip install --upgrade pip setuptools
a7dd05 142
SP 143 On Windows
144 ^^^^^^^^^^
145
a651b3 146 .. code-block:: doscon
a7dd05 147
b29848 148     c:\tutorial> %VENV%\Scripts\pip install --upgrade pip setuptools
e26700 149
25fed6 150
af1a96 151 .. _installing_project_in_dev_mode:
TL 152
3e6b60 153 Installing the project in development mode
8571f2 154 ------------------------------------------
e26700 155
b29848 156 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.
e26700 157
70cc73 158 On UNIX
8571f2 159 ^^^^^^^
e26700 160
25fed6 161 .. code-block:: bash
e26700 162
b29848 163     $ $VENV/bin/pip install -e ".[testing]"
e26700 164
70cc73 165 On Windows
8571f2 166 ^^^^^^^^^^
e26700 167
a651b3 168 .. code-block:: doscon
e26700 169
b29848 170     c:\tutorial> %VENV%\Scripts\pip install -e ".[testing]"
25fed6 171
b29848 172 On all operating systems
SP 173 ^^^^^^^^^^^^^^^^^^^^^^^^
174
175 The console will show ``pip`` checking for packages and installing missing packages. Success executing this command will show a line like the following:
6772a2 176
e551a4 177 .. code-block:: bash
SP 178
b29848 179     Successfully installed Jinja2-2.8 Mako-1.0.6 MarkupSafe-0.23 \
SP 180     PasteDeploy-1.5.2 Pygments-2.1.3 SQLAlchemy-1.1.4 WebOb-1.6.3 \
181     WebTest-2.0.24 beautifulsoup4-4.5.1 coverage-4.2 py-1.4.32 pyramid-1.7.3 \
182     pyramid-debugtoolbar-3.0.5 pyramid-jinja2-2.7 pyramid-mako-1.0.2 \
2d5234 183     pyramid-tm-1.1.1 pytest-3.0.5 pytest-cov-2.4.0 repoze.lru-0.6 six-1.10.0 \
SP 184     transaction-2.0.3 translationstring-1.3 tutorial venusian-1.0 \
b29848 185     waitress-1.0.1 zope.deprecation-4.2.0 zope.interface-4.3.3 \
SP 186     zope.sqlalchemy-0.7.7
e551a4 187
b29848 188 Testing requirements are defined in our project's ``setup.py`` file, in the ``tests_require`` and ``extras_require`` stanzas.
e551a4 189
d8be5a 190 .. literalinclude:: src/installation/setup.py
SP 191    :language: python
b29848 192    :lineno-match:
d8be5a 193    :lines: 22-26
e551a4 194
d8be5a 195 .. literalinclude:: src/installation/setup.py
SP 196    :language: python
b29848 197    :lineno-match:
SP 198    :lines: 46-48
e551a4 199
6772a2 200
e26700 201 .. _sql_running_tests:
CM 202
3e6b60 203 Run the tests
8571f2 204 -------------
e26700 205
e551a4 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
SP 208 provide options to py.test that specify the module for which its tests shall be
209 run, and to run py.test in quiet mode.
e26700 210
70cc73 211 On UNIX
8571f2 212 ^^^^^^^
e26700 213
25fed6 214 .. code-block:: bash
e26700 215
5e3eeb 216    $ $VENV/bin/py.test -q
e551a4 217
70cc73 218 On Windows
8571f2 219 ^^^^^^^^^^
e26700 220
a651b3 221 .. code-block:: doscon
e26700 222
b29848 223    c:\tutorial> %VENV%\Scripts\py.test -q
6772a2 224
e551a4 225 For a successful test run, you should see output that ends like this:
SP 226
227 .. code-block:: bash
6772a2 228
8571f2 229    ..
e551a4 230    2 passed in 0.44 seconds
13846e 231
e26700 232
3e6b60 233 Expose test coverage information
8571f2 234 --------------------------------
e26700 235
e551a4 236 You can run the ``py.test`` command to see test coverage information. This
SP 237 runs the tests in the same way that ``py.test`` does, but provides additional
b29848 238 :term:`coverage` information, exposing which lines of your project are covered by the
e551a4 239 tests.
e26700 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.
e26700 243
70cc73 244 On UNIX
8571f2 245 ^^^^^^^
e26700 246
25fed6 247 .. code-block:: bash
e26700 248
5e3eeb 249    $ $VENV/bin/py.test --cov --cov-report=term-missing
e26700 250
70cc73 251 On Windows
8571f2 252 ^^^^^^^^^^
e26700 253
a651b3 254 .. code-block:: doscon
e26700 255
b29848 256    c:\tutorial> %VENV%\Scripts\py.test --cov --cov-report=term-missing
e26700 257
25c809 258 If successful, you will see output something like this:
6772a2 259
25c809 260 .. code-block:: bash
6772a2 261
b29848 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 2 items
e551a4 267
b29848 268     tutorial/tests.py ..
SP 269     ------------------ coverage: platform Python 3.6.0 ------------------
270     Name                               Stmts   Miss  Cover   Missing
271     ----------------------------------------------------------------
272     tutorial/__init__.py                   8      6    25%   7-12
273     tutorial/models/__init__.py           22      0   100%
274     tutorial/models/meta.py                5      0   100%
275     tutorial/models/mymodel.py             8      0   100%
276     tutorial/routes.py                     3      2    33%   2-3
277     tutorial/scripts/__init__.py           0      0   100%
278     tutorial/scripts/initializedb.py      26     16    38%   22-25, 29-45
279     tutorial/views/__init__.py             0      0   100%
280     tutorial/views/default.py             12      0   100%
281     tutorial/views/notfound.py             4      2    50%   6-7
282     ----------------------------------------------------------------
283     TOTAL                                 88     26    70%
284     ===================== 2 passed in 0.57 seconds ======================
6772a2 285
8571f2 286 Our package doesn't quite have 100% test coverage.
SP 287
e26700 288
b29848 289 .. _test_and_coverage_cookiecutter_defaults_sql:
5e3eeb 290
b29848 291 Test and coverage cookiecutter defaults
SP 292 ---------------------------------------
5e3eeb 293
b29848 294 Cookiecutters include configuration defaults for ``py.test`` and test coverage.
5e3eeb 295 These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
SP 296 the root of your package. Without these defaults, we would need to specify the
297 path to the module on which we want to run tests and coverage.
298
299 On UNIX
300 ^^^^^^^
301
302 .. code-block:: bash
303
304    $ $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q
305
306 On Windows
307 ^^^^^^^^^^
308
309 .. code-block:: doscon
310
b29848 311    c:\tutorial> %VENV%\Scripts\py.test --cov=tutorial tutorial\tests.py -q
5e3eeb 312
SP 313 py.test follows :ref:`conventions for Python test discovery
b29848 314 <pytest:test discovery>`, and the configuration defaults from the cookiecutter
5e3eeb 315 tell ``py.test`` where to find the module on which we want to run tests and
SP 316 coverage.
317
318 .. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
319    ``py.test -h`` to see its full set of options.
320
321
af1a96 322 .. _initialize_db_wiki2:
TL 323
3e6b60 324 Initializing the database
8571f2 325 -------------------------
6772a2 326
8571f2 327 We need to use the ``initialize_tutorial_db`` :term:`console script` to
SP 328 initialize our database.
6772a2 329
d6243a 330 .. note::
MM 331
8571f2 332    The ``initialize_tutorial_db`` command does not perform a migration, but
SP 333    rather it simply creates missing tables and adds some dummy data. If you
a7dd05 334    already have a database, you should delete it before running
SP 335    ``initialize_tutorial_db`` again.
336
ee9676 337 Type the following command, making sure you are still in the ``tutorial``
b284c6 338 directory (the directory with a ``development.ini`` in it):
6772a2 339
70cc73 340 On UNIX
8571f2 341 ^^^^^^^
6772a2 342
25fed6 343 .. code-block:: bash
6772a2 344
f73f0e 345    $ $VENV/bin/initialize_tutorial_db development.ini
6772a2 346
70cc73 347 On Windows
8571f2 348 ^^^^^^^^^^
6772a2 349
a651b3 350 .. code-block:: doscon
6772a2 351
b29848 352    c:\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini
6772a2 353
d8be5a 354 The output to your console should be something like this:
6772a2 355
d8be5a 356 .. code-block:: bash
SP 357
b29848 358     2016-12-18 21:30:08,675 INFO  [sqlalchemy.engine.base.Engine:1235][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
SP 359     2016-12-18 21:30:08,675 INFO  [sqlalchemy.engine.base.Engine:1236][MainThread] ()
360     2016-12-18 21:30:08,676 INFO  [sqlalchemy.engine.base.Engine:1235][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
361     2016-12-18 21:30:08,676 INFO  [sqlalchemy.engine.base.Engine:1236][MainThread] ()
362     2016-12-18 21:30:08,676 INFO  [sqlalchemy.engine.base.Engine:1140][MainThread] PRAGMA table_info("models")
363     2016-12-18 21:30:08,676 INFO  [sqlalchemy.engine.base.Engine:1143][MainThread] ()
364     2016-12-18 21:30:08,677 INFO  [sqlalchemy.engine.base.Engine:1140][MainThread]
365     CREATE TABLE models (
366             id INTEGER NOT NULL,
367             name TEXT,
368             value INTEGER,
369             CONSTRAINT pk_models PRIMARY KEY (id)
370     )
ee9676 371
SP 372
b29848 373     2016-12-18 21:30:08,677 INFO  [sqlalchemy.engine.base.Engine:1143][MainThread] ()
SP 374     2016-12-18 21:30:08,678 INFO  [sqlalchemy.engine.base.Engine:719][MainThread] COMMIT
375     2016-12-18 21:30:08,679 INFO  [sqlalchemy.engine.base.Engine:1140][MainThread] CREATE UNIQUE INDEX my_index ON models (name)
376     2016-12-18 21:30:08,679 INFO  [sqlalchemy.engine.base.Engine:1143][MainThread] ()
377     2016-12-18 21:30:08,679 INFO  [sqlalchemy.engine.base.Engine:719][MainThread] COMMIT
378     2016-12-18 21:30:08,681 INFO  [sqlalchemy.engine.base.Engine:679][MainThread] BEGIN (implicit)
379     2016-12-18 21:30:08,682 INFO  [sqlalchemy.engine.base.Engine:1140][MainThread] INSERT INTO models (name, value) VALUES (?, ?)
380     2016-12-18 21:30:08,682 INFO  [sqlalchemy.engine.base.Engine:1143][MainThread] ('one', 1)
381     2016-12-18 21:30:08,682 INFO  [sqlalchemy.engine.base.Engine:719][MainThread] COMMIT
6772a2 382
8571f2 383 Success!  You should now have a ``tutorial.sqlite`` file in your current
SP 384 working directory. This is an SQLite database with a single table defined in it
6772a2 385 (``models``).
CM 386
b284c6 387 .. _wiki2-start-the-application:
6772a2 388
3e6b60 389 Start the application
8571f2 390 ---------------------
b284c6 391
1644ef 392 Start the application. See :ref:`what_is_this_pserve_thing` for more
MM 393 information on ``pserve``.
6772a2 394
70cc73 395 On UNIX
8571f2 396 ^^^^^^^
6772a2 397
25fed6 398 .. code-block:: bash
6772a2 399
f73f0e 400    $ $VENV/bin/pserve development.ini --reload
6772a2 401
70cc73 402 On Windows
8571f2 403 ^^^^^^^^^^
6772a2 404
a651b3 405 .. code-block:: doscon
6772a2 406
b29848 407    c:\tutorial> %VENV%\Scripts\pserve development.ini --reload
6772a2 408
3e6b60 409 .. note::
SP 410
411    Your OS firewall, if any, may pop up a dialog asking for authorization
412    to allow python to accept incoming network connections.
413
9591e9 414 If successful, you will see something like this on your console:
SP 415
416 .. code-block:: text
b284c6 417
b29848 418     Starting subprocess with file monitor
SP 419     Starting server in PID 44078.
420     Serving on http://localhost:6543
421     Serving on http://localhost:6543
b284c6 422
PP 423 This means the server is ready to accept requests.
424
8571f2 425
3e6b60 426 Visit the application in a browser
8571f2 427 ----------------------------------
3e6b60 428
9591e9 429 In a browser, visit http://localhost:6543/. You will see the generated
13846e 430 application's default page.
e26700 431
2c9f3c 432 One thing you'll notice is the "debug toolbar" icon on right hand side of the
CM 433 page.  You can read more about the purpose of the icon at
434 :ref:`debug_toolbar`.  It allows you to get information about your
435 application while you develop.
436
8571f2 437
b29848 438 Decisions the ``alchemy`` cookiecutter has made for you
SP 439 -------------------------------------------------------
e26700 440
b29848 441 Creating a project using the ``alchemy`` cookiecutter makes the following
3e6b60 442 assumptions:
b2adfe 443
b29848 444 - You are willing to use SQLite for persistent storage, although almost any SQL database could be used with SQLAlchemy.
SP 445
446 - You are willing to use :term:`SQLAlchemy` for a database access tool.
b2adfe 447
8d4571 448 - You are willing to use :term:`URL dispatch` to map URLs to code.
b2adfe 449
d8be5a 450 - You want to use zope.sqlalchemy_, pyramid_tm_, and the transaction_ packages
a7dd05 451   to scope sessions to requests.
8d4571 452
8571f2 453 - You want to use pyramid_jinja2_ to render your templates. Different
SP 454   templating engines can be used, but we had to choose one to make this
455   tutorial. See :ref:`available_template_system_bindings` for some options.
e91085 456
b2adfe 457 .. note::
CM 458
ee9676 459    :app:`Pyramid` supports any persistent storage mechanism (e.g., object
8571f2 460    database or filesystem files). It also supports an additional mechanism to
SP 461    map URLs to code (:term:`traversal`). However, for the purposes of this
9591e9 462    tutorial, we'll only be using :term:`URL dispatch` and :term:`SQLAlchemy`.
8d4571 463
MM 464 .. _pyramid_jinja2:
465    http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/
466
467 .. _pyramid_tm:
468    http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
469
470 .. _zope.sqlalchemy:
471    https://pypi.python.org/pypi/zope.sqlalchemy
472
473 .. _transaction:
474    http://zodb.readthedocs.org/en/latest/transactions.html