| commit | author | age | ||
| 3d338e | 1 | .. _paste_chapter: |
| CM | 2 | |
| cfb2b5 | 3 | PasteDeploy Configuration Files |
| CM | 4 | =============================== |
| 3d338e | 5 | |
| 0a11d0 | 6 | Packages generated via a :term:`cookiecutter` make use of a system created by Ian |
| cfb2b5 | 7 | Bicking named :term:`PasteDeploy`. PasteDeploy defines a way to declare |
| CM | 8 | :term:`WSGI` application configuration in an ``.ini`` file. |
| 3d338e | 9 | |
| fc3f6b | 10 | Pyramid uses this configuration file format as input to its :term:`WSGI` server |
| SP | 11 | runner ``pserve``, as well as other commands such as ``pviews``, ``pshell``, |
| 12 | ``proutes``, and ``ptweens``. | |
| 3d338e | 13 | |
| cfb2b5 | 14 | PasteDeploy is not a particularly integral part of Pyramid. It's possible to |
| fc3f6b | 15 | create a Pyramid application which does not use PasteDeploy at all. We show a |
| SP | 16 | Pyramid application that doesn't use PasteDeploy in :ref:`firstapp_chapter`. |
| 0a11d0 | 17 | However, all Pyramid cookiecutters render PasteDeploy configuration files, to |
| fc3f6b | 18 | provide new developers with a standardized way of setting deployment values, |
| SP | 19 | and to provide new users with a standardized way of starting, stopping, and |
| 20 | debugging an application. | |
| 3d338e | 21 | |
| fc3f6b | 22 | This chapter is not a replacement for documentation about PasteDeploy; it only |
| SP | 23 | contextualizes the use of PasteDeploy within Pyramid. For detailed |
| 8a212d | 24 | documentation, see https://pastedeploy.readthedocs.io/en/latest/. |
| 3d338e | 25 | |
| CM | 26 | PasteDeploy |
| 27 | ----------- | |
| 28 | ||
| fc3f6b | 29 | :term:`PasteDeploy` is the system that Pyramid uses to allow :term:`deployment |
| SP | 30 | settings` to be specified using an ``.ini`` configuration file format. It also |
| 31 | allows the ``pserve`` command to work. Its configuration format provides a | |
| 32 | convenient place to define application :term:`deployment settings` and WSGI | |
| 33 | server settings, and its server runner allows you to stop and start a Pyramid | |
| 34 | application easily. | |
| 3d338e | 35 | |
| CM | 36 | .. _pastedeploy_entry_points: |
| 37 | ||
| 38 | Entry Points and PasteDeploy ``.ini`` Files | |
| fc3f6b | 39 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3d338e | 40 | |
| CM | 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 = | |
| fb77c9 | 43 | egg:myproject`` line in the ``[app:main]`` section. We breezed over it because |
| fc3f6b | 44 | it's pretty confusing and "too much information" for an introduction to the |
| SP | 45 | system. We'll try to give it a bit of attention here. Let's see the config |
| 46 | file again: | |
| 3d338e | 47 | |
| fb77c9 | 48 | .. literalinclude:: myproject/development.ini |
| 3d338e | 49 | :language: ini |
| CM | 50 | :linenos: |
| 51 | ||
| fb77c9 | 52 | The line in ``[app:main]`` above that says ``use = egg:myproject`` is actually |
| SP | 53 | shorthand for a longer spelling: ``use = egg:myproject#main``. The ``#main`` |
| fc3f6b | 54 | part is omitted for brevity, as ``#main`` is a default defined by PasteDeploy. |
| fb77c9 | 55 | ``egg:myproject#main`` is a string which has meaning to PasteDeploy. It points |
| fc3f6b | 56 | at a :term:`setuptools` :term:`entry point` named ``main`` defined in the |
| fb77c9 | 57 | ``myproject`` project. |
| 3d338e | 58 | |
| CM | 59 | Take a look at the generated ``setup.py`` file for this project. |
| 60 | ||
| fb77c9 | 61 | .. literalinclude:: myproject/setup.py |
| 3d338e | 62 | :language: python |
| CM | 63 | :linenos: |
| 64 | ||
| fc3f6b | 65 | Note that ``entry_points`` is assigned a string which looks a lot like an |
| SP | 66 | ``.ini`` file. This string representation of an ``.ini`` file has a section |
| 67 | named ``[paste.app_factory]``. Within this section, there is a key named | |
| 68 | ``main`` (the entry point name) which has a value ``myproject:main``. The | |
| fb77c9 | 69 | *key* ``main`` is what our ``egg:myproject#main`` value of the ``use`` section |
| fc3f6b | 70 | in our config file is pointing at, although it is actually shortened to |
| fb77c9 | 71 | ``egg:myproject`` there. The value represents a :term:`dotted Python name` |
| fc3f6b | 72 | path, which refers to a callable in our ``myproject`` package's ``__init__.py`` |
| SP | 73 | module. |
| 3d338e | 74 | |
| fb77c9 | 75 | The ``egg:`` prefix in ``egg:myproject`` indicates that this is an entry point |
| fc3f6b | 76 | *URI* specifier, where the "scheme" is "egg". An "egg" is created when you run |
| SP | 77 | ``setup.py install`` or ``setup.py develop`` within your project. |
| 3d338e | 78 | |
| f8869c | 79 | In English, this entry point can thus be referred to as a "PasteDeploy |
| fb77c9 | 80 | application factory in the ``myproject`` project which has the entry point |
| f8869c | 81 | named ``main`` where the entry point refers to a ``main`` function in the |
| CM | 82 | ``mypackage`` module". Indeed, if you open up the ``__init__.py`` module |
| 0a11d0 | 83 | generated within any cookiecutter-generated package, you'll see a ``main`` |
| f8869c | 84 | function. This is the function called by :term:`PasteDeploy` when the |
| CM | 85 | ``pserve`` command is invoked against our application. It accepts a global |
| 86 | configuration object and *returns* an instance of our application. | |
| 3d338e | 87 | |
| 62ea1b | 88 | .. _defaults_section_of_pastedeploy_file: |
| TL | 89 | |
| daa096 | 90 | ``[DEFAULT]`` Section of a PasteDeploy ``.ini`` File |
| fc3f6b | 91 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 3d338e | 92 | |
| fc3f6b | 93 | You can add a ``[DEFAULT]`` section to your PasteDeploy ``.ini`` file. Such a |
| SP | 94 | section should consist of global parameters that are shared by all the |
| 95 | applications, servers, and :term:`middleware` defined within the configuration | |
| 3d338e | 96 | file. The values in a ``[DEFAULT]`` section will be passed to your |
| fc3f6b | 97 | application's ``main`` function as ``global_config`` (see the reference to the |
| SP | 98 | ``main`` function in :ref:`init_py`). |
