From 8bd6cf291b91977f22d8e153328cc13d38d00ff2 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 26 Jun 2011 03:46:47 -0400 Subject: - Added ``mako.preprocessor`` config file parameter; allows for a Mako preprocessor to be specified as a Python callable or Python dotted name. See https://github.com/Pylons/pyramid/pull/183 for rationale. Closes #183. --- docs/narr/environment.rst | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 3b938c09c..a57b316e1 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -227,11 +227,11 @@ should be changed accordingly. 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. +A callable (or a :term:`dotted Python name` which names a 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 | @@ -290,6 +290,25 @@ default, this is ``false``. | | +-----------------------------+ +Mako Preprocessor ++++++++++++++++++ + +A callable (or a :term:`dotted Python name` which names a callable) which is +called to preprocess the source before the template is called. The callable +will be passed the full template source before it is parsed. The return +result of the callable will be used as the template source code. + +.. note:: This feature is new in Pyramid 1.1. + ++-----------------------------+ +| Config File Setting Name | ++=============================+ +| ``mako.preprocessor`` | +| | +| | +| | ++-----------------------------+ + Examples -------- -- cgit v1.2.3 From e573d4356ed0371f5ba34ff3ff396fefd2e55913 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 12 Jul 2011 20:56:53 -0400 Subject: - New environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and new configuration file value ``prevent_http_cache``. These are synomymous and allow you to prevent HTTP cache headers from being set by Pyramid's ``http_cache`` machinery globally in a process. see the "Influencing HTTP Caching" section of the "View Configuration" narrative chapter and the detailed documentation for this setting in the "Environment Variables and Configuration Settings" narrative chapter. - New documentation section in View Configuration narrative chapter: "Influencing HTTP Caching". --- docs/narr/environment.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index a57b316e1..7f8e3953d 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -117,6 +117,25 @@ this value is true. See also :ref:`debug_routematch_section`. | | | +---------------------------------+-----------------------------+ +.. _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. See also :ref:`influencing_http_caching`. + ++---------------------------------+-----------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+=============================+ +| ``PYRAMID_PREVENT_HTTP_CACHE`` | ``prevent_http_cache`` | +| | | +| | | +| | | ++---------------------------------+-----------------------------+ + Debugging All ------------- -- cgit v1.2.3 From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/environment.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 7f8e3953d..53234cba1 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -8,9 +8,12 @@ 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 + single: Mako environment settings single: ini file settings single: PasteDeploy settings @@ -419,6 +422,9 @@ around in overridden asset directories. ``reload_assets`` makes the system *very slow* when templates are in use. Never set ``reload_assets`` to ``True`` on a production system. +.. index:: + par: settings; adding custom + .. _adding_a_custom_setting: Adding A Custom Setting -- cgit v1.2.3 From 875ded31e7fdd0c85d1c91458248581b9dd729d7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 30 Jul 2011 01:50:24 -0600 Subject: Updated all of the docs to reflect the new pyramid.* settings prefix. --- docs/narr/environment.rst | 162 +++++++++++++++++++++++----------------------- 1 file changed, 81 insertions(+), 81 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 53234cba1..6465c2a1e 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -47,14 +47,14 @@ 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`` | -| | | -| | | -| | | -+---------------------------------+-----------------------------+ ++---------------------------------+--------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+================================+ +| ``PYRAMID_RELOAD_TEMPLATES`` | ``pyramid.reload_templates`` | +| | | +| | | +| | | ++---------------------------------+--------------------------------+ Reloading Assets ---------------- @@ -65,7 +65,7 @@ also :ref:`overriding_assets_section`. +---------------------------------+-----------------------------+ | Environment Variable Name | Config File Setting Name | +=================================+=============================+ -| ``PYRAMID_RELOAD_ASSETS`` | ``reload_assets`` | +| ``PYRAMID_RELOAD_ASSETS`` | ``pyramid.reload_assets`` | | | | | | | | | | @@ -73,7 +73,7 @@ also :ref:`overriding_assets_section`. .. note:: For backwards compatibility purposes, aliases can be used for configurating asset reloading: ``PYRAMID_RELOAD_RESOURCES`` (envvar) - and ``reload_resources`` (config file). + and ``pyramid.reload_resources`` (config file). Debugging Authorization ----------------------- @@ -81,14 +81,14 @@ Debugging Authorization Print view authorization failure and success information to stderr when this value is true. See also :ref:`debug_authorization_section`. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_DEBUG_AUTHORIZATION`` | ``debug_authorization`` | -| | | -| | | -| | | -+---------------------------------+-----------------------------+ ++---------------------------------+-----------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+===================================+ +| ``PYRAMID_DEBUG_AUTHORIZATION`` | ``pyramid.debug_authorization`` | +| | | +| | | +| | | ++---------------------------------+-----------------------------------+ Debugging Not Found Errors -------------------------- @@ -96,14 +96,14 @@ Debugging Not Found Errors Print view-related ``NotFound`` debug messages to stderr when this value is true. See also :ref:`debug_notfound_section`. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_DEBUG_NOTFOUND`` | ``debug_notfound`` | -| | | -| | | -| | | -+---------------------------------+-----------------------------+ ++---------------------------------+------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+==============================+ +| ``PYRAMID_DEBUG_NOTFOUND`` | ``pyramid.debug_notfound`` | +| | | +| | | +| | | ++---------------------------------+------------------------------+ Debugging Route Matching ------------------------ @@ -111,14 +111,14 @@ Debugging Route Matching Print debugging messages related to :term:`url dispatch` route matching when this value is true. 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`` | +| | | +| | | +| | | ++---------------------------------+--------------------------------+ .. _preventing_http_caching: @@ -130,14 +130,14 @@ 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. See also :ref:`influencing_http_caching`. -+---------------------------------+-----------------------------+ -| Environment Variable Name | Config File Setting Name | -+=================================+=============================+ -| ``PYRAMID_PREVENT_HTTP_CACHE`` | ``prevent_http_cache`` | -| | | -| | | -| | | -+---------------------------------+-----------------------------+ ++---------------------------------+----------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+==================================+ +| ``PYRAMID_PREVENT_HTTP_CACHE`` | ``pyramid.prevent_http_cache`` | +| | | +| | | +| | | ++---------------------------------+----------------------------------+ Debugging All ------------- @@ -147,7 +147,7 @@ Turns on all ``debug*`` settings. +---------------------------------+-----------------------------+ | Environment Variable Name | Config File Setting Name | +=================================+=============================+ -| ``PYRAMID_DEBUG_ALL`` | ``debug_all`` | +| ``PYRAMID_DEBUG_ALL`` | ``pyramid.debug_all`` | | | | | | | | | | @@ -161,7 +161,7 @@ Turns on all ``reload*`` settings. +---------------------------------+-----------------------------+ | Environment Variable Name | Config File Setting Name | +=================================+=============================+ -| ``PYRAMID_RELOAD_ALL`` | ``reload_all`` | +| ``PYRAMID_RELOAD_ALL`` | ``pyramid.reload_all`` | | | | | | | | | | @@ -176,14 +176,14 @@ 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`` | -| | | -| | | -| | | -+---------------------------------+-----------------------------+ ++---------------------------------+-----------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+===================================+ +| ``PYRAMID_DEFAULT_LOCALE_NAME`` | ``pyramid.default_locale_name`` | +| | | +| | | +| | | ++---------------------------------+-----------------------------------+ .. _mako_template_renderer_settings: @@ -346,8 +346,8 @@ an example of such a section: [app:main] use = egg:MyProject#app - reload_templates = true - debug_authorization = true + 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 @@ -364,18 +364,18 @@ 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 +with ``pyramid.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``. +``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 ``reload`` settings (every setting that starts -with ``reload_``) on in one fell swoop, you can use +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 @@ -392,35 +392,35 @@ 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 +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 ``reload_templates`` is true but -``reload_assets`` is *not* true, the template filename returned by the +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). +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 ``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 +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 ``reload_assets`` to ``True`` affects performance +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. ``reload_assets`` makes the system -*very slow* when templates are in use. Never set ``reload_assets`` to -``True`` on a production system. +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 -- cgit v1.2.3 From 8cd013ed14f22b85096784ace1bac480f3825414 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 11 Aug 2011 23:28:52 -0400 Subject: add docs for pyramid.includes; allow space-separated or cr separated items or both for tweens and includes --- docs/narr/environment.rst | 98 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 6465c2a1e..cb6bc6a5d 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -185,6 +185,104 @@ The value supplied here is used as the default locale name when a | | | +---------------------------------+-----------------------------------+ +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 supplied as ``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` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PasteDeploy ++++++++++++ + +Using the following ``pyramid.includes`` setting in the PasteDeploy ``.ini`` +file in your application: + +.. code-block:: ini + + [app:myapp] + 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. + .. _mako_template_renderer_settings: Mako Template Render Settings -- cgit v1.2.3 From be46dacfd3b197ce3d8cb907532daa49c93fb8df Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Aug 2011 00:08:16 -0400 Subject: add pyramid.tweens configuration value docs --- docs/narr/environment.rst | 83 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index cb6bc6a5d..cc858a892 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -283,6 +283,89 @@ Is equivalent to using the following statements in your configuration code: It is fine to use both or either form. +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.Configuration.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 supplied as ``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`. + +Paste Configuration vs. Plain-Python Configuration +++++++++++++++++++++++++++++++++++++++++++++++++++ + +Using the following ``pyramid.tweens`` setting in the PasteDeploy ``.ini`` +file in your application: + +.. code-block:: ini + + [app:myapp] + 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. + .. _mako_template_renderer_settings: Mako Template Render Settings -- cgit v1.2.3 From 47369747d8050faddd8b98f4cad9f5d0bb263130 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Aug 2011 00:17:52 -0400 Subject: garden changes; fix docs rendering --- docs/narr/environment.rst | 72 +++++++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 34 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index cc858a892..2f5555840 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -225,31 +225,35 @@ Each value in the sequence should be a :term:`dotted Python name`. ``pyramid.includes`` vs. :meth:`pyramid.config.Configurator.include` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -PasteDeploy -+++++++++++ +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:myapp] - pyramid.includes = pyramid_debugtoolbar - pyramid_tm + [app:myapp] + 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 + from pyramid.config import Configurator - def main(global_config, **settings): - config = Configurator(settings=settings) - # ... - config.include('pyramid_debugtoolbar') - config.include('pyramid_tm') - # ... + 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. @@ -337,32 +341,32 @@ sequence can take several different forms. Each value in the sequence should be a :term:`dotted Python name`. Paste Configuration vs. Plain-Python Configuration -++++++++++++++++++++++++++++++++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using the following ``pyramid.tweens`` setting in the PasteDeploy ``.ini`` file in your application: .. code-block:: ini - [app:myapp] - pyramid.tweens = pyramid_debugtoolbar.toolbar.tween_factory - pyramid.tweens.excview_tween_factory - pyramid_tm.tm_tween_factory + [app:myapp] + 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) + 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. @@ -379,7 +383,7 @@ Renderer uses a subclass of Mako's `template lookup 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: @@ -395,7 +399,7 @@ should be in :term:`asset specification` format, for example: +-----------------------------+ 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 @@ -412,7 +416,7 @@ called ``data/templates`` in the same parent directory as the INI file. +-----------------------------+ 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 @@ -428,7 +432,7 @@ should be changed accordingly. +-----------------------------+ Mako Error Handler -++++++++++++++++++ +~~~~~~~~~~~~~~~~~~ A callable (or a :term:`dotted Python name` which names a callable) which is called whenever Mako compile or runtime exceptions occur. The callable is @@ -446,7 +450,7 @@ the function completes. Is used to provide custom error-rendering functions. +-----------------------------+ Mako Default Filters -++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~ List of string filter names that will be applied to all Mako expressions. @@ -460,7 +464,7 @@ List of string filter names that will be applied to all Mako expressions. +-----------------------------+ 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. @@ -477,7 +481,7 @@ will be placed into the module level preamble of all generated Python modules. Mako Strict Undefined -+++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~~ ``true`` or ``false``, representing the "strict undefined" behavior of Mako (see `Mako Context Variables @@ -494,7 +498,7 @@ default, this is ``false``. +-----------------------------+ Mako Preprocessor -+++++++++++++++++ +~~~~~~~~~~~~~~~~~ A callable (or a :term:`dotted Python name` which names a callable) which is called to preprocess the source before the template is called. The callable -- cgit v1.2.3 From a8c81dbd55b1e06dd2da1b598670dc27a73ce8b1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 21 Aug 2011 00:23:00 -0400 Subject: add a whatsnew-1.2 doc --- docs/narr/environment.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 2f5555840..352912a81 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -185,6 +185,8 @@ The value supplied here is used as the default locale name when a | | | +---------------------------------+-----------------------------------+ +.. _including_packages: + Including Packages ------------------ @@ -287,6 +289,8 @@ Is equivalent to using the following statements in your configuration code: It is fine to use both or either form. +.. _explicit_tween_config: + Explicit Tween Configuration ---------------------------- -- cgit v1.2.3 From 3d338ea5737b7c113b17120b40684e2694cf3fa9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Aug 2011 02:16:55 -0400 Subject: - Use [app:main] instead of a pipeline in all scaffolds and tutorials and narrative docs. - Break out awkward description of PasteDeploy entry points from project chapter into its own Paste chapter. --- docs/narr/environment.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 352912a81..a5909e541 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -239,7 +239,7 @@ file in your application: .. code-block:: ini - [app:myapp] + [app:main] pyramid.includes = pyramid_debugtoolbar pyramid_tm @@ -352,7 +352,7 @@ file in your application: .. code-block:: ini - [app:myapp] + [app:main] pyramid.tweens = pyramid_debugtoolbar.toolbar.tween_factory pyramid.tweens.excview_tween_factory pyramid_tm.tm_tween_factory @@ -534,7 +534,7 @@ an example of such a section: :linenos: [app:main] - use = egg:MyProject#app + use = egg:MyProject pyramid.reload_templates = true pyramid.debug_authorization = true @@ -628,7 +628,7 @@ Here's how: .. code-block:: ini - [app:myapp] + [app:main] # .. other settings debug_frobnosticator = True -- cgit v1.2.3 From 1feefdb0a789c89e1c4dd201a99aac6418a15b68 Mon Sep 17 00:00:00 2001 From: Charlie Choiniere Date: Sat, 3 Sep 2011 20:51:40 -0400 Subject: Updated environment documentation to include an example of accessing the settings dictionary inside an includeme function --- docs/narr/environment.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index a5909e541..da93332c0 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -654,7 +654,18 @@ Here's how: 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): + settings = config.registry.settings + debug_frobnosticator = settings['debug_frobnosticator'] + - 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 :term:`view` code (or any other code that has access to the request), the @@ -662,7 +673,7 @@ Here's how: .. 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 -- cgit v1.2.3 From b4870b1d58f57cb20edefd4b0306615c0fc5a2e0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 5 Sep 2011 00:19:19 -0400 Subject: readd aliases to environment tables --- docs/narr/environment.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index da93332c0..2ac094d47 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -51,7 +51,7 @@ third-party template rendering extensions. | Environment Variable Name | Config File Setting Name | +=================================+================================+ | ``PYRAMID_RELOAD_TEMPLATES`` | ``pyramid.reload_templates`` | -| | | +| | or ``reload_templates`` | | | | | | | +---------------------------------+--------------------------------+ @@ -66,7 +66,7 @@ also :ref:`overriding_assets_section`. | Environment Variable Name | Config File Setting Name | +=================================+=============================+ | ``PYRAMID_RELOAD_ASSETS`` | ``pyramid.reload_assets`` | -| | | +| | or ``reload_assets`` | | | | | | | +---------------------------------+-----------------------------+ @@ -85,7 +85,7 @@ when this value is true. See also :ref:`debug_authorization_section`. | Environment Variable Name | Config File Setting Name | +=================================+===================================+ | ``PYRAMID_DEBUG_AUTHORIZATION`` | ``pyramid.debug_authorization`` | -| | | +| | or ``debug_authorization`` | | | | | | | +---------------------------------+-----------------------------------+ @@ -100,7 +100,7 @@ when this value is true. See also :ref:`debug_notfound_section`. | Environment Variable Name | Config File Setting Name | +=================================+==============================+ | ``PYRAMID_DEBUG_NOTFOUND`` | ``pyramid.debug_notfound`` | -| | | +| | or ``debug_notfound`` | | | | | | | +---------------------------------+------------------------------+ @@ -115,7 +115,7 @@ 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`` | | | | | | | +---------------------------------+--------------------------------+ @@ -134,7 +134,7 @@ feature when this is true. 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`` | | | | | | | +---------------------------------+----------------------------------+ @@ -148,7 +148,7 @@ Turns on all ``debug*`` settings. | Environment Variable Name | Config File Setting Name | +=================================+=============================+ | ``PYRAMID_DEBUG_ALL`` | ``pyramid.debug_all`` | -| | | +| | or ``debug_all`` | | | | | | | +---------------------------------+-----------------------------+ @@ -162,7 +162,7 @@ Turns on all ``reload*`` settings. | Environment Variable Name | Config File Setting Name | +=================================+=============================+ | ``PYRAMID_RELOAD_ALL`` | ``pyramid.reload_all`` | -| | | +| | or ``reload_all`` | | | | | | | +---------------------------------+-----------------------------+ @@ -180,7 +180,7 @@ The value supplied here is used as the default locale name when a | Environment Variable Name | Config File Setting Name | +=================================+===================================+ | ``PYRAMID_DEFAULT_LOCALE_NAME`` | ``pyramid.default_locale_name`` | -| | | +| | or ``default_locale_name`` | | | | | | | +---------------------------------+-----------------------------------+ -- cgit v1.2.3 From f8869cb0664506204b22aa791003a6d5f8ded58c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Oct 2011 03:22:35 -0400 Subject: remove stray references to Paste --- docs/narr/environment.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 2ac094d47..8206e0bcb 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -344,8 +344,8 @@ sequence can take several different forms. Each value in the sequence should be a :term:`dotted Python name`. -Paste Configuration vs. Plain-Python Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +PasteDeploy Configuration vs. Plain-Python Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using the following ``pyramid.tweens`` setting in the PasteDeploy ``.ini`` file in your application: -- cgit v1.2.3 From fdcd1beef58e106b556f6586f4a95e02d6aec1f4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 28 Jan 2013 08:27:05 +0200 Subject: use a more correct directive --- docs/narr/environment.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 8206e0bcb..def5e12a4 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -504,12 +504,13 @@ default, this is ``false``. Mako Preprocessor ~~~~~~~~~~~~~~~~~ +.. versionadded:: 1.1 + A callable (or a :term:`dotted Python name` which names a callable) which is called to preprocess the source before the template is called. The callable will be passed the full template source before it is parsed. The return result of the callable will be used as the template source code. -.. note:: This feature is new in Pyramid 1.1. +-----------------------------+ | Config File Setting Name | -- cgit v1.2.3 From 3a6bdf983b51d8d0df124999ae217084c7dddbc6 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 3 Feb 2013 12:38:55 +0200 Subject: use clearer language --- docs/narr/environment.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index def5e12a4..281bb6919 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -203,7 +203,7 @@ Using the setting is equivalent to using the | | +---------------------------------+ -The value supplied as ``pyramid.includes`` should be a sequence. The +The value assigned to ``pyramid.includes`` should be a sequence. The sequence can take several different forms. 1) It can be a string. @@ -323,7 +323,7 @@ the behest of an add-on author. | | +---------------------------------+ -The value supplied as ``pyramid.tweens`` should be a sequence. The +The value assigned to ``pyramid.tweens`` should be a sequence. The sequence can take several different forms. 1) It can be a string. -- cgit v1.2.3 From a33ac9438f62c6d85263c772d601d77e1b2b1e3c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 22 Feb 2013 00:25:06 +0200 Subject: paster use is outdated --- docs/narr/environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 281bb6919..fb3c3d7e3 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -546,7 +546,7 @@ for settings documented as such. For example, you might start your .. code-block:: text $ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \ - bin/paster serve MyProject.ini + 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 -- cgit v1.2.3 From 3144affbb05ecea581d0e1cc612a3e1672b55181 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 16:41:11 +0200 Subject: fix markup --- docs/narr/environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index fb3c3d7e3..c8a666b90 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -212,7 +212,7 @@ sequence can take several different forms. package1 package2 package3 - The package names can also be separated by carriage returns:: + The package names can also be separated by carriage returns:: package1 package2 -- cgit v1.2.3 From 70b951b47c31af883aa7a6a5853d9265db7f6fdb Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 17:06:04 +0200 Subject: improve readability --- docs/narr/environment.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index fb3c3d7e3..1ac59bfb6 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -666,9 +666,9 @@ Here's how: def includeme(config): settings = config.registry.settings debug_frobnosticator = settings['debug_frobnosticator'] - -- 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 + +- 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: -- cgit v1.2.3 From f73f0e332658fac2583f51247dcd49bd36d63ce4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Mar 2013 23:05:17 +0200 Subject: consistency: use $VENV whenever virtualenv binaries are used --- docs/narr/environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 35bfddb8d..e059acc4e 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -546,7 +546,7 @@ for settings documented as such. For example, you might start your .. code-block:: text $ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \ - bin/pserve MyProject.ini + $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 -- cgit v1.2.3 From 125ea45ae864a5513e6d83fdded6ceea9516b578 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 6 Apr 2013 07:07:37 +0200 Subject: fix some cross-references Also, pyramid_zcml is cross-referenced, so add it to intersphinx_mapping dict. --- docs/narr/environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index e059acc4e..f0c0c18fe 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -302,7 +302,7 @@ 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.Configuration.include`. +: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 -- cgit v1.2.3 From 2033eeb3602f330930585678aac926749b9c22f7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 10 Feb 2014 03:22:33 -0600 Subject: - Garden PR #1121 --- docs/narr/environment.rst | 38 ++++++++++++++++++++++++++++++-------- 1 file changed, 30 insertions(+), 8 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index f0c0c18fe..412635f08 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -59,8 +59,11 @@ third-party template rendering extensions. 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 | @@ -79,7 +82,11 @@ Debugging Authorization ----------------------- Print view authorization failure and success information to stderr -when this value is true. See also :ref:`debug_authorization_section`. +when this value is true. + +.. seealso:: + + See also :ref:`debug_authorization_section`. +---------------------------------+-----------------------------------+ | Environment Variable Name | Config File Setting Name | @@ -94,7 +101,11 @@ Debugging Not Found Errors -------------------------- Print view-related ``NotFound`` debug messages to stderr -when this value is true. See also :ref:`debug_notfound_section`. +when this value is true. + +.. seealso:: + + See also :ref:`debug_notfound_section`. +---------------------------------+------------------------------+ | Environment Variable Name | Config File Setting Name | @@ -109,7 +120,11 @@ 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 | @@ -128,7 +143,11 @@ 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. See also :ref:`influencing_http_caching`. +feature when this is true. + +.. seealso:: + + See also :ref:`influencing_http_caching`. +---------------------------------+----------------------------------+ | Environment Variable Name | Config File Setting Name | @@ -173,8 +192,11 @@ 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`. +:term:`locale negotiator` is not registered. + +.. seealso:: + + See also :ref:`localization_deployment_settings`. +---------------------------------+-----------------------------------+ | Environment Variable Name | Config File Setting Name | -- cgit v1.2.3 From faaed6c7cffb453aed823b80f4169e87bfbc8026 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 16 Jul 2014 10:28:47 -0500 Subject: remove mako docs that should be in pyramid_mako package --- docs/narr/environment.rst | 148 ---------------------------------------------- 1 file changed, 148 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 412635f08..7bac12ea7 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -13,7 +13,6 @@ single: reload settings single: default_locale_name single: environment variables - single: Mako environment settings single: ini file settings single: PasteDeploy settings @@ -396,153 +395,6 @@ Is equivalent to using the following statements in your configuration code: It is fine to use both or either form. -.. _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 -`_ 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 -~~~~~~~~~~~~~~~~~~ - -A callable (or a :term:`dotted Python name` which names a 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 -`_). By -default, this is ``false``. - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.strict_undefined`` | -| | -| | -| | -+-----------------------------+ - -Mako Preprocessor -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.1 - -A callable (or a :term:`dotted Python name` which names a callable) which is -called to preprocess the source before the template is called. The callable -will be passed the full template source before it is parsed. The return -result of the callable will be used as the template source code. - - -+-----------------------------+ -| Config File Setting Name | -+=============================+ -| ``mako.preprocessor`` | -| | -| | -| | -+-----------------------------+ - Examples -------- -- cgit v1.2.3 From 6596304446f8369dfbcf264d143fe85d75832dba Mon Sep 17 00:00:00 2001 From: Chris Rossi Date: Mon, 21 Jul 2014 16:46:35 -0400 Subject: Add 'prevent_cachebuster' setting. --- docs/narr/environment.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 412635f08..7e2f19278 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -158,6 +158,26 @@ feature when this is true. | | | +---------------------------------+----------------------------------+ +Preventing Cache Busting +------------------------ + +Prevent the ``cachebuster`` 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. + +.. seealso:: + + See also :ref:`cache_busting`. + ++---------------------------------+----------------------------------+ +| Environment Variable Name | Config File Setting Name | ++=================================+==================================+ +| ``PYRAMID_PREVENT_CACHEBUSTER`` | ``pyramid.prevent_cachebuster`` | +| | or ``prevent_cachebuster`` | +| | | +| | | ++---------------------------------+----------------------------------+ + Debugging All ------------- -- cgit v1.2.3 From 15b979413c700fbc289328b25aaa4ba1c4cbdda9 Mon Sep 17 00:00:00 2001 From: Chris Rossi Date: Thu, 24 Jul 2014 17:13:08 -0400 Subject: cachebuster -> cachebust --- docs/narr/environment.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 7e2f19278..a81ad19af 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -161,7 +161,7 @@ feature when this is true. Preventing Cache Busting ------------------------ -Prevent the ``cachebuster`` static view configuration argument from having any +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. @@ -172,8 +172,8 @@ be configured or used when this is true. +---------------------------------+----------------------------------+ | Environment Variable Name | Config File Setting Name | +=================================+==================================+ -| ``PYRAMID_PREVENT_CACHEBUSTER`` | ``pyramid.prevent_cachebuster`` | -| | or ``prevent_cachebuster`` | +| ``PYRAMID_PREVENT_CACHEBUST`` | ``pyramid.prevent_cachebust`` | +| | or ``prevent_cachebust`` | | | | | | | +---------------------------------+----------------------------------+ -- cgit v1.2.3 From 6b88bdf7680151345debec0c8651f164a149a53a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 28 Jul 2014 21:06:34 -0400 Subject: add versionadded notes --- docs/narr/environment.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/environment.rst') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index a81ad19af..e1171d710 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -165,6 +165,8 @@ 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`. -- cgit v1.2.3 From de6258689fd6a3e3d4726b6d1873fcca48e7ca02 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 17 Oct 2015 03:26:01 -0700 Subject: minor grammar, rewrap 79 cols, .rst syntax fixes --- docs/narr/environment.rst | 344 +++++++++++++++++++++------------------------- 1 file changed, 155 insertions(+), 189 deletions(-) (limited to 'docs/narr/environment.rst') 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'] - - - - -- cgit v1.2.3