diff options
Diffstat (limited to 'docs/narr/environment.rst')
| -rw-r--r-- | docs/narr/environment.rst | 717 |
1 files changed, 412 insertions, 305 deletions
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 3b938c09c..743266d2c 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -8,6 +8,8 @@ single: debug_all single: reload_all single: debug settings + single: debug_routematch + single: prevent_http_cache single: reload settings single: default_locale_name single: environment variables @@ -19,330 +21,424 @@ 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. +: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. +.. 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. +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`` | ``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 ---------------- -Don't cache any asset file data when this value is true. See -also :ref:`overriding_assets_section`. +Don't cache any asset file data when this value is true. + +.. seealso:: + + See also :ref:`overriding_assets_section`. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_RELOAD_ASSETS`` | ``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 ``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. See also :ref:`debug_authorization_section`. +Print view authorization failure and success information to stderr when this +value is true. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_DEBUG_AUTHORIZATION`` | ``debug_authorization`` | -| | | -| | | -| | | -+---------------------------------+-----------------------------+ +.. seealso:: + + See also :ref:`debug_authorization_section`. + ++---------------------------------+-----------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+===================================+ +| ``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. See also :ref:`debug_notfound_section`. +Print view-related ``NotFound`` debug messages to stderr when this value is +true. + +.. seealso:: -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_DEBUG_NOTFOUND`` | ``debug_notfound`` | -| | | -| | | -| | | -+---------------------------------+-----------------------------+ + See also :ref:`debug_notfound_section`. + ++----------------------------+------------------------------+ +| Environment Variable Name | Config File Setting Name | ++============================+==============================+ +| ``PYRAMID_DEBUG_NOTFOUND`` | ``pyramid.debug_notfound`` | +| | or ``debug_notfound`` | ++----------------------------+------------------------------+ Debugging Route Matching ------------------------ Print debugging messages related to :term:`url dispatch` route matching when -this value is true. See also :ref:`debug_routematch_section`. +this value is true. + +.. seealso:: + + See also :ref:`debug_routematch_section`. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_DEBUG_ROUTEMATCH`` | ``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 :app:`Pyramid` ``http_cache`` view +configuration feature when this is true. + +.. seealso:: + + See also :ref:`influencing_http_caching`. + ++---------------------------------+----------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+==================================+ +| ``PYRAMID_PREVENT_HTTP_CACHE`` | ``pyramid.prevent_http_cache`` | +| | or ``prevent_http_cache`` | ++---------------------------------+----------------------------------+ + +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. + +.. versionadded:: 1.6 + +.. seealso:: + + See also :ref:`cache_busting`. + ++---------------------------------+----------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+==================================+ +| ``PYRAMID_PREVENT_CACHEBUST`` | ``pyramid.prevent_cachebust`` | +| | or ``prevent_cachebust`` | ++---------------------------------+----------------------------------+ Debugging All ------------- Turns on all ``debug*`` settings. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_DEBUG_ALL`` | ``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`` | ``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. See also -:ref:`localization_deployment_settings`. - -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_DEFAULT_LOCALE_NAME`` | ``default_locale_name`` | -| | | -| | | -| | | -+---------------------------------+-----------------------------+ - -.. _mako_template_renderer_settings: - -Mako Template Render Settings ------------------------------ - -Mako derives additional settings to configure its template renderer that -should be set when using it. Many of these settings are optional and only need -to be set if they should be different from the default. The Mako Template -Renderer uses a subclass of Mako's `template lookup -<http://www.makotemplates.org/docs/usage.html#usage_lookup>`_ and accepts -several arguments to configure it. - -Mako Directories -++++++++++++++++ - -The value(s) supplied here are passed in as the template directories. They -should be in :term:`asset specification` format, for example: -``my.package:templates``. - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.directories`` | -| | -| | -| | -+-----------------------------+ - -Mako Module Directory -+++++++++++++++++++++ - -The value supplied here tells Mako where to store compiled Mako templates. If -omitted, compiled templates will be stored in memory. This value should be an -absolute path, for example: ``%(here)s/data/templates`` would use a directory -called ``data/templates`` in the same parent directory as the INI file. - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.module_directory`` | -| | -| | -| | -+-----------------------------+ - -Mako Input Encoding -+++++++++++++++++++ - -The encoding that Mako templates are assumed to have. By default this is set -to ``utf-8``. If you wish to use a different template encoding, this value -should be changed accordingly. - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.input_encoding`` | -| | -| | -| | -+-----------------------------+ - -Mako Error Handler -++++++++++++++++++ - -Python callable which is called whenever Mako compile or runtime exceptions -occur. The callable is passed the current context as well as the exception. If -the callable returns True, the exception is considered to be handled, else it -is re-raised after the function completes. Is used to provide custom -error-rendering functions. - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.error_handler`` | -| | -| | -| | -+-----------------------------+ - -Mako Default Filters -++++++++++++++++++++ - -List of string filter names that will be applied to all Mako expressions. - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.default_filters`` | -| | -| | -| | -+-----------------------------+ - -Mako Import -+++++++++++ - -String list of Python statements, typically individual "import" lines, which -will be placed into the module level preamble of all generated Python modules. - - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.imports`` | -| | -| | -| | -+-----------------------------+ - - -Mako Strict Undefined -+++++++++++++++++++++ - -``true`` or ``false``, representing the "strict undefined" behavior of Mako -(see `Mako Context Variables -<http://www.makotemplates.org/docs/runtime.html#context-variables>`_). By -default, this is ``false``. - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.strict_undefined`` | -| | -| | -| | -+-----------------------------+ +------------------- + +The value supplied here is used as the default locale name when a :term:`locale +negotiator` is not registered. + +.. seealso:: + + See also :ref:`localization_deployment_settings`. + ++---------------------------------+-----------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+===================================+ +| ``PYRAMID_DEFAULT_LOCALE_NAME`` | ``pyramid.default_locale_name`` | +| | or ``default_locale_name`` | ++---------------------------------+-----------------------------------+ + +.. _including_packages: + +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. + ++--------------------------+ +| Config File Setting Name | ++==========================+ +| ``pyramid.includes`` | ++--------------------------+ + +The value assigned to ``pyramid.includes`` should be a sequence. The sequence +can take several different forms. + +1) It can be a string. + + If it is a string, the package names can be separated by spaces:: + + package1 package2 package3 + + The package names can also be separated by carriage returns:: + + package1 + package2 + package3 + +2) It can be a Python list, where the values are strings:: + + ['package1', 'package2', 'package3'] + +Each value in the sequence should be a :term:`dotted Python name`. + +``pyramid.includes`` vs. :meth:`pyramid.config.Configurator.include` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Two methods exist for including packages: ``pyramid.includes`` and +:meth:`pyramid.config.Configurator.include`. This section explains their +equivalence. + +Using PasteDeploy ++++++++++++++++++ + +Using the following ``pyramid.includes`` setting in the PasteDeploy ``.ini`` +file in your application: + +.. code-block:: ini + + [app:main] + pyramid.includes = pyramid_debugtoolbar + pyramid_tm + +Is equivalent to using the following statements in your configuration code: + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + + def main(global_config, **settings): + config = Configurator(settings=settings) + # ... + config.include('pyramid_debugtoolbar') + config.include('pyramid_tm') + # ... + +It is fine to use both or either form. + +Plain Python +++++++++++++ + +Using the following ``pyramid.includes`` setting in your plain-Python Pyramid +application: + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + + if __name__ == '__main__': + settings = {'pyramid.includes':'pyramid_debugtoolbar pyramid_tm'} + config = Configurator(settings=settings) + +Is equivalent to using the following statements in your configuration code: + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + + if __name__ == '__main__': + settings = {} + config = Configurator(settings=settings) + config.include('pyramid_debugtoolbar') + config.include('pyramid_tm') + +It is fine to use both or either form. + +.. _explicit_tween_config: + +Explicit Tween Configuration +---------------------------- + +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 +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. + +1) It can be a string. + + If it is a string, the tween names can be separated by spaces:: + + pkg.tween_factory1 pkg.tween_factory2 pkg.tween_factory3 + + The tween names can also be separated by carriage returns:: + + pkg.tween_factory1 + pkg.tween_factory2 + pkg.tween_factory3 + +2) It can be a Python list, where the values are strings:: + + ['pkg.tween_factory1', 'pkg.tween_factory2', 'pkg.tween_factory3'] + +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: + +.. code-block:: ini + + [app:main] + pyramid.tweens = pyramid_debugtoolbar.toolbar.tween_factory + pyramid.tweens.excview_tween_factory + pyramid_tm.tm_tween_factory + +Is equivalent to using the following statements in your configuration code: + +.. code-block:: python + :linenos: + + from pyramid.config import Configurator + + def main(global_config, **settings): + settings['pyramid.tweens'] = [ + 'pyramid_debugtoolbar.toolbar.tween_factory', + 'pyramid.tweebs.excview_tween_factory', + 'pyramid_tm.tm_tween_factory', + ] + config = Configurator(settings=settings) + +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: [app:main] - use = egg:MyProject#app - reload_templates = true - debug_authorization = true + use = egg:MyProject + 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 \ - bin/paster serve 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 want to turn all ``debug`` settings (every setting that starts -with ``debug_``). on in one fell swoop, you can use -``PYRAMID_DEBUG_ALL=1`` as an environment variable setting or you may use -``debug_all=true`` in the config file. Note that this does not affect -settings that do not start with ``debug_*`` such as -``reload_templates``. - -If you want to turn all ``reload`` settings (every setting that starts -with ``reload_``) on in one fell swoop, you can use + $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 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 -``reload_all=true`` in the config file. Note that this does not -affect settings that do not start with ``reload_*`` such as -``debug_notfound``. +``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 @@ -351,39 +447,42 @@ affect settings that do not start with ``reload_*`` such as Understanding the Distinction Between ``reload_templates`` and ``reload_assets`` -------------------------------------------------------------------------------- -The difference between ``reload_assets`` and ``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 :ref:`overriding_assets_section` for some context -about assets in general. +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 +:ref:`overriding_assets_section` for some context about assets in general. -When ``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 ``reload_templates`` is true but -``reload_assets`` is *not* true, the template filename returned by the +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 template file will return a cached template filename. The underlying templating system checks for modifications to this particular file for every -request. Setting ``reload_templates`` to ``True`` doesn't affect performance -dramatically (although it should still not be used in production because it -has some effect). - -However, when ``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 ``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. ``reload_assets`` makes the system -*very slow* when templates are in use. Never set ``reload_assets`` to +request. Setting ``pyramid.reload_templates`` to ``True`` doesn't affect +performance dramatically (although it should still not be used in production +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. +.. 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. @@ -395,17 +494,17 @@ Here's how: .. code-block:: ini - [app:myapp] + [app:main] # .. other settings 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 @@ -417,23 +516,35 @@ 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. + .. 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: -- In the runtime code that you need to access the new settings value, find - the value in the ``registry.settings`` dictionary and use it. In + .. code-block:: python + + def includeme(config): + settings = config.registry.settings + debug_frobnosticator = settings['debug_frobnosticator'] + +- In the runtime code from where you need to access the new settings value, + find the value in the ``registry.settings`` dictionary and use it. In :term:`view` code (or any other code that has access to the request), the easiest way to do this is via ``request.registry.settings``. For example: .. code-block:: python - registry = request.registry.settings + 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: @@ -442,7 +553,3 @@ Here's how: registry = pyramid.threadlocal.get_current_registry() settings = registry.settings debug_frobnosticator = settings['debug_frobnosticator'] - - - - |