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 |
|
f1dbf2
|
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 |
|
78828f
|
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`` |
78828f
|
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 |
|
813b7c
|
88 |
$ cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.8-branch |
54f2bb
|
89 |
|
e1b26e
|
90 |
If prompted for the first item, accept the default ``yes`` by hitting return. |
SP |
91 |
|
51a39b
|
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 |
eb3531
|
97 |
repo_name [myproject]: myproject |
51a39b
|
98 |
Select template_language: |
SP |
99 |
1 - jinja2 |
|
100 |
2 - chameleon |
78828f
|
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 |
6d8c4d
|
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 |
6d8c4d
|
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 |
SP |
743 |
<https://packaging.python.org/en/latest/>`_ and `Setuptools documentation |
|
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 |
3d4023
|
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 |
3d4023
|
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 |
4e96ae
|
1115 |
`hupper <http://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 |
|
a229f9
|
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 |
343fff
|
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 |
a229f9
|
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 |
a229f9
|
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 |
a229f9
|
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. |