view | history | commit | commitdiff
Steve Piercy
2017-06-27 7b16126c85c466be09868c26ea67e09bfa18a446
commit | author | age
837916 1 .. _project_narr:
CM 2
fd5ae9 3 Creating a :app:`Pyramid` Project
609a99 4 =================================
54f2bb 5
a54e4c 6 As we saw in :ref:`firstapp_chapter`, it's possible to create a :app:`Pyramid`
SP 7 application completely manually.  However, it's usually more convenient to use
e2cda9 8 a :term:`cookiecutter` to generate a basic :app:`Pyramid` :term:`project`.
41e3bf 9
3f695c 10 A project is a directory that contains at least one Python :term:`package`.
e2cda9 11 You'll use a cookiecutter to create a project, and you'll create your application
a54e4c 12 logic within a package that lives inside the project.  Even if your application
SP 13 is extremely simple, it is useful to place code that drives the application
14 within a package, because (1) a package is more easily extended with new code,
15 and (2) an application that lives inside a package can also be distributed more
16 easily than one which does not live within a package.
9ec2d6 17
e2cda9 18 The Pylons Project provides several :app:`Pyramid` cookiecutters that you can use to generate a
SP 19 project.  Each cookiecutter makes different configuration assumptions about what
a54e4c 20 type of application you're trying to construct.
a119be 21
e2cda9 22 These cookiecutters are rendered using the ``cookiecutter`` command that you may install.
SP 23
24 .. seealso::
25
e1b26e 26     See also `Cookiecutter Installation <https://cookiecutter.readthedocs.io/en/latest/installation.html>`_.
e2cda9 27
9ec2d6 28
CM 29 .. index::
e2cda9 30    single: cookiecutters
SP 31    single: pyramid-cookiecutter-starter
32    single: pyramid-cookiecutter-zodb
33    single: pyramid-cookiecutter-alchemy
9ec2d6 34
e2cda9 35 .. _additional_cookiecutters:
9ec2d6 36
e2cda9 37 :app:`Pyramid` cookiecutters
SP 38 ----------------------------
39
ff7fc4 40 Pyramid cookiecutters released under the Pylons Project differ from each other on a number of axes:
e2cda9 41
e1b26e 42 - the persistence mechanism they offer (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`)
SP 43
44 - the mechanism they use to map URLs to code (:term:`URL dispatch` or :term:`traversal`)
45
6204d8 46 - templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`)
e1b26e 47
e2cda9 48 * `pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_
e1b26e 49 * `pyramid-cookiecutter-alchemy <https://github.com/Pylons/pyramid-cookiecutter-alchemy>`_
e2cda9 50 * `pyramid-cookiecutter-zodb <https://github.com/Pylons/pyramid-cookiecutter-zodb>`_
SP 51
e1b26e 52 These cookiecutters include:
9ec2d6 53
e1b26e 54 ``pyramid-cookiecutter-starter``
6204d8 55     :term:`URL dispatch` for routing and either :term:`Jinja2`, :term:`Chameleon`, or :term:`Mako` for templating
9ec2d6 56
e1b26e 57 ``pyramid-cookiecutter-alchemy``
SP 58     SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Jinja2` for templating.
9ec2d6 59
e1b26e 60 ``pyramid-cookiecutter-zodb``
SP 61     :term:`ZODB` for persistent storage, :term:`traversal` for routing, and :term:`Chameleon` for templating
8afd28 62
5ff3d2 63
8c56ae 64 .. index::
c5f24b 65    single: creating a project
CM 66    single: project
e1b26e 67    single: cookiecutter
8c56ae 68
e60df4 69 .. _creating_a_project:
CM 70
0bc787 71 Creating the Project
CM 72 --------------------
5ff3d2 73
a54e4c 74 In :ref:`installing_chapter`, you created a virtual Python environment via the
e1b26e 75 ``venv`` command. We called the virtual environment directory
SP 76 ``env`` and set an environment variable ``VENV`` to its path.
545654 77
7ed8e2 78 We assume that you :ref:`previously installed cookiecutter <cookiecutters>`, following its installation instructions.
e1b26e 79
SP 80 We'll choose ``pyramid-cookiecutter-starter`` to start the project.  When we invoke ``cookiecutter``, it will create a directory that represents our project.
81
7ed8e2 82 We assume our current working directory is the value of ``VENV``.
0dd16d 83
7ed8e2 84 On all platforms, generate a project using cookiecutter.
54f2bb 85
d4177a 86 .. code-block:: bash
189c6e 87
1aa283 88    $ cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.9-branch
54f2bb 89
e1b26e 90 If prompted for the first item, accept the default ``yes`` by hitting return.
SP 91
2cd381 92 .. code-block:: text
SP 93
94     You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before.
95     Is it okay to delete and re-clone it? [yes]: yes
96     project_name [Pyramid Scaffold]: myproject
6ff6fa 97     repo_name [myproject]: myproject
2cd381 98     Select template_language:
SP 99     1 - jinja2
100     2 - chameleon
6204d8 101     3 - mako
SP 102     Choose from 1, 2, 3 [1]: 1
e1b26e 103
SP 104 We then run through the following commands.
105
106 On UNIX:
107
108 .. code-block:: bash
109
110     # Reset our environment variable for a new virtual environment.
111     $ export VENV=~/env/myproject/env
112     # Change directory into your newly created project.
113     $ cd myproject
114     # Create a new virtual environment...
115     $ python3 -m venv $VENV
116     # ...where we upgrade packaging tools.
117     $ env/bin/pip install --upgrade pip setuptools
118
119 Or on Windows:
120
121 .. code-block:: doscon
122
123     # Reset our environment variable for a new virtual environment.
124     c:\> set VENV=c:\env\myproject\env
125     # Change directory into your newly created project.
126     c:\> cd myproject
127     # Create a new virtual environment...
7ed8e2 128     c:\myproject> python -m venv %VENV%
e1b26e 129     # ...where we upgrade packaging tools.
7ed8e2 130     c:\myproject> %VENV%\Scripts\pip install --upgrade pip setuptools
e1b26e 131
SP 132 As a result of invoking the ``cookiecutter`` command, a directory named
133 ``myproject`` is created.  That directory is a :term:`project` directory. The
a54e4c 134 ``setup.py`` file in that directory can be used to distribute your application,
SP 135 or install your application for deployment or development.
9ec2d6 136
f21b2b 137 An ``.ini`` file named ``development.ini`` will be created in the project
a54e4c 138 directory.  You will use this ``.ini`` file to configure a server, to run your
SP 139 application, and to debug your application.  It contains configuration that
140 enables an interactive debugger and settings optimized for development.
43ab04 141
cfb2b5 142 Another ``.ini`` file named ``production.ini`` will also be created in the
f23bec 143 project directory.  It contains configuration that disables any interactive
cfb2b5 144 debugger (to prevent inappropriate access and disclosure), and turns off a
CM 145 number of debugging settings.  You can use this file to put your application
146 into production.
54f2bb 147
e1b26e 148 The ``myproject`` project directory contains an additional subdirectory named
a54e4c 149 ``myproject`` (note the case difference) representing a Python :term:`package`
SP 150 which holds very simple :app:`Pyramid` sample code.  This is where you'll edit
151 your application's Python code and templates.
54f2bb 152
e1b26e 153 We created this project in a directory next to its virtual environment directory.
d67566 154 However, note that this is not mandatory. The project directory can go more or
SP 155 less anywhere on your filesystem. You don't need to put it in a special "web
e1b26e 156 server" directory. You could put it within a virtual environment
d67566 157 directory. The author uses Linux mainly, and tends to put project directories
SP 158 which he creates within his ``~/projects`` directory. On Windows, it's a good
159 idea to put project directories within a directory that contains no space
160 characters, so it's wise to *avoid* a path that contains, i.e., ``My
161 Documents``. As a result, the author, when he uses Windows, just puts his
162 projects in ``C:\projects``.
545654 163
1a76ed 164 .. warning::
7b5544 165
e1b26e 166    You'll need to avoid using ``cookiecutter`` to create a project with the same
be8e3a 167    name as a Python standard library component. In particular, this means you
a54e4c 168    should avoid using the names ``site`` or ``test``, both of which conflict
SP 169    with Python standard library packages.  You should also avoid using the name
170    ``pyramid``, which will conflict with Pyramid itself.
7b5544 171
8c56ae 172 .. index::
9ec2d6 173    single: setup.py develop
CM 174    single: development install
2ff0c8 175
54f2bb 176 Installing your Newly Created Project for Development
CM 177 -----------------------------------------------------
178
429029 179 To install a newly created project for development, you should ``cd`` to the
CM 180 newly created project directory and use the Python interpreter from the
d67566 181 :term:`virtual environment` you created during :ref:`installing_chapter` to
SP 182 invoke the command ``pip install -e .``, which installs the project in
183 development mode (``-e`` is for "editable") into the current directory (``.``).
429029 184
e1b26e 185 The file named ``setup.py`` will be in the root of the cookiecutter-generated
a54e4c 186 project directory.  The ``python`` you're invoking should be the one that lives
SP 187 in the ``bin`` (or ``Scripts`` on Windows) directory of your virtual Python
188 environment.  Your terminal's current working directory *must* be the newly
189 created project directory.
d0ec94 190
CM 191 On UNIX:
54f2bb 192
d4177a 193 .. code-block:: bash
8f7262 194
e1b26e 195     $ $VENV/bin/pip install -e .
8f7262 196
d0ec94 197 Or on Windows:
189c6e 198
a651b3 199 .. code-block:: doscon
189c6e 200
7ed8e2 201     c:\env\myproject> %VENV%\Scripts\pip install -e .
d0ec94 202
CM 203 Elided output from a run of this command on UNIX is shown below:
204
d4177a 205 .. code-block:: bash
d0ec94 206
e1b26e 207       Running setup.py develop for myproject
SP 208     Successfully installed Jinja2-2.8 Mako-1.0.6 MarkupSafe-0.23 \
209     PasteDeploy-1.5.2 Pygments-2.1.3 WebOb-1.7.0 myproject pyramid-1.7.3 \
210     pyramid-debugtoolbar-3.0.5 pyramid-jinja2-2.7 pyramid-mako-1.0.2 \
211     repoze.lru-0.6 translationstring-1.3 venusian-1.0 waitress-1.0.1 \
212     zope.deprecation-4.2.0 zope.interface-4.3.3
54f2bb 213
a54e4c 214 This will install a :term:`distribution` representing your project into the
SP 215 virtual environment interpreter's library set so it can be found by ``import``
216 statements and by other console scripts such as ``pserve``, ``pshell``,
217 ``proutes``, and ``pviews``.
54f2bb 218
8c56ae 219 .. index::
c5f24b 220    single: running tests
CM 221    single: tests (running)
8c56ae 222
609a99 223 Running the Tests for Your Application
8e0dfc 224 --------------------------------------
54f2bb 225
f21b2b 226 To run unit tests for your application, you must first install the testing
SP 227 dependencies.
d0ec94 228
CM 229 On UNIX:
8f7262 230
d4177a 231 .. code-block:: bash
8f7262 232
f21b2b 233    $ $VENV/bin/pip install -e ".[testing]"
8e0dfc 234
f21b2b 235 On Windows:
8e0dfc 236
a651b3 237 .. code-block:: doscon
189c6e 238
7ed8e2 239    c:\env\myproject> %VENV%\Scripts\pip install -e ".[testing]"
f21b2b 240
SP 241 Once the testing requirements are installed, then you can run the tests using
242 the ``py.test`` command that was just installed in the ``bin`` directory of
243 your virtual environment.
244
245 On UNIX:
246
247 .. code-block:: bash
248
68ba58 249    $ $VENV/bin/py.test -q
f21b2b 250
SP 251 On Windows:
252
a651b3 253 .. code-block:: doscon
f21b2b 254
7ed8e2 255    c:\env\myproject> %VENV%\Scripts\py.test -q
d0ec94 256
CM 257 Here's sample output from a test run on UNIX:
258
d4177a 259 .. code-block:: bash
d0ec94 260
68ba58 261    $ $VENV/bin/py.test -q
f21b2b 262    ..
SP 263    2 passed in 0.47 seconds
0bd226 264
e1b26e 265 The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project.  Within a project generated by the ``pyramid-cookiecutter-starter`` cookiecutter, only two sample tests exist.
5ded35 266
SP 267 .. note::
268
f21b2b 269     The ``-q`` option is passed to the ``py.test`` command to limit the output
SP 270     to a stream of dots. If you don't pass ``-q``, you'll see verbose test
271     result output (which normally isn't very useful).
e8561f 272
68ba58 273 Alternatively, if you'd like to see test coverage, pass the ``--cov`` option
VF 274 to ``py.test``:
275
276 .. code-block:: bash
277
e09369 278    $ $VENV/bin/py.test --cov -q
SP 279
e1b26e 280 Cookiecutters include configuration defaults for ``py.test`` and test coverage.
e09369 281 These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
SP 282 the root of your package. Without these defaults, we would need to specify the
283 path to the module on which we want to run tests and coverage.
284
285 .. code-block:: bash
286
287    $ $VENV/bin/py.test --cov=myproject myproject/tests.py -q
288
289 .. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
290    ``py.test -h`` to see its full set of options.
68ba58 291
VF 292
9ec2d6 293 .. index::
CM 294    single: running an application
cfb2b5 295    single: pserve
9ec2d6 296    single: reload
CM 297    single: startup
298
eb3b27 299 .. _running_the_project_application:
KOP 300
609a99 301 Running the Project Application
e0fc0b 302 -------------------------------
0bc787 303
fa257d 304 .. seealso:: See also the output of :ref:`pserve --help <pserve_script>`.
5ff3d2 305
a119be 306 Once a project is installed for development, you can run the application it
cfb2b5 307 represents using the ``pserve`` command against the generated configuration
CM 308 file.  In our case, this file is named ``development.ini``.
d0ec94 309
CM 310 On UNIX:
0bc787 311
d4177a 312 .. code-block:: bash
793425 313
f73f0e 314    $ $VENV/bin/pserve development.ini
793425 315
d0ec94 316 On Windows:
CM 317
e1b26e 318 .. code-block:: doscon
d0ec94 319
7ed8e2 320    c:\env\myproject> %VENV%\Scripts\pserve development.ini
d0ec94 321
cfb2b5 322 Here's sample output from a run of ``pserve`` on UNIX:
189c6e 323
d4177a 324 .. code-block:: bash
189c6e 325
f73f0e 326    $ $VENV/bin/pserve development.ini
e1b26e 327    Starting server in PID 77171.
SP 328    Serving on http://localhost:6543
329    Serving on http://localhost:6543
0bc787 330
d4177a 331 Access is restricted such that only a browser running on the same machine as
SP 332 Pyramid will be able to access your Pyramid application.  However, if you want
333 to open access to other machines on the same network, then edit the
07e802 334 ``development.ini`` file, and replace the ``listen`` value in the
b57460 335 ``[server:main]`` section, changing it from ``localhost:6543`` to ``*:6543``
fb17a3 336 (this is equivalent to ``0.0.0.0:6543 [::]:6543``).  For example:
38669d 337
TL 338 .. code-block:: ini
dace59 339
CM 340    [server:main]
341    use = egg:waitress#main
fb17a3 342    listen = *:6543
d4177a 343
SP 344 Now when you use ``pserve`` to start the application, it will respond to
345 requests on *all* IP addresses possessed by your system, not just requests to
346 ``localhost``.  This is what the ``0.0.0.0`` in
347 ``serving on http://0.0.0.0:6543`` means.  The server will respond to requests
348 made to ``127.0.0.1`` and on any external IP address. For example, your system
349 might be configured to have an external IP address ``192.168.1.50``.  If that's
350 the case, if you use a browser running on the same system as Pyramid, it will
351 be able to access the application via ``http://127.0.0.1:6543/`` as well as via
352 ``http://192.168.1.50:6543/``. However, *other people* on other computers on
353 the same network will also be able to visit your Pyramid application in their
3c5731 354 browser by visiting ``http://192.168.1.50:6543/``. The same holds true if you use
M 355 IPv6. ``[::]`` means the same as ``0.0.0.0`` but for IPv6 protocol.
dace59 356
CM 357 You can change the port on which the server runs on by changing the same
358 portion of the ``development.ini`` file.  For example, you can change the
b57460 359 ``listen = localhost:6543`` line in the ``development.ini`` file's ``[server:main]``
SP 360 section to ``listen = localhost:8080`` to run the server on port 8080 instead of port 6543.
dace59 361
609a99 362 You can shut down a server started this way by pressing ``Ctrl-C`` (or
SP 363 ``Ctrl-Break`` on Windows).
a119be 364
7a89a4 365 The default server used to run your Pyramid application when a project is
e1b26e 366 created from a cookiecutter is named :term:`Waitress`.  This server is what prints
SP 367 the ``Serving on...`` line when you run ``pserve``.  It's a good idea to use
a54e4c 368 this server during development because it's very simple.  It can also be used
SP 369 for light production.  Setting your application up under a different server is
370 not advised until you've done some development work under the default server,
371 particularly if you're not yet experienced with Python web development.  Python
372 web server setup can be complex, and you should get some confidence that your
373 application works in a default environment before trying to optimize it or make
374 it "more like production".  It's awfully easy to get sidetracked trying to set
375 up a non-default server for hours without actually starting to do any
376 development.  One of the nice things about Python web servers is that they're
377 largely interchangeable, so if your application works under the default server,
378 it will almost certainly work under any other server in production if you
379 eventually choose to use a different one.  Don't worry about it right now.
7a89a4 380
CM 381 For more detailed information about the startup process, see
382 :ref:`startup_chapter`.  For more information about environment variables and
383 configuration file settings that influence startup and runtime behavior, see
384 :ref:`environment_chapter`.
385
386 .. _reloading_code:
387
388 Reloading Code
389 ~~~~~~~~~~~~~~
390
a54e4c 391 During development, it's often useful to run ``pserve`` using its ``--reload``
SP 392 option.  When ``--reload`` is passed to ``pserve``, changes to any Python
393 module your project uses will cause the server to restart.  This typically
394 makes development easier, as changes to Python code made within a
cfb2b5 395 :app:`Pyramid` application is not put into effect until the server restarts.
9ec2d6 396
d0ec94 397 For example, on UNIX:
9ec2d6 398
CM 399 .. code-block:: text
400
f73f0e 401    $ $VENV/bin/pserve development.ini --reload
9ec2d6 402    Starting subprocess with file monitor
CM 403    Starting server in PID 16601.
e1b26e 404    Serving on http://localhost:6543
SP 405    Serving on http://localhost:6543
6ce1e0 406
5991d9 407 Now if you make a change to any of your project's ``.py`` files or ``.ini``
CM 408 files, you'll see the server restart automatically:
409
410 .. code-block:: text
411
412    development.ini changed; reloading...
413    -------------------- Restarting --------------------
414    Starting server in PID 16602.
e1b26e 415    Serving on http://localhost:6543
SP 416    Serving on http://localhost:6543
5991d9 417
CM 418 Changes to template files (such as ``.pt`` or ``.mak`` files) won't cause the
a54e4c 419 server to restart.  Changes to template files don't require a server restart as
SP 420 long as the ``pyramid.reload_templates`` setting in the ``development.ini``
e1b26e 421 file is ``true``.  Changes made to template files when this setting is ``true``
a54e4c 422 will take effect immediately without a server restart.
5991d9 423
6ce1e0 424 .. index::
CM 425    single: WSGI
b17af4 426
0bc787 427 Viewing the Application
CM 428 -----------------------
429
cfb2b5 430 Once your application is running via ``pserve``, you may visit
a119be 431 ``http://localhost:6543/`` in your browser.  You will see something in your
CM 432 browser like what is displayed in the following image:
0bc787 433
eff462 434 .. image:: project.png
0bc787 435
e1b26e 436 This is the page shown by default when you visit an unmodified ``cookiecutter``
SP 437 generated ``pyramid-cookiecutter-starter`` application in a browser.
a119be 438
2c9f3c 439 .. index::
CM 440    single: debug toolbar
441
442 .. _debug_toolbar:
443
444 The Debug Toolbar
445 ~~~~~~~~~~~~~~~~~
446
609a99 447 .. image:: project-show-toolbar.png
SP 448
449 If you click on the :app:`Pyramid` logo at the top right of the page, a new
450 target window will open to present a debug toolbar that provides various
a54e4c 451 niceties while you're developing.  This logo will float above every HTML page
SP 452 served by :app:`Pyramid` while you develop an application, and allows you to
453 show the toolbar as necessary.
c6d9f1 454
CM 455 .. image:: project-debug.png
456
a54e4c 457 If you don't see the Pyramid logo on the top right of the page, it means you're
SP 458 browsing from a system that does not have debugging access.  By default, for
459 security reasons, only a browser originating from ``localhost`` (``127.0.0.1``)
460 can see the debug toolbar.  To allow your browser on a remote system to access
461 the server, add a line within the ``[app:main]`` section of the
462 ``development.ini`` file in the form ``debugtoolbar.hosts = X .X.X.X``.  For
463 example, if your Pyramid application is running on a remote system, and you're
464 browsing from a host with the IP address ``192.168.1.1``, you'd add something
465 like this to enable the toolbar when your system contacts Pyramid:
9bdb09 466
CM 467 .. code-block:: ini
468
469    [app:main]
72bb71 470    # .. other settings ...
9bdb09 471    debugtoolbar.hosts = 192.168.1.1
CM 472
f21b2b 473 For more information about what the debug toolbar allows you to do, see the
SP 474 :ref:`documentation for pyramid_debugtoolbar <toolbar:overview>`.
c6d9f1 475
a54e4c 476 The debug toolbar will not be shown (and all debugging will be turned off) when
SP 477 you use the ``production.ini`` file instead of the ``development.ini`` ini file
478 to run the application.
c6d9f1 479
06247f 480 You can also turn the debug toolbar off by editing ``development.ini`` and
d21ba4 481 commenting out a line.  For example, instead of:
06247f 482
CM 483 .. code-block:: ini
484    :linenos:
485
3d338e 486    [app:main]
3cdd3c 487    # ... elided configuration
d21ba4 488    pyramid.includes =
CM 489        pyramid_debugtoolbar
06247f 490
d21ba4 491 Put a hash mark at the beginning of the ``pyramid_debugtoolbar`` line:
06247f 492
CM 493 .. code-block:: ini
494    :linenos:
495
3d338e 496    [app:main]
3cdd3c 497    # ... elided configuration
d21ba4 498    pyramid.includes =
CM 499    #    pyramid_debugtoolbar
06247f 500
CM 501 Then restart the application to see that the toolbar has been turned off.
8f7262 502
f57b56 503 Note that if you comment out the ``pyramid_debugtoolbar`` line, the ``#``
a54e4c 504 *must* be in the first column.  If you put it anywhere else, and then attempt
SP 505 to restart the application, you'll receive an error that ends something like
506 this:
d21ba4 507
CM 508 .. code-block:: text
509
510    ImportError: No module named #pyramid_debugtoolbar
511
8c56ae 512 .. index::
CM 513    single: project structure
514
0bc787 515 The Project Structure
CM 516 ---------------------
517
e1b26e 518 The ``pyramid-cookiecutter-starter`` cookiecutter generated a :term:`project` (named ``myproject``),
cfb2b5 519 which contains a Python :term:`package`.  The package is *also* named
e1b26e 520 ``myproject``; the cookiecutter generates a project which
SP 521 contains a package that shares its name.
0bc787 522
e1b26e 523 All :app:`Pyramid` ``cookiecutter``-generated projects share a similar structure.
SP 524 The ``myproject`` project we've generated has the following directory structure:
5d22ee 525
BL 526 .. code-block:: text
0bc787 527
e1b26e 528    myproject/
SP 529    â”œâ”€â”€ .coveragerc
530    â”œâ”€â”€ CHANGES.txt
531    â”œâ”€â”€ MANIFEST.in
532    â”œâ”€â”€ myproject
533    â”‚   â”œâ”€â”€ __init__.py
534    â”‚   â”œâ”€â”€ static
535    â”‚   â”‚   â”œâ”€â”€ pyramid-16x16.png
536    â”‚   â”‚   â”œâ”€â”€ pyramid.png
537    â”‚   â”‚   â””── theme.css
538    â”‚   â”œâ”€â”€ templates
539    â”‚   â”‚   â”œâ”€â”€ layout.jinja2
540    â”‚   â”‚   â””── mytemplate.jinja2
541    â”‚   â”œâ”€â”€ tests.py
542    â”‚   â””── views.py
543    â”œâ”€â”€ README.txt
544    â”œâ”€â”€ development.ini
545    â”œâ”€â”€ production.ini
546    â”œâ”€â”€ pytest.ini
547    â””── setup.py
0bc787 548
e1b26e 549
SP 550 The ``myproject`` :term:`Project`
178623 551 ---------------------------------
0bc787 552
e1b26e 553 The ``myproject`` :term:`project` directory is the distribution and deployment
a54e4c 554 wrapper for your application.  It contains both the ``myproject``
178623 555 :term:`package` representing your application as well as files used to
CM 556 describe, run, and test your application.
0bc787 557
e1b26e 558 #. ``.coveragerc`` configures coverage when running tests.
SP 559
a54e4c 560 #. ``CHANGES.txt`` describes the changes you've made to the application.  It is
e1b26e 561    conventionally written in :term:`reStructuredText` format.
SP 562
563 #. ``MANIFEST.in`` is a :term:`distutils` "manifest" file, naming which files
564    should be included in a source distribution of the package when ``python
565    setup.py sdist`` is run.
0bc787 566
a119be 567 #. ``README.txt`` describes the application in general.  It is conventionally
e1b26e 568    written in :term:`reStructuredText` format.
0bc787 569
a54e4c 570 #. ``development.ini`` is a :term:`PasteDeploy` configuration file that can be
SP 571    used to execute your application during development.
43ab04 572
a54e4c 573 #. ``production.ini`` is a :term:`PasteDeploy` configuration file that can be
SP 574    used to execute your application in a production configuration.
47442f 575
e1b26e 576 #. ``pytest.ini`` is a configuration file for running tests.
1f884e 577
a54e4c 578 #. ``setup.py`` is the file you'll use to test and distribute your application.
SP 579    It is a standard :term:`setuptools` ``setup.py`` file.
1f884e 580
8c56ae 581 .. index::
CM 582    single: PasteDeploy
583    single: ini file
543024 584
e1b26e 585 .. _myproject_ini:
c6e58b 586
9f0269 587 ``development.ini``
CM 588 ~~~~~~~~~~~~~~~~~~~
543024 589
a54e4c 590 The ``development.ini`` file is a :term:`PasteDeploy` configuration file. Its
SP 591 purpose is to specify an application to run when you invoke ``pserve``, as well
592 as the deployment settings provided to that application.
543024 593
9f0269 594 The generated ``development.ini`` file looks like so:
543024 595
e1b26e 596 .. literalinclude:: myproject/development.ini
edf394 597    :language: ini
543024 598    :linenos:
CM 599
9573ac 600 This file contains several sections including ``[app:main]``,
a54e4c 601 ``[server:main]``, and several other sections related to logging configuration.
543024 602
3d338e 603 The ``[app:main]`` section represents configuration for your :app:`Pyramid`
a54e4c 604 application.  The ``use`` setting is the only setting required to be present in
e1b26e 605 the ``[app:main]`` section.  Its default value, ``egg:myproject``, indicates
SP 606 that our myproject project contains the application that should be served. 
a54e4c 607 Other settings added to this section are passed as keyword arguments to the
SP 608 function named ``main`` in our package's ``__init__.py`` module.  You can
609 provide startup-time configuration parameters to your application by adding
610 more settings to this section.
e35dc1 611
058e90 612 .. seealso:: See :ref:`pastedeploy_entry_points` for more information about the
e1b26e 613    meaning of the ``use = egg:myproject`` value in this section.
3d338e 614
CM 615 The ``pyramid.reload_templates`` setting in the ``[app:main]`` section is a
058e90 616 :app:`Pyramid`-specific setting which is passed into the framework.  If it
a54e4c 617 exists, and its value is ``true``, supported template changes will not require
SP 618 an application restart to be detected.  See :ref:`reload_templates_section` for
619 more information.
e35dc1 620
488ea0 621 .. warning:: The ``pyramid.reload_templates`` option should be turned off for
CM 622    production applications, as template rendering is slowed when it is turned
623    on.
7c525f 624
a54e4c 625 The ``pyramid.includes`` setting in the ``[app:main]`` section tells Pyramid to
SP 626 "include" configuration from another package.  In this case, the line
3d338e 627 ``pyramid.includes = pyramid_debugtoolbar`` tells Pyramid to include
c6d9f1 628 configuration from the ``pyramid_debugtoolbar`` package.  This turns on a
058e90 629 debugging panel in development mode which can be opened by clicking on the
SP 630 :app:`Pyramid` logo on the top right of the screen.  Including the debug
631 toolbar will also make it possible to interactively debug exceptions when an
632 error occurs.
c6d9f1 633
a54e4c 634 Various other settings may exist in this section having to do with debugging or
SP 635 influencing runtime behavior of a :app:`Pyramid` application.  See
a3ceb6 636 :ref:`environment_chapter` for more information about these settings.
CM 637
3d338e 638 The name ``main`` in ``[app:main]`` signifies that this is the default
cfb2b5 639 application run by ``pserve`` when it is invoked against this configuration
a54e4c 640 file.  The name ``main`` is a convention used by PasteDeploy signifying that it
SP 641 is the default application.
b65d8e 642
a119be 643 The ``[server:main]`` section of the configuration file configures a WSGI
d4177a 644 server which listens on TCP port 6543.  It is configured to listen on localhost
SP 645 only (``127.0.0.1``).
543024 646
e1b26e 647 .. _myproject_ini_logging:
eb3b27 648
d4177a 649 The sections after ``# logging configuration`` represent Python's standard
SP 650 library :mod:`logging` module configuration for your application.  These
651 sections are passed to the `logging module's config file configuration engine
1cb30e 652 <https://docs.python.org/2/howto/logging.html#configuring-logging>`_ when the
d4177a 653 ``pserve`` or ``pshell`` commands are executed.  The default configuration
a54e4c 654 sends application logging output to the standard error output of your terminal.
SP 655 For more information about logging configuration, see :ref:`logging_chapter`.
f4a804 656
a119be 657 See the :term:`PasteDeploy` documentation for more information about other
CM 658 types of things you can put into this ``.ini`` file, such as other
058e90 659 applications, :term:`middleware`, and alternate :term:`WSGI` server
a119be 660 implementations.
543024 661
6ce1e0 662 .. index::
CM 663    single: production.ini
664
43ab04 665 ``production.ini``
609a99 666 ~~~~~~~~~~~~~~~~~~
43ab04 667
a54e4c 668 The ``production.ini`` file is a :term:`PasteDeploy` configuration file with a
SP 669 purpose much like that of ``development.ini``.  However, it disables the debug
670 toolbar, and filters all log messages except those above the WARN level.  It
671 also turns off template development options such that templates are not
672 automatically reloaded when changed, and turns off all debugging options.  This
673 file is appropriate to use instead of ``development.ini`` when you put your
674 application into production.
f601bd 675
2b65bb 676 It's important to use ``production.ini`` (and *not* ``development.ini``) to
CM 677 benchmark your application and put it into production.  ``development.ini``
678 configures your system with a debug toolbar that helps development, but the
679 inclusion of this toolbar slows down page rendering times by over an order of
a54e4c 680 magnitude.  The debug toolbar is also a potential security risk if you have it
SP 681 configured incorrectly.
2b65bb 682
f601bd 683 .. index::
CM 684    single: MANIFEST.in
685
686 ``MANIFEST.in``
687 ~~~~~~~~~~~~~~~
688
689 The ``MANIFEST.in`` file is a :term:`distutils` configuration file which
690 specifies the non-Python files that should be included when a
691 :term:`distribution` of your Pyramid project is created when you run ``python
692 setup.py sdist``.  Due to the information contained in the default
a54e4c 693 ``MANIFEST.in``, an sdist of your Pyramid project will include ``.txt`` files,
SP 694 ``.ini`` files, ``.rst`` files, graphics files, and template files, as well as
695 ``.py`` files.  See
1cb30e 696 https://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template
SP 697 for more information about the syntax and usage of ``MANIFEST.in``.
43ab04 698
a54e4c 699 Without the presence of a ``MANIFEST.in`` file or without checking your source
SP 700 code into a version control repository, ``setup.py sdist`` places only *Python
701 source files* (files ending with a ``.py`` extension) into tarballs generated
702 by ``python setup.py sdist``.  This means, for example, if your project was not
703 checked into a setuptools-compatible source control system, and your project
704 directory didn't contain a ``MANIFEST.in`` file that told the ``sdist``
705 machinery to include ``*.pt`` files, the ``myproject/templates/mytemplate.pt``
706 file would not be included in the generated tarball.
01815e 707
e1b26e 708 Projects generated by Pyramid cookiecutters include a default ``MANIFEST.in`` file.
a54e4c 709 The ``MANIFEST.in`` file contains declarations which tell it to include files
SP 710 like ``*.pt``, ``*.css`` and ``*.js`` in the generated tarball. If you include
711 files with extensions other than the files named in the project's
712 ``MANIFEST.in`` and you don't make use of a setuptools-compatible version
713 control system, you'll need to edit the ``MANIFEST.in`` file and include the
714 statements necessary to include your new files.  See
1cb30e 715 https://docs.python.org/2/distutils/sourcedist.html#principle for more
SP 716 information about how to do this.
01815e 717
a54e4c 718 You can also delete ``MANIFEST.in`` from your project and rely on a setuptools
SP 719 feature which simply causes all files checked into a version control system to
720 be put into the generated tarball.  To allow this to happen, check all the
721 files that you'd like to be distributed along with your application's Python
722 files into Subversion.  After you do this, when you rerun ``setup.py sdist``,
723 all files checked into the version control system will be included in the
724 tarball.  If you don't use Subversion, and instead use a different version
725 control system, you may need to install a setuptools add-on such as
726 ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly.
01815e 727
8c56ae 728 .. index::
CM 729    single: setup.py
730
543024 731 ``setup.py``
CM 732 ~~~~~~~~~~~~
733
a119be 734 The ``setup.py`` file is a :term:`setuptools` setup file.  It is meant to be
f21b2b 735 used to define requirements for installing dependencies for your package and
SP 736 testing, as well as distributing your application.
5ded35 737
SP 738 .. note::
739
a54e4c 740    ``setup.py`` is the de facto standard which Python developers use to
SP 741    distribute their reusable code.  You can read more about ``setup.py`` files
f21b2b 742    and their usage in the `Python Packaging User Guide
7b1612 743    <https://packaging.python.org/>`_ and `Setuptools documentation
f21b2b 744    <http://pythonhosted.org/setuptools/>`_.
543024 745
CM 746 Our generated ``setup.py`` looks like this:
747
e1b26e 748 .. literalinclude:: myproject/setup.py
5d22ee 749    :language: python
543024 750    :linenos:
CM 751
a119be 752 The ``setup.py`` file calls the setuptools ``setup`` function, which does
f21b2b 753 various things depending on the arguments passed to ``pip`` on the command
a54e4c 754 line.
543024 755
a54e4c 756 Within the arguments to this function call, information about your application
SP 757 is kept.  While it's beyond the scope of this documentation to explain
758 everything about setuptools setup files, we'll provide a whirlwind tour of what
759 exists in this file in this section.
543024 760
a3ceb6 761 Your application's name can be any string; it is specified in the ``name``
CM 762 field.  The version number is specified in the ``version`` value.  A short
a54e4c 763 description is provided in the ``description`` field.  The ``long_description``
f21b2b 764 is conventionally the content of the ``README`` and ``CHANGES`` files appended
1cb30e 765 together. The ``classifiers`` field is a list of `Trove classifiers
SP 766 <https://pypi.python.org/pypi?%3Aaction=list_classifiers>`_ describing your
767 application.  ``author`` and ``author_email`` are text fields which probably
768 don't need any description. ``url`` is a field that should point at your
769 application project's URL (if any). ``packages=find_packages()`` causes all
770 packages within the project to be found when packaging the application.
771 ``include_package_data`` will include non-Python files when the application is
772 packaged if those files are checked into version control. ``zip_safe=False``
773 indicates that this package is not safe to use as a zipped egg; instead it will
774 always unpack as a directory, which is more convenient. ``install_requires``
775 indicates that this package depends on the ``pyramid`` package.
776 ``extras_require`` is a Python dictionary that defines what is required to be
777 installed for running tests. We examined ``entry_points`` in our discussion of
778 the ``development.ini`` file; this file defines the ``main`` entry point that
779 represents our project's application.
543024 780
a54e4c 781 Usually you only need to think about the contents of the ``setup.py`` file when
SP 782 distributing your application to other people, when adding Python package
783 dependencies, or when versioning your application for your own use. For fun,
784 you can try this command now:
543024 785
5d22ee 786 .. code-block:: text
9ec2d6 787
058e90 788    $ $VENV/bin/python setup.py sdist
543024 789
a54e4c 790 This will create a tarball of your application in a ``dist`` subdirectory named
e1b26e 791 ``myproject-0.0.tar.gz``.  You can send this tarball to other people who want
a54e4c 792 to install and use your application.
7534ba 793
8c56ae 794 .. index::
CM 795    single: package
796
178623 797 The ``myproject`` :term:`Package`
CM 798 ---------------------------------
1f884e 799
e1b26e 800 The ``myproject`` :term:`package` lives inside the ``myproject``
178623 801 :term:`project`.  It contains:
1f884e 802
a54e4c 803 #. An ``__init__.py`` file signifies that this is a Python :term:`package`. It
SP 804    also contains code that helps users run the application, including a
f8869c 805    ``main`` function which is used as a entry point for commands such as
CM 806    ``pserve``, ``pshell``, ``pviews``, and others.
1f884e 807
e1b26e 808 #. A ``templates`` directory, which contains :term:`Jinja2` (or other types
a54e4c 809    of) templates.
1f884e 810
a54e4c 811 #. A ``tests.py`` module, which contains unit test code for the application.
1f884e 812
a54e4c 813 #. A ``views.py`` module, which contains view code for the application.
1f884e 814
e1b26e 815 These are purely conventions established by the cookiecutter. :app:`Pyramid`
058e90 816 doesn't insist that you name things in any particular way. However, it's
SP 817 generally a good idea to follow Pyramid standards for naming, so that other
818 Pyramid developers can get up to speed quickly on your code when you need help.
8c56ae 819
CM 820 .. index::
9f0269 821    single: __init__.py
1f884e 822
f601bd 823 .. _init_py:
CM 824
9f0269 825 ``__init__.py``
CM 826 ~~~~~~~~~~~~~~~
1f884e 827
9f0269 828 We need a small Python module that configures our application and which
CM 829 advertises an entry point for use by our :term:`PasteDeploy` ``.ini`` file.
830 This is the file named ``__init__.py``.  The presence of an ``__init__.py``
831 also informs Python that the directory which contains it is a *package*.
1f884e 832
e1b26e 833 .. literalinclude:: myproject/myproject/__init__.py
5d22ee 834    :language: python
1f884e 835    :linenos:
CM 836
a119be 837 #. Line 1 imports the :term:`Configurator` class from :mod:`pyramid.config`
CM 838    that we use later.
1f884e 839
2207ed 840 #. Lines 4-12 define a function named ``main`` that returns a :app:`Pyramid`
f601bd 841    WSGI application.  This function is meant to be called by the
cfb2b5 842    :term:`PasteDeploy` framework as a result of running ``pserve``.
9f0269 843
429029 844    Within this function, application configuration is performed.
9f0269 845
d85569 846    Line 7 creates an instance of a :term:`Configurator`.
9bbaa8 847
e1b26e 848    Line 8 adds support for Jinja2 templating bindings, allowing us to
SP 849    specify renderers with the ``.jinja2`` extension.
2207ed 850
MM 851    Line 9 registers a static view, which will serve up the files from the
a54e4c 852    ``myproject:static`` :term:`asset specification` (the ``static`` directory
SP 853    of the ``myproject`` package).
eff462 854
a54e4c 855    Line 10 adds a :term:`route` to the configuration.  This route is later used
SP 856    by a view in the ``views`` module.
8fe021 857
2207ed 858    Line 11 calls ``config.scan()``, which picks up view registrations declared
8fe021 859    elsewhere in the package (in this case, in the ``views.py`` module).
8595a7 860
2207ed 861    Line 12 returns a :term:`WSGI` application to the caller of the function
f8869c 862    (Pyramid's pserve).
8c56ae 863
6ce1e0 864 .. index::
CM 865    single: views.py
866
0bc787 867 ``views.py``
1f884e 868 ~~~~~~~~~~~~
0bc787 869
a119be 870 Much of the heavy lifting in a :app:`Pyramid` application is done by *view
CM 871 callables*.  A :term:`view callable` is the main tool of a :app:`Pyramid` web
a54e4c 872 application developer; it is a bit of code which accepts a :term:`request` and
SP 873 which returns a :term:`response`.
0bc787 874
e1b26e 875 .. literalinclude:: myproject/myproject/views.py
5d22ee 876    :language: python
1f884e 877    :linenos:
0bc787 878
d85569 879 Lines 4-6 define and register a :term:`view callable` named ``my_view``.  The
a54e4c 880 function named ``my_view`` is decorated with a ``view_config`` decorator (which
SP 881 is processed by the ``config.scan()`` line in our ``__init__.py``). The
882 view_config decorator asserts that this view be found when a :term:`route`
883 named ``home`` is matched.  In our case, because our ``__init__.py`` maps the
884 route named ``home`` to the URL pattern ``/``, this route will match when a
885 visitor visits the root URL.  The view_config decorator also names a
886 ``renderer``, which in this case is a template that will be used to render the
887 result of the view callable.  This particular view declaration points at
888 ``templates/mytemplate.pt``, which is an :term:`asset specification` that
889 specifies the ``mytemplate.pt`` file within the ``templates`` directory of the
890 ``myproject`` package.  The asset specification could have also been specified
891 as ``myproject:templates/mytemplate.pt``; the leading package name and colon is
e1b26e 892 optional.  The template file pointed to is a :term:`Jinja2` template
SP 893 file (``templates/my_template.jinja2``).
1f884e 894
a119be 895 This view callable function is handed a single piece of information: the
a54e4c 896 :term:`request`.  The *request* is an instance of the :term:`WebOb` ``Request``
SP 897 class representing the browser's request to our server.
1f884e 898
47e13e 899 This view is configured to invoke a :term:`renderer` on a template.  The
f24ac4 900 dictionary the view returns (on line 6) provides the value the renderer
a54e4c 901 substitutes into the template when generating HTML.  The renderer then returns
SP 902 the HTML in a :term:`response`.
9bbaa8 903
5276ce 904 .. note:: Dictionaries provide values to :term:`template`\s.
KOP 905
e1b26e 906 .. note:: When the application is run with the cookiecutter's :ref:`default
SP 907    development.ini <myproject_ini>` configuration, :ref:`logging is set up
908    <myproject_ini_logging>` to aid debugging.  If an exception is raised,
6b2e8e 909    uncaught tracebacks are displayed after the startup messages on :ref:`the
SP 910    console running the server <running_the_project_application>`. Also
a54e4c 911    ``print()`` statements may be inserted into the application for debugging to
SP 912    send output to this console.
eb3b27 913
56170f 914 .. note:: ``development.ini`` has a setting that controls how templates are
5ded35 915    reloaded, ``pyramid.reload_templates``.
56170f 916
e1b26e 917    - When set to ``True`` (as in the cookiecutter ``development.ini``), changed
5ded35 918      templates automatically reload without a server restart.  This is
SP 919      convenient while developing, but slows template rendering speed.
920
a54e4c 921    - When set to ``False`` (the default value), changing templates requires a
SP 922      server restart to reload them.  Production applications should use
56170f 923      ``pyramid.reload_templates = False``.
8c56ae 924
2033ee 925 .. seealso::
SP 926
a54e4c 927     See also :ref:`views_which_use_a_renderer` for more information about how
SP 928     views, renderers, and templates relate and cooperate.
5ded35 929
2033ee 930 .. seealso::
5ded35 931
2033ee 932     Pyramid can also dynamically reload changed Python files.  See also
SP 933     :ref:`reloading_code`.
934
935 .. seealso::
936
937     See also the :ref:`debug_toolbar`, which provides interactive access to
938     your application's internals and, should an exception occur, allows
939     interactive access to traceback execution stack frames from the Python
940     interpreter.
5ded35 941
6ce1e0 942 .. index::
CM 943    single: static directory
944
fb3003 945 ``static``
a5ffd6 946 ~~~~~~~~~~
fb3003 947
e1b26e 948 This directory contains static assets which support the ``layout.jinja2``
a5ffd6 949 template.  It includes CSS and images.
fb3003 950
e1b26e 951
SP 952 ``templates/layout.jinja2``
1f884e 953 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
CM 954
e1b26e 955 This is the base layout content. It contains a single marker for content block. Other templates inherit its content, providing layout for the web application. Its contents are too long to show here, but here is an excerpt:
SP 956
957 .. literalinclude:: myproject/myproject/templates/layout.jinja2
958    :language: jinja
959    :lines: 34-38
960    :lineno-match:
961
962
963 ``templates/mytemplate.jinja2``
964 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
965
966 This is the content :term:`Jinja2` template that exists in the project.  It is referenced by the call to ``@view_config`` as the ``renderer``
a54e4c 967 of the ``my_view`` view callable in the ``views.py`` file.  See
e1b26e 968 :ref:`views_which_use_a_renderer` for more information about renderers. It inherits ("extends") the HTML provided by ``layout.jinja2``, replacing the content block with its own content.
SP 969
970 .. literalinclude:: myproject/myproject/templates/mytemplate.jinja2
971    :language: jinja
972    :linenos:
eff462 973
a119be 974 Templates are accessed and used by view configurations and sometimes by view
CM 975 functions themselves.  See :ref:`templates_used_directly` and
9ec2d6 976 :ref:`templates_used_as_renderers`.
e1b26e 977
8c56ae 978
f52d59 979 .. index::
CM 980    single: tests.py
981
1f884e 982 ``tests.py``
CM 983 ~~~~~~~~~~~~
984
e1b26e 985 The ``tests.py`` module includes tests for your application.
1f884e 986
e1b26e 987 .. literalinclude:: myproject/myproject/tests.py
5d22ee 988    :language: python
1f884e 989    :linenos:
CM 990
f21b2b 991 This sample ``tests.py`` file has one unit test and one functional test defined
ea252c 992 within it. These tests are executed when you run ``py.test -q``. You may add
SP 993 more tests here as you build your application. You are not required to write
994 tests to use :app:`Pyramid`. This file is simply provided for convenience and
995 example.
0bc787 996
6ee49a 997 See :ref:`testing_chapter` for more information about writing :app:`Pyramid`
CM 998 unit tests.
aa3306 999
6ce1e0 1000 .. index::
CM 1001    pair: modifying; package structure
1002
fd9c5b 1003 .. _modifying_package_structure:
CM 1004
aa3306 1005 Modifying Package Structure
609a99 1006 ---------------------------
aa3306 1007
CM 1008 It is best practice for your application's code layout to not stray too much
e1b26e 1009 from accepted Pyramid cookiecutter defaults.  If you refrain from changing things
a54e4c 1010 very much, other Pyramid coders will be able to more quickly understand your
e1b26e 1011 application.  However, the code layout choices made for you by a cookiecutter are
a54e4c 1012 in no way magical or required.  Despite the choices made for you by any
e1b26e 1013 cookiecutter, you can decide to lay your code out any way you see fit.
aa3306 1014
CM 1015 For example, the configuration method named
d7f259 1016 :meth:`~pyramid.config.Configurator.add_view` requires you to pass a
aa3306 1017 :term:`dotted Python name` or a direct object reference as the class or
e1b26e 1018 function to be used as a view.  By default, the ``starter`` cookiecutter would have
a54e4c 1019 you add view functions to the ``views.py`` module in your package. However, you
SP 1020 might be more comfortable creating a ``views`` *directory*, and adding a single
1021 file for each view.
aa3306 1022
CM 1023 If your project package name was ``myproject`` and you wanted to arrange all
1024 your views in a Python subpackage within the ``myproject`` :term:`package`
058e90 1025 named ``views`` instead of within a single ``views.py`` file, you might do the
SP 1026 following.
aa3306 1027
a54e4c 1028 - Create a ``views`` directory inside your ``myproject`` package directory (the
SP 1029   same directory which holds ``views.py``).
aa3306 1030
bc3de3 1031 - Create a file within the new ``views`` directory named ``__init__.py``.  (It
KOP 1032   can be empty.  This just tells Python that the ``views`` directory is a
1033   *package*.)
aa3306 1034
716bdf 1035 - *Move* the content from the existing ``views.py`` file to a file inside the
SP 1036   new ``views`` directory named, say, ``blog.py``.  Because the ``templates``
1037   directory remains in the ``myproject`` package, the template :term:`asset
ab2fed 1038   specification` values in ``blog.py`` must now be fully qualified with the
ac7d17 1039   project's package name (``myproject:templates/blog.pt``).
aa3306 1040
a54e4c 1041 You can then continue to add view callable functions to the ``blog.py`` module,
SP 1042 but you can also add other ``.py`` files which contain view callable functions
1043 to the ``views`` directory.  As long as you use the ``@view_config`` directive
1044 to register views in conjunction with ``config.scan()``, they will be picked up
1045 automatically when the application is restarted.
aa3306 1046
ae4c57 1047 Using the Interactive Shell
CM 1048 ---------------------------
1049
926fbe 1050 It is possible to use the ``pshell`` command to load a Python interpreter
a54e4c 1051 prompt with a similar configuration as would be loaded if you were running your
SP 1052 Pyramid application via ``pserve``.  This can be a useful debugging tool. See
1053 :ref:`interactive_shell` for more details.
ae4c57 1054
47eaa1 1055 .. _what_is_this_pserve_thing:
PE 1056
c3a36b 1057 What Is This ``pserve`` Thing
CM 1058 -----------------------------
d83b39 1059
e1b26e 1060 The code generated by a :app:`Pyramid` cookiecutter assumes that you will be using
058e90 1061 the ``pserve`` command to start your application while you do development.
SP 1062 ``pserve`` is a command that reads a :term:`PasteDeploy` ``.ini`` file (e.g.,
1063 ``development.ini``), and configures a server to serve a :app:`Pyramid`
1064 application based on the data in the file.
ef9767 1065
8fe021 1066 ``pserve`` is by no means the only way to start up and serve a :app:`Pyramid`
CM 1067 application.  As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be
1068 invoked at all to run a :app:`Pyramid` application.  The use of ``pserve`` to
058e90 1069 run a :app:`Pyramid` application is purely conventional based on the output of
e1b26e 1070 its cookiecutter.  But we strongly recommend using ``pserve`` while developing
058e90 1071 your application because many other convenience introspection commands (such as
SP 1072 ``pviews``, ``prequest``, ``proutes``, and others) are also implemented in
1073 terms of configuration availability of this ``.ini`` file format.  It also
b7736b 1074 configures Pyramid logging and provides the ``--reload`` switch for convenient
058e90 1075 restarting of the server when code changes.
aa3306 1076
c3a36b 1077 .. _alternate_wsgi_server:
2c9f3c 1078
c3a36b 1079 Using an Alternate WSGI Server
CM 1080 ------------------------------
1081
e1b26e 1082 Pyramid cookiecutters generate projects which use the :term:`Waitress` WSGI server.
a54e4c 1083 Waitress is a server that is suited for development and light production
SP 1084 usage.  It's not the fastest nor the most featureful WSGI server. Instead, its
1085 main feature is that it works on all platforms that Pyramid needs to run on,
1086 making it a good choice as a default server from the perspective of Pyramid's
1087 developers.
c3a36b 1088
CM 1089 Any WSGI server is capable of running a :app:`Pyramid` application.  But we
a54e4c 1090 suggest you stick with the default server for development, and that you wait to
SP 1091 investigate other server options until you're ready to deploy your application
1092 to production.  Unless for some reason you need to develop on a non-local
1093 system, investigating alternate server options is usually a distraction until
1094 you're ready to deploy.  But we recommend developing using the default
1095 configuration on a local system that you have complete control over; it will
1096 provide the best development experience.
c3a36b 1097
CM 1098 One popular production alternative to the default Waitress server is
ce8894 1099 :term:`mod_wsgi`. You can use ``mod_wsgi`` to serve your :app:`Pyramid` application
a54e4c 1100 using the Apache web server rather than any "pure-Python" server like Waitress.
SP 1101 It is fast and featureful.  See :ref:`modwsgi_tutorial` for details.
c3a36b 1102
CM 1103 Another good production alternative is :term:`Green Unicorn` (aka
a54e4c 1104 ``gunicorn``).  It's faster than Waitress and slightly easier to configure than
ce8894 1105 ``mod_wsgi``, although it depends, in its default configuration, on having a
a54e4c 1106 buffering HTTP proxy in front of it.  It does not, as of this writing, work on
SP 1107 Windows.
1644ef 1108
MM 1109 Automatically Reloading Your Code
1110 ---------------------------------
1111
1112 During development, it can be really useful to automatically have the
1113 webserver restart when you make changes. ``pserve`` has a ``--reload`` switch
1114 to enable this. It uses the
19d341 1115 `hupper <https://docs.pylonsproject.org/projects/hupper/en/latest/>`_ package
1644ef 1116 to enable this behavior. When your code crashes, ``hupper`` will wait for
MM 1117 another change or the ``SIGHUP`` signal before restarting again.
1118
1119 inotify support
1120 ~~~~~~~~~~~~~~~
1121
0aa967 1122 By default ``hupper`` will poll the filesystem for changes to all Python
1644ef 1123 code. This can be pretty inefficient in larger projects. To be nicer to your
MM 1124 hard drive, you should install the
f8e8ab 1125 `watchdog <http://pythonhosted.org/watchdog/>`_ package in development.
1644ef 1126 ``hupper`` will automatically use ``watchdog`` to more efficiently poll the
MM 1127 filesystem.
3f1309 1128
MM 1129 Monitoring Custom Files
1130 ~~~~~~~~~~~~~~~~~~~~~~~
1131
1132 By default, ``pserve --reload`` will monitor all imported Python code
1133 (everything in ``sys.modules``) as well as the config file passed to
0aa967 1134 ``pserve`` (e.g., ``development.ini``). You can instruct ``pserve`` to watch
3f1309 1135 other files for changes as well by defining a ``[pserve]`` section in your
MM 1136 configuration file. For example, let's say your application loads the
1137 ``favicon.ico`` file at startup and stores it in memory to efficiently
0aa967 1138 serve it many times. When you change it, you want ``pserve`` to restart:
3f1309 1139
MM 1140 .. code-block:: ini
1141
1142     [pserve]
1143     watch_files =
1144         myapp/static/favicon.ico
1145
ff0da7 1146 Paths may be absolute or relative to the configuration file. They may also
0aa967 1147 be an :term:`asset specification`. These paths are passed to ``hupper``, which
ff0da7 1148 has some basic support for globbing. Acceptable glob patterns depend on the
MM 1149 version of Python being used.