PasteDeploy Configuration Files

Packages generated via a cookiecutter make use of a system created by Ian Bicking named PasteDeploy. PasteDeploy defines a way to declare WSGI application configuration in an .ini file.

Pyramid uses this configuration file format as input to its WSGI server runner pserve, as well as other commands such as pviews, pshell, proutes, and ptweens.

PasteDeploy is not a particularly integral part of Pyramid. It's possible to create a Pyramid application which does not use PasteDeploy at all. We show a Pyramid application that doesn't use PasteDeploy in Creating Your First Pyramid Application. However, the Pyramid cookiecutter renders PasteDeploy configuration files, to provide new developers with a standardized way of setting deployment values, and to provide new users with a standardized way of starting, stopping, and debugging an application.

This chapter is not a replacement for documentation about PasteDeploy; it only contextualizes the use of PasteDeploy within Pyramid. For detailed documentation, see https://docs.pylonsproject.org/projects/pastedeploy/en/latest/.

PasteDeploy

plaster is the system that Pyramid uses to load settings from configuration files. The most common format for these files is an .ini format structured in a way defined by PasteDeploy. The format supports mechanisms to define WSGI app deployment settings, WSGI server settings and logging. This allows the pserve command to work, allowing you to stop and start a Pyramid application easily.

Entry Points and PasteDeploy .ini Files

In the Creating a Pyramid Project chapter, we breezed over the meaning of a configuration line in the deployment.ini file. This was the use = egg:myproject line in the [app:main] section. We breezed over it because it's pretty confusing and "too much information" for an introduction to the system. We'll try to give it a bit of attention here. Let's see the config file again:

 1###
 2# app configuration
 3# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
 4###
 5
 6[app:main]
 7use = egg:myproject
 8
 9pyramid.reload_templates = true
10pyramid.debug_authorization = false
11pyramid.debug_notfound = false
12pyramid.debug_routematch = false
13pyramid.default_locale_name = en
14pyramid.includes =
15    pyramid_debugtoolbar
16
17# By default, the toolbar only appears for clients from IP addresses
18# '127.0.0.1' and '::1'.
19# debugtoolbar.hosts = 127.0.0.1 ::1
20
21###
22# wsgi server configuration
23###
24
25[server:main]
26use = egg:waitress#main
27listen = localhost:6543
28
29###
30# logging configuration
31# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
32###
33
34[loggers]
35keys = root, myproject
36
37[handlers]
38keys = console
39
40[formatters]
41keys = generic
42
43[logger_root]
44level = INFO
45handlers = console
46
47[logger_myproject]
48level = DEBUG
49handlers =
50qualname = myproject
51
52[handler_console]
53class = StreamHandler
54args = (sys.stderr,)
55level = NOTSET
56formatter = generic
57
58[formatter_generic]
59format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s

The line in [app:main] above that says use = egg:myproject is actually shorthand for a longer spelling: use = egg:myproject#main. The #main part is omitted for brevity, as #main is a default defined by PasteDeploy. egg:myproject#main is a string which has meaning to PasteDeploy. It points at a Setuptools entry point named main defined in the myproject project.

Take a look at the generated setup.py file for this project.

 1import os
 2
 3from setuptools import setup, find_packages
 4
 5here = os.path.abspath(os.path.dirname(__file__))
 6with open(os.path.join(here, 'README.txt')) as f:
 7    README = f.read()
 8with open(os.path.join(here, 'CHANGES.txt')) as f:
 9    CHANGES = f.read()
10
11requires = [
12    'plaster_pastedeploy',
13    'pyramid',
14    'pyramid_jinja2',
15    'pyramid_debugtoolbar',
16    'waitress',
17]
18
19tests_require = [
20    'WebTest >= 1.3.1',  # py3 compat
21    'pytest >= 3.7.4',
22    'pytest-cov',
23]
24
25setup(
26    name='myproject',
27    version='0.0',
28    description='MyProject',
29    long_description=README + '\n\n' + CHANGES,
30    classifiers=[
31        'Programming Language :: Python',
32        'Framework :: Pyramid',
33        'Topic :: Internet :: WWW/HTTP',
34        'Topic :: Internet :: WWW/HTTP :: WSGI :: Application',
35    ],
36    author='',
37    author_email='',
38    url='',
39    keywords='web pyramid pylons',
40    packages=find_packages(),
41    include_package_data=True,
42    zip_safe=False,
43    extras_require={
44        'testing': tests_require,
45    },
46    install_requires=requires,
47    entry_points={
48        'paste.app_factory': [
49            'main = myproject:main',
50        ],
51    },
52)

Note that entry_points is assigned a string which looks a lot like an .ini file. This string representation of an .ini file has a section named [paste.app_factory]. Within this section, there is a key named main (the entry point name) which has a value myproject:main. The key main is what our egg:myproject#main value of the use section in our config file is pointing at, although it is actually shortened to egg:myproject there. The value represents a dotted Python name path, which refers to a callable in our myproject package's __init__.py module.

The egg: prefix in egg:myproject indicates that this is an entry point URI specifier, where the "scheme" is "egg". An "egg" is created when you run setup.py install or setup.py develop within your project.

In English, this entry point can thus be referred to as a "PasteDeploy application factory in the myproject project which has the entry point named main where the entry point refers to a main function in the mypackage module". Indeed, if you open up the __init__.py module generated within the cookiecutter-generated package, you'll see a main function. This is the function called by PasteDeploy when the pserve command is invoked against our application. It accepts a global configuration object and returns an instance of our application.

[DEFAULT] Section of a PasteDeploy .ini File

You can add a [DEFAULT] section to your PasteDeploy .ini file. Such a section should consist of global parameters that are shared by all the applications, servers, and middleware defined within the configuration file. The values in a [DEFAULT] section will be passed to your application's main function as global_config (see the reference to the main function in __init__.py).

Alternative Configuration File Formats

It is possible to use different file formats with Pyramid if you do not like PasteDeploy. Under the hood all command-line scripts such as pserve and pshell pass the config_uri (e.g. development.ini or production.ini) to the plaster library which performs a lookup for an appropriate parser. For .ini files it uses PasteDeploy but you can register your own configuration formats that plaster will find instead.