diff options
| -rw-r--r-- | docs/narr/environment.rst | 344 |
1 files changed, 155 insertions, 189 deletions
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 0b06fb80b..743266d2c 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -21,39 +21,36 @@ Environment Variables and ``.ini`` File Settings ================================================ -:app:`Pyramid` behavior can be configured through a combination of -operating system environment variables and ``.ini`` configuration file -application section settings. The meaning of the environment -variables and the configuration file settings overlap. - -.. note:: Where a configuration file setting exists with the same - meaning as an environment variable, and both are present at - application startup time, the environment variable setting - takes precedence. - -The term "configuration file setting name" refers to a key in the -``.ini`` configuration for your application. The configuration file -setting names documented in this chapter are reserved for -:app:`Pyramid` use. You should not use them to indicate -application-specific configuration settings. +:app:`Pyramid` behavior can be configured through a combination of operating +system environment variables and ``.ini`` configuration file application +section settings. The meaning of the environment variables and the +configuration file settings overlap. + +.. note:: + Where a configuration file setting exists with the same meaning as an + environment variable, and both are present at application startup time, the + environment variable setting takes precedence. + +The term "configuration file setting name" refers to a key in the ``.ini`` +configuration for your application. The configuration file setting names +documented in this chapter are reserved for :app:`Pyramid` use. You should not +use them to indicate application-specific configuration settings. Reloading Templates ------------------- -When this value is true, templates are automatically reloaded whenever -they are modified without restarting the application, so you can see -changes to templates take effect immediately during development. This -flag is meaningful to Chameleon and Mako templates, as well as most -third-party template rendering extensions. - -+---------------------------------+--------------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+================================+ -| ``PYRAMID_RELOAD_TEMPLATES`` | ``pyramid.reload_templates`` | -| | or ``reload_templates`` | -| | | -| | | -+---------------------------------+--------------------------------+ +When this value is true, templates are automatically reloaded whenever they are +modified without restarting the application, so you can see changes to +templates take effect immediately during development. This flag is meaningful +to Chameleon and Mako templates, as well as most third-party template rendering +extensions. + ++-------------------------------+--------------------------------+ +| Environment Variable Name | Config File Setting Name | ++===============================+================================+ +| ``PYRAMID_RELOAD_TEMPLATES`` | ``pyramid.reload_templates`` | +| | or ``reload_templates`` | ++-------------------------------+--------------------------------+ Reloading Assets ---------------- @@ -64,24 +61,22 @@ Don't cache any asset file data when this value is true. See also :ref:`overriding_assets_section`. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_RELOAD_ASSETS`` | ``pyramid.reload_assets`` | -| | or ``reload_assets`` | -| | | -| | | -+---------------------------------+-----------------------------+ ++----------------------------+-----------------------------+ +| Environment Variable Name | Config File Setting Name | ++============================+=============================+ +| ``PYRAMID_RELOAD_ASSETS`` | ``pyramid.reload_assets`` | +| | or ``reload_assets`` | ++----------------------------+-----------------------------+ -.. note:: For backwards compatibility purposes, aliases can be - used for configurating asset reloading: ``PYRAMID_RELOAD_RESOURCES`` (envvar) - and ``pyramid.reload_resources`` (config file). +.. note:: For backwards compatibility purposes, aliases can be used for + configuring asset reloading: ``PYRAMID_RELOAD_RESOURCES`` (envvar) and + ``pyramid.reload_resources`` (config file). Debugging Authorization ----------------------- -Print view authorization failure and success information to stderr -when this value is true. +Print view authorization failure and success information to stderr when this +value is true. .. seealso:: @@ -92,28 +87,24 @@ when this value is true. +=================================+===================================+ | ``PYRAMID_DEBUG_AUTHORIZATION`` | ``pyramid.debug_authorization`` | | | or ``debug_authorization`` | -| | | -| | | +---------------------------------+-----------------------------------+ Debugging Not Found Errors -------------------------- -Print view-related ``NotFound`` debug messages to stderr -when this value is true. +Print view-related ``NotFound`` debug messages to stderr when this value is +true. .. seealso:: See also :ref:`debug_notfound_section`. -+---------------------------------+------------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+==============================+ -| ``PYRAMID_DEBUG_NOTFOUND`` | ``pyramid.debug_notfound`` | -| | or ``debug_notfound`` | -| | | -| | | -+---------------------------------+------------------------------+ ++----------------------------+------------------------------+ +| Environment Variable Name | Config File Setting Name | ++============================+==============================+ +| ``PYRAMID_DEBUG_NOTFOUND`` | ``pyramid.debug_notfound`` | +| | or ``debug_notfound`` | ++----------------------------+------------------------------+ Debugging Route Matching ------------------------ @@ -125,24 +116,22 @@ this value is true. See also :ref:`debug_routematch_section`. -+---------------------------------+--------------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+================================+ -| ``PYRAMID_DEBUG_ROUTEMATCH`` | ``pyramid.debug_routematch`` | -| | or ``debug_routematch`` | -| | | -| | | -+---------------------------------+--------------------------------+ ++------------------------------+--------------------------------+ +| Environment Variable Name | Config File Setting Name | ++==============================+================================+ +| ``PYRAMID_DEBUG_ROUTEMATCH`` | ``pyramid.debug_routematch`` | +| | or ``debug_routematch`` | ++------------------------------+--------------------------------+ .. _preventing_http_caching: Preventing HTTP Caching ------------------------- +----------------------- Prevent the ``http_cache`` view configuration argument from having any effect -globally in this process when this value is true. No http caching-related -response headers will be set by the Pyramid ``http_cache`` view configuration -feature when this is true. +globally in this process when this value is true. No HTTP caching-related +response headers will be set by the :app:`Pyramid` ``http_cache`` view +configuration feature when this is true. .. seealso:: @@ -153,8 +142,6 @@ feature when this is true. +=================================+==================================+ | ``PYRAMID_PREVENT_HTTP_CACHE`` | ``pyramid.prevent_http_cache`` | | | or ``prevent_http_cache`` | -| | | -| | | +---------------------------------+----------------------------------+ Preventing Cache Busting @@ -162,7 +149,7 @@ Preventing Cache Busting Prevent the ``cachebust`` static view configuration argument from having any effect globally in this process when this value is true. No cache buster will -be configured or used when this is true. +be configured or used when this is true. .. versionadded:: 1.6 @@ -175,8 +162,6 @@ be configured or used when this is true. +=================================+==================================+ | ``PYRAMID_PREVENT_CACHEBUST`` | ``pyramid.prevent_cachebust`` | | | or ``prevent_cachebust`` | -| | | -| | | +---------------------------------+----------------------------------+ Debugging All @@ -184,36 +169,32 @@ Debugging All Turns on all ``debug*`` settings. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_DEBUG_ALL`` | ``pyramid.debug_all`` | -| | or ``debug_all`` | -| | | -| | | -+---------------------------------+-----------------------------+ ++----------------------------+---------------------------+ +| Environment Variable Name | Config File Setting Name | ++============================+===========================+ +| ``PYRAMID_DEBUG_ALL`` | ``pyramid.debug_all`` | +| | or ``debug_all`` | ++----------------------------+---------------------------+ Reloading All ------------- Turns on all ``reload*`` settings. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_RELOAD_ALL`` | ``pyramid.reload_all`` | -| | or ``reload_all`` | -| | | -| | | -+---------------------------------+-----------------------------+ ++---------------------------+----------------------------+ +| Environment Variable Name | Config File Setting Name | ++===========================+============================+ +| ``PYRAMID_RELOAD_ALL`` | ``pyramid.reload_all`` or | +| | ``reload_all`` | ++---------------------------+----------------------------+ .. _default_locale_name_setting: Default Locale Name --------------------- +------------------- -The value supplied here is used as the default locale name when a -:term:`locale negotiator` is not registered. +The value supplied here is used as the default locale name when a :term:`locale +negotiator` is not registered. .. seealso:: @@ -224,8 +205,6 @@ The value supplied here is used as the default locale name when a +=================================+===================================+ | ``PYRAMID_DEFAULT_LOCALE_NAME`` | ``pyramid.default_locale_name`` | | | or ``default_locale_name`` | -| | | -| | | +---------------------------------+-----------------------------------+ .. _including_packages: @@ -235,19 +214,16 @@ Including Packages ``pyramid.includes`` instructs your application to include other packages. Using the setting is equivalent to using the -:meth:`pyramid.config.Configurator.include` method. +:meth:`pyramid.config.Configurator.include` method. -+---------------------------------+ -| Config File Setting Name | -+=================================+ -| ``pyramid.includes`` | -| | -| | -| | -+---------------------------------+ ++--------------------------+ +| Config File Setting Name | ++==========================+ +| ``pyramid.includes`` | ++--------------------------+ -The value assigned to ``pyramid.includes`` should be a sequence. The -sequence can take several different forms. +The value assigned to ``pyramid.includes`` should be a sequence. The sequence +can take several different forms. 1) It can be a string. @@ -306,7 +282,7 @@ Plain Python ++++++++++++ Using the following ``pyramid.includes`` setting in your plain-Python Pyramid -application: +application: .. code-block:: python :linenos: @@ -341,33 +317,29 @@ This value allows you to perform explicit :term:`tween` ordering in your configuration. Tweens are bits of code used by add-on authors to extend Pyramid. They form a chain, and require ordering. -Ideally, you won't need to use the ``pyramid.tweens`` setting at all. Tweens +Ideally you won't need to use the ``pyramid.tweens`` setting at all. Tweens are generally ordered and included "implicitly" when an add-on package which registers a tween is "included". Packages are included when you name a ``pyramid.includes`` setting in your configuration or when you call :meth:`pyramid.config.Configurator.include`. Authors of included add-ons provide "implicit" tween configuration ordering -hints to Pyramid when their packages are included. However, the implicit -tween ordering is only best-effort. Pyramid will attempt to provide an -implicit order of tweens as best it can using hints provided by add-on -authors, but because it's only best-effort, if very precise tween ordering is -required, the only surefire way to get it is to use an explicit tween order. -You may be required to inspect your tween ordering (see -:ref:`displaying_tweens`) and add a ``pyramid.tweens`` configuration value at -the behest of an add-on author. - -+---------------------------------+ -| Config File Setting Name | -+=================================+ -| ``pyramid.tweens`` | -| | -| | -| | -+---------------------------------+ - -The value assigned to ``pyramid.tweens`` should be a sequence. The -sequence can take several different forms. +hints to Pyramid when their packages are included. However, the implicit tween +ordering is only best-effort. Pyramid will attempt to provide an implicit +order of tweens as best it can using hints provided by add-on authors, but +because it's only best-effort, if very precise tween ordering is required, the +only surefire way to get it is to use an explicit tween order. You may be +required to inspect your tween ordering (see :ref:`displaying_tweens`) and add +a ``pyramid.tweens`` configuration value at the behest of an add-on author. + ++---------------------------+ +| Config File Setting Name | ++===========================+ +| ``pyramid.tweens`` | ++---------------------------+ + +The value assigned to ``pyramid.tweens`` should be a sequence. The sequence +can take several different forms. 1) It can be a string. @@ -375,11 +347,11 @@ sequence can take several different forms. pkg.tween_factory1 pkg.tween_factory2 pkg.tween_factory3 - The tween names can also be separated by carriage returns:: + The tween names can also be separated by carriage returns:: - pkg.tween_factory1 - pkg.tween_factory2 - pkg.tween_factory3 + pkg.tween_factory1 + pkg.tween_factory2 + pkg.tween_factory3 2) It can be a Python list, where the values are strings:: @@ -390,8 +362,8 @@ Each value in the sequence should be a :term:`dotted Python name`. PasteDeploy Configuration vs. Plain-Python Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Using the following ``pyramid.tweens`` setting in the PasteDeploy ``.ini`` -file in your application: +Using the following ``pyramid.tweens`` setting in the PasteDeploy ``.ini`` file +in your application: .. code-block:: ini @@ -420,12 +392,11 @@ It is fine to use both or either form. Examples -------- -Let's presume your configuration file is named ``MyProject.ini``, and -there is a section representing your application named ``[app:main]`` -within the file that represents your :app:`Pyramid` application. -The configuration file settings documented in the above "Config File -Setting Name" column would go in the ``[app:main]`` section. Here's -an example of such a section: +Let's presume your configuration file is named ``MyProject.ini``, and there is +a section representing your application named ``[app:main]`` within the file +that represents your :app:`Pyramid` application. The configuration file +settings documented in the above "Config File Setting Name" column would go in +the ``[app:main]`` section. Here's an example of such a section: .. code-block:: ini :linenos: @@ -435,41 +406,39 @@ an example of such a section: pyramid.reload_templates = true pyramid.debug_authorization = true -You can also use environment variables to accomplish the same purpose -for settings documented as such. For example, you might start your -:app:`Pyramid` application using the following command line: +You can also use environment variables to accomplish the same purpose for +settings documented as such. For example, you might start your :app:`Pyramid` +application using the following command line: .. code-block:: text $ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \ $VENV/bin/pserve MyProject.ini -If you started your application this way, your :app:`Pyramid` -application would behave in the same manner as if you had placed the -respective settings in the ``[app:main]`` section of your -application's ``.ini`` file. +If you started your application this way, your :app:`Pyramid` application would +behave in the same manner as if you had placed the respective settings in the +``[app:main]`` section of your application's ``.ini`` file. -If you want to turn all ``debug`` settings (every setting that starts -with ``pyramid.debug_``). on in one fell swoop, you can use -``PYRAMID_DEBUG_ALL=1`` as an environment variable setting or you may use -``pyramid.debug_all=true`` in the config file. Note that this does not affect -settings that do not start with ``pyramid.debug_*`` such as -``pyramid.reload_templates``. +If you want to turn all ``debug`` settings (every setting that starts with +``pyramid.debug_``) on in one fell swoop, you can use ``PYRAMID_DEBUG_ALL=1`` +as an environment variable setting or you may use ``pyramid.debug_all=true`` in +the config file. Note that this does not affect settings that do not start +with ``pyramid.debug_*`` such as ``pyramid.reload_templates``. If you want to turn all ``pyramid.reload`` settings (every setting that starts with ``pyramid.reload_``) on in one fell swoop, you can use ``PYRAMID_RELOAD_ALL=1`` as an environment variable setting or you may use -``pyramid.reload_all=true`` in the config file. Note that this does not -affect settings that do not start with ``pyramid.reload_*`` such as +``pyramid.reload_all=true`` in the config file. Note that this does not affect +settings that do not start with ``pyramid.reload_*`` such as ``pyramid.debug_notfound``. .. note:: Specifying configuration settings via environment variables is generally - most useful during development, where you may wish to augment or - override the more permanent settings in the configuration file. - This is useful because many of the reload and debug settings may - have performance or security (i.e., disclosure) implications - that make them undesirable in a production environment. + most useful during development, where you may wish to augment or override + the more permanent settings in the configuration file. This is useful + because many of the reload and debug settings may have performance or + security (i.e., disclosure) implications that make them undesirable in a + production environment. .. index:: single: reload_templates @@ -480,13 +449,13 @@ Understanding the Distinction Between ``reload_templates`` and ``reload_assets`` The difference between ``pyramid.reload_assets`` and ``pyramid.reload_templates`` is a bit subtle. Templates are themselves also -treated by :app:`Pyramid` as asset files (along with other static files), so the -distinction can be confusing. It's helpful to read +treated by :app:`Pyramid` as asset files (along with other static files), so +the distinction can be confusing. It's helpful to read :ref:`overriding_assets_section` for some context about assets in general. -When ``pyramid.reload_templates`` is true, :app:`Pyramid` takes advantage of the -underlying templating systems' ability to check for file modifications to an -individual template file. When ``pyramid.reload_templates`` is true but +When ``pyramid.reload_templates`` is true, :app:`Pyramid` takes advantage of +the underlying templating system's ability to check for file modifications to +an individual template file. When ``pyramid.reload_templates`` is true, but ``pyramid.reload_assets`` is *not* true, the template filename returned by the ``pkg_resources`` package (used under the hood by asset resolution) is cached by :app:`Pyramid` on the first request. Subsequent requests for the same @@ -499,21 +468,21 @@ because it has some effect). However, when ``pyramid.reload_assets`` is true, :app:`Pyramid` will not cache the template filename, meaning you can see the effect of changing the content of an overridden asset directory for templates without restarting the server -after every change. Subsequent requests for the same template file may -return different filenames based on the current state of overridden asset -directories. Setting ``pyramid.reload_assets`` to ``True`` affects performance -*dramatically*, slowing things down by an order of magnitude for each -template rendering. However, it's convenient to enable when moving files -around in overridden asset directories. ``pyramid.reload_assets`` makes the -system *very slow* when templates are in use. Never set -``pyramid.reload_assets`` to ``True`` on a production system. +after every change. Subsequent requests for the same template file may return +different filenames based on the current state of overridden asset directories. +Setting ``pyramid.reload_assets`` to ``True`` affects performance +*dramatically*, slowing things down by an order of magnitude for each template +rendering. However, it's convenient to enable when moving files around in +overridden asset directories. ``pyramid.reload_assets`` makes the system *very +slow* when templates are in use. Never set ``pyramid.reload_assets`` to +``True`` on a production system. .. index:: par: settings; adding custom .. _adding_a_custom_setting: -Adding A Custom Setting +Adding a Custom Setting ----------------------- From time to time, you may need to add a custom setting to your application. @@ -530,12 +499,12 @@ Here's how: debug_frobnosticator = True - In the ``main()`` function that represents the place that your Pyramid WSGI - application is created, anticipate that you'll be getting this key/value - pair as a setting and do any type conversion necessary. + application is created, anticipate that you'll be getting this key/value pair + as a setting and do any type conversion necessary. - If you've done any type conversion of your custom value, reset the - converted values into the ``settings`` dictionary *before* you pass the - dictionary as ``settings`` to the :term:`Configurator`. For example: + If you've done any type conversion of your custom value, reset the converted + values into the ``settings`` dictionary *before* you pass the dictionary as + ``settings`` to the :term:`Configurator`. For example: .. code-block:: python @@ -547,16 +516,17 @@ Here's how: settings['debug_frobnosticator'] = debug_frobnosticator config = Configurator(settings=settings) - .. note:: It's especially important that you mutate the ``settings`` - dictionary with the converted version of the variable *before* passing - it to the Configurator: the configurator makes a *copy* of ``settings``, - it doesn't use the one you pass directly. - -- When creating an ``includeme`` function that will be later added to your + .. note:: + It's especially important that you mutate the ``settings`` dictionary with + the converted version of the variable *before* passing it to the + Configurator: the configurator makes a *copy* of ``settings``, it doesn't + use the one you pass directly. + +- When creating an ``includeme`` function that will be later added to your application's configuration you may access the ``settings`` dictionary through the instance of the :term:`Configurator` that is passed into the function as its only argument. For Example: - + .. code-block:: python def includeme(config): @@ -573,8 +543,8 @@ Here's how: settings = request.registry.settings debug_frobnosticator = settings['debug_frobnosticator'] - If you wish to use the value in code that does not have access to the - request and you wish to use the value, you'll need to use the + If you wish to use the value in code that does not have access to the request + and you wish to use the value, you'll need to use the :func:`pyramid.threadlocal.get_current_registry` API to obtain the current registry, then ask for its ``settings`` attribute. For example: @@ -583,7 +553,3 @@ Here's how: registry = pyramid.threadlocal.get_current_registry() settings = registry.settings debug_frobnosticator = settings['debug_frobnosticator'] - - - - |