Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 101 lines (78 sloc) 4.738 kb
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
1 .. _paste_chapter:
2
cfb2b55 @mcdonc remove all reference to the paster command-line utility
mcdonc authored
3 PasteDeploy Configuration Files
4 ===============================
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
5
6 Packages generated via a :term:`scaffold` make use of a system created by Ian
cfb2b55 @mcdonc remove all reference to the paster command-line utility
mcdonc authored
7 Bicking named :term:`PasteDeploy`. PasteDeploy defines a way to declare
8 :term:`WSGI` application configuration in an ``.ini`` file.
9
10 Pyramid uses this configuration file format in input to its :term:`WSGI`
11 server runner ``pserve``, as well as other commands such as ``pviews``,
12 ``pshell``, ``proutes``, and ``ptweens``.
13
14 PasteDeploy is not a particularly integral part of Pyramid. It's possible to
15 create a Pyramid application which does not use PasteDeploy at all. We show
16 a Pyramid application that doesn't use PasteDeploy in
17 :ref:`firstapp_chapter`. However, all Pyramid scaffolds render PasteDeploy
18 configuration files, to provide new developers with a standardized way of
19 setting deployment values, and to provide new users with a standardized way
253df13 @mcdonc whitespace
mcdonc authored
20 of starting, stopping, and debugging an application.
cfb2b55 @mcdonc remove all reference to the paster command-line utility
mcdonc authored
21
22 This chapter is not a replacement for documentation about PasteDeploy; it
f8869cb @mcdonc remove stray references to Paste
mcdonc authored
23 only contextualizes the use of PasteDeploy within Pyramid. For detailed
6ad5fb2 @tshepang fix links
tshepang authored
24 documentation, see http://pythonpaste.org/deploy/.
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
25
26 PasteDeploy
27 -----------
28
29 :term:`PasteDeploy` is the system that Pyramid uses to allow
30 :term:`deployment settings` to be spelled using an ``.ini`` configuration
cfb2b55 @mcdonc remove all reference to the paster command-line utility
mcdonc authored
31 file format. It also allows the ``pserve`` command to work. Its
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
32 configuration format provides a convenient place to define application
33 :term:`deployment settings` and WSGI server settings, and its server runner
34 allows you to stop and start a Pyramid application easily.
35
36 .. _pastedeploy_entry_points:
37
38 Entry Points and PasteDeploy ``.ini`` Files
39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40
41 In the :ref:`project_narr` chapter, we breezed over the meaning of a
42 configuration line in the ``deployment.ini`` file. This was the ``use =
43 egg:MyProject`` line in the ``[app:main]`` section. We breezed over it
44 because it's pretty confusing and "too much information" for an introduction
45 to the system. We'll try to give it a bit of attention here. Let's see the
46 config file again:
47
48 .. literalinclude:: MyProject/development.ini
49 :language: ini
50 :linenos:
51
52 The line in ``[app:main]`` above that says ``use = egg:MyProject`` is
53 actually shorthand for a longer spelling: ``use = egg:MyProject#main``. The
54 ``#main`` part is omitted for brevity, as ``#main`` is a default defined by
55 PasteDeploy. ``egg:MyProject#main`` is a string which has meaning to
56 PasteDeploy. It points at a :term:`setuptools` :term:`entry point` named
57 ``main`` defined in the ``MyProject`` project.
58
59 Take a look at the generated ``setup.py`` file for this project.
60
61 .. literalinclude:: MyProject/setup.py
62 :language: python
63 :linenos:
64
c4c182b @tshepang be more concise, and simplify
tshepang authored
65 Note that ``entry_points`` is assigned a string which
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
66 looks a lot like an ``.ini`` file. This string representation of an ``.ini``
67 file has a section named ``[paste.app_factory]``. Within this section, there
68 is a key named ``main`` (the entry point name) which has a value
69 ``myproject:main``. The *key* ``main`` is what our ``egg:MyProject#main``
70 value of the ``use`` section in our config file is pointing at, although it
71 is actually shortened to ``egg:MyProject`` there. The value represents a
72 :term:`dotted Python name` path, which refers to a callable in our
73 ``myproject`` package's ``__init__.py`` module.
74
75 The ``egg:`` prefix in ``egg:MyProject`` indicates that this is an entry
76 point *URI* specifier, where the "scheme" is "egg". An "egg" is created when
77 you run ``setup.py install`` or ``setup.py develop`` within your project.
78
f8869cb @mcdonc remove stray references to Paste
mcdonc authored
79 In English, this entry point can thus be referred to as a "PasteDeploy
80 application factory in the ``MyProject`` project which has the entry point
81 named ``main`` where the entry point refers to a ``main`` function in the
82 ``mypackage`` module". Indeed, if you open up the ``__init__.py`` module
83 generated within any scaffold-generated package, you'll see a ``main``
84 function. This is the function called by :term:`PasteDeploy` when the
85 ``pserve`` command is invoked against our application. It accepts a global
86 configuration object and *returns* an instance of our application.
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
87
62ea1b6 @tshepang fix link
tshepang authored
88 .. _defaults_section_of_pastedeploy_file:
89
daa0964 @mmerickel easiest commit ever
mmerickel authored
90 ``[DEFAULT]`` Section of a PasteDeploy ``.ini`` File
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
93 You can add a ``[DEFAULT]`` section to your PasteDeploy ``.ini`` file. Such
94 a section should consists of global parameters that are shared by all the
95 applications, servers and :term:`middleware` defined within the configuration
96 file. The values in a ``[DEFAULT]`` section will be passed to your
97 application's ``main`` function as ``global_config`` (see the reference to
98 the ``main`` function in :ref:`init_py`).
99
100
Something went wrong with that request. Please try again.