diff options
Diffstat (limited to 'docs/narr/environment.rst')
| -rw-r--r-- | docs/narr/environment.rst | 201 |
1 files changed, 193 insertions, 8 deletions
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 6465c2a1e..2f5555840 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -185,6 +185,191 @@ 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` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 + +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 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 @@ -198,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: @@ -214,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 @@ -231,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 @@ -247,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 @@ -265,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. @@ -279,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. @@ -296,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 @@ -313,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 |