From 87c8da5865c001ff0ca9ef2c923e26e323ccfcde Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 29 Oct 2018 13:39:31 -0500 Subject: Describe the points at which ini files are processed --- docs/narr/project.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 725263407..218545193 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -611,6 +611,8 @@ The generated ``development.ini`` file looks like so: This file contains several sections including ``[app:main]``, ``[server:main]``, and several other sections related to logging configuration. +.. _app_main: + The ``[app:main]`` section represents configuration for your :app:`Pyramid` application. The ``use`` setting is the only setting required to be present in the ``[app:main]`` section. Its default value, ``egg:myproject``, indicates @@ -834,6 +836,11 @@ Pyramid developers can get up to speed quickly on your code when you need help. .. index:: single: __init__.py + single: ini file processing + pair: conflict resolution; ini file + pair: add-on; configuration + pair: logging; configuration + pair: PasteDeploy; configuration .. _init_py: @@ -856,12 +863,16 @@ also informs Python that the directory which contains it is a *package*. WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. - Within this function, application configuration is performed. + Before ``main`` is called :term:`PasteDeploy` :ref:`configures logging `. + Within ``main`` further application configuration is performed. Line 7 opens a context manager with an instance of a :term:`Configurator`. + This applies lines in the ``.ini`` file to ``config``, the configuration returned by :term:`Configurator`. + Only those lines in :ref:`[app:main] ` which are understood by :app:`Pyramid` are applied, such as ``pyramid.includes = pyramid_debugtoolbar``. - Line 8 adds support for Jinja2 templating bindings, allowing us to - specify renderers with the ``.jinja2`` extension. + Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. + The expectation is that the add-on applies what is relevant in the ``.ini`` file at this point. + Consult your add-on's documentation. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From 9ef620f65721aa8474e8bde2e6b13673ed980f73 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 30 Oct 2018 12:56:44 -0500 Subject: mmerickel noted that add-ons may not get their settings from .ini files Also, remove detail about Configurator returning a configuration. --- docs/narr/project.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 218545193..11302fcf9 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -867,12 +867,12 @@ also informs Python that the directory which contains it is a *package*. Within ``main`` further application configuration is performed. Line 7 opens a context manager with an instance of a :term:`Configurator`. - This applies lines in the ``.ini`` file to ``config``, the configuration returned by :term:`Configurator`. + This applies lines in the ``.ini`` file. Only those lines in :ref:`[app:main] ` which are understood by :app:`Pyramid` are applied, such as ``pyramid.includes = pyramid_debugtoolbar``. - Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. - The expectation is that the add-on applies what is relevant in the ``.ini`` file at this point. - Consult your add-on's documentation. + Line 8 adds support for Jinja2 templating bindings. + Settings are applied to the configuration allowing us to specify renderers with the ``.jinja2`` extension. + These settings are add-on dependent and may come from the ``.ini`` file or from elsewhere. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From d5efd3c665952e67953405b794d0e2bb02689a86 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 30 Oct 2018 13:05:51 -0500 Subject: Remove unnecessary words --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 11302fcf9..9fde7918f 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -872,7 +872,7 @@ also informs Python that the directory which contains it is a *package*. Line 8 adds support for Jinja2 templating bindings. Settings are applied to the configuration allowing us to specify renderers with the ``.jinja2`` extension. - These settings are add-on dependent and may come from the ``.ini`` file or from elsewhere. + The source of these settings are add-on dependent. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From 7741aaa13bb266f5822b742bb5fda5cbc41d77c9 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 18:52:27 -0600 Subject: Revert "Remove unnecessary words" This reverts commit d5efd3c665952e67953405b794d0e2bb02689a86. --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9fde7918f..11302fcf9 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -872,7 +872,7 @@ also informs Python that the directory which contains it is a *package*. Line 8 adds support for Jinja2 templating bindings. Settings are applied to the configuration allowing us to specify renderers with the ``.jinja2`` extension. - The source of these settings are add-on dependent. + These settings are add-on dependent and may come from the ``.ini`` file or from elsewhere. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From 6cb6e15090e527250d41df81dc4a56c56114b3a3 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 18:52:39 -0600 Subject: Revert "mmerickel noted that add-ons may not get their settings from .ini files" This reverts commit 9ef620f65721aa8474e8bde2e6b13673ed980f73. --- docs/narr/project.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 11302fcf9..218545193 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -867,12 +867,12 @@ also informs Python that the directory which contains it is a *package*. Within ``main`` further application configuration is performed. Line 7 opens a context manager with an instance of a :term:`Configurator`. - This applies lines in the ``.ini`` file. + This applies lines in the ``.ini`` file to ``config``, the configuration returned by :term:`Configurator`. Only those lines in :ref:`[app:main] ` which are understood by :app:`Pyramid` are applied, such as ``pyramid.includes = pyramid_debugtoolbar``. - Line 8 adds support for Jinja2 templating bindings. - Settings are applied to the configuration allowing us to specify renderers with the ``.jinja2`` extension. - These settings are add-on dependent and may come from the ``.ini`` file or from elsewhere. + Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. + The expectation is that the add-on applies what is relevant in the ``.ini`` file at this point. + Consult your add-on's documentation. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From d9e378525bdce3feab8d842fe73afc1a5462f8d4 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 18:52:43 -0600 Subject: Revert "Describe the points at which ini files are processed" This reverts commit 87c8da5865c001ff0ca9ef2c923e26e323ccfcde. --- docs/narr/project.rst | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 218545193..725263407 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -611,8 +611,6 @@ The generated ``development.ini`` file looks like so: This file contains several sections including ``[app:main]``, ``[server:main]``, and several other sections related to logging configuration. -.. _app_main: - The ``[app:main]`` section represents configuration for your :app:`Pyramid` application. The ``use`` setting is the only setting required to be present in the ``[app:main]`` section. Its default value, ``egg:myproject``, indicates @@ -836,11 +834,6 @@ Pyramid developers can get up to speed quickly on your code when you need help. .. index:: single: __init__.py - single: ini file processing - pair: conflict resolution; ini file - pair: add-on; configuration - pair: logging; configuration - pair: PasteDeploy; configuration .. _init_py: @@ -863,16 +856,12 @@ also informs Python that the directory which contains it is a *package*. WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. - Before ``main`` is called :term:`PasteDeploy` :ref:`configures logging `. - Within ``main`` further application configuration is performed. + Within this function, application configuration is performed. Line 7 opens a context manager with an instance of a :term:`Configurator`. - This applies lines in the ``.ini`` file to ``config``, the configuration returned by :term:`Configurator`. - Only those lines in :ref:`[app:main] ` which are understood by :app:`Pyramid` are applied, such as ``pyramid.includes = pyramid_debugtoolbar``. - Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. - The expectation is that the add-on applies what is relevant in the ``.ini`` file at this point. - Consult your add-on's documentation. + Line 8 adds support for Jinja2 templating bindings, allowing us to + specify renderers with the ``.jinja2`` extension. Line 9 includes the ``routes.py`` module. -- cgit v1.2.3 From 9d194007b15c67698adf66c0b94aba1f617a7a6a Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 20:56:56 -0600 Subject: Simplify sentence --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 725263407..89cebd063 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -856,7 +856,7 @@ also informs Python that the directory which contains it is a *package*. WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. - Within this function, application configuration is performed. + The ``main`` function configures the application. Line 7 opens a context manager with an instance of a :term:`Configurator`. -- cgit v1.2.3 From 807d5c77801e3d038aa21151235e91496b70fb84 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 21:13:11 -0600 Subject: Link to startup docs for more detail --- docs/narr/project.rst | 2 ++ docs/narr/startup.rst | 8 +++++++- 2 files changed, 9 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 89cebd063..3522ea964 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -871,6 +871,8 @@ also informs Python that the directory which contains it is a *package*. Line 11 returns a :term:`WSGI` application to the caller of the function (Pyramid's pserve). + See :ref:`the_startup_process` for more about the application's :ref:`settings ` and ``main``\'s :ref:`arguments ` and statements. + .. index:: single: routes.py diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 90792c0ff..be708dfc7 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -18,9 +18,11 @@ on your keyboard after typing ``pserve development.ini`` and the time the lines ``Serving on http://localhost:6543`` are output to your console. .. index:: - single: startup process + single: startup pair: settings; .ini +.. _the_startup_process: + The Startup Process ------------------- @@ -81,6 +83,8 @@ Here's a high-level time-ordered overview of what happens when you press :language: python :linenos: + .. _startup_constructor_arguments: + Note that the constructor function accepts a ``global_config`` argument, which is a dictionary of key/value pairs mentioned in the ``[DEFAULT]`` section of an ``.ini`` file (if :ref:`[DEFAULT] @@ -111,6 +115,8 @@ Here's a high-level time-ordered overview of what happens when you press dictionary captured via the ``**settings`` kwarg as its ``settings`` argument. + .. _startup_settings: + The ``settings`` dictionary contains all the options in the ``[app:main]`` section of our .ini file except the ``use`` option (which is internal to PasteDeploy) such as ``pyramid.reload_templates``, -- cgit v1.2.3 From 33a1ec755a5e128224f31550ae04462d225ca9fc Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 22:13:06 -0600 Subject: More index entries for ini files and configuration --- docs/narr/startup.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index be708dfc7..95673051e 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -83,6 +83,10 @@ Here's a high-level time-ordered overview of what happens when you press :language: python :linenos: + .. index:: + single: ini file + pair: PasteDeploy; configuration + .. _startup_constructor_arguments: Note that the constructor function accepts a ``global_config`` argument, -- cgit v1.2.3 From 3f01e1f615041aa0e6787e1c6ba2f9c54d139100 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:14:49 -0600 Subject: Fix so sentence has the right meaning --- docs/narr/advconfig.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 322741648..f6a6c5b42 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -169,8 +169,8 @@ Using ``config.commit()`` You can manually commit a configuration by using the :meth:`~pyramid.config.Configurator.commit` method between configuration calls. For example, we prevent conflicts from occurring in the application we examined -previously as the result of adding a ``commit``. Here's the application that -generates conflicts: +previously by adding a ``commit``. +Here's the application that generates conflicts: .. code-block:: python :linenos: -- cgit v1.2.3 From 084cdc68d27299a3aaf6f9a2464dd5b99fbb9947 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:16:20 -0600 Subject: Note what directive takes effect when conflits are resolved with commit() --- docs/narr/advconfig.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index f6a6c5b42..0d583029e 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -168,6 +168,8 @@ Using ``config.commit()`` You can manually commit a configuration by using the :meth:`~pyramid.config.Configurator.commit` method between configuration calls. +After a commit :term:`configuration declaration`\s which would otherwise result in a conflict may be added to a :term:`configurator` and will override previously committed directives. + For example, we prevent conflicts from occurring in the application we examined previously by adding a ``commit``. Here's the application that generates conflicts: -- cgit v1.2.3 From 11953e10b6fb9832196b0fdab28dd53f771c3eab Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:18:01 -0600 Subject: Add "commit" to the glossary --- docs/glossary.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index f42b298df..649daf79e 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1207,3 +1207,7 @@ Glossary route prefix A route prefix is a path prefix that is prepended to any routes that are configured while it is active. A route prefix can be set via :meth:`pyramid.config.Configurator.include` or :meth:`pyramid.config.Configurator.route_prefix_context`. + + commit + An operation applied to a :term:`configurator` which checks for conflicts in :term:`configuration declaration`\s, and if none are found applies all pending :term:`action`\s. + It is possible, although not necessarily recommended, to invoke :term:`commit`\s using :meth:`pyramid.config.Configurator.commit` to :ref:`manually resolve ` configuration conflicts. -- cgit v1.2.3 From 401cf69020b888bf5343e211871a42d59494abd1 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:19:23 -0600 Subject: More explaination of calling Configurator() --- docs/narr/startup.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 95673051e..5582f5ff4 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -115,9 +115,8 @@ Here's a high-level time-ordered overview of what happens when you press for the meanings of these keys. #. The ``main`` function first constructs a - :class:`~pyramid.config.Configurator` instance, passing the ``settings`` - dictionary captured via the ``**settings`` kwarg as its ``settings`` - argument. + :class:`~pyramid.config.Configurator` instance. + It holds the application's settings and is able to :term:`commit` any :term:`configuration declaration`\s the settings contain because the dictionary captured via the ``**settings`` kwarg is passed to the :class:`~pyramid.config.Configurator` in its``settings`` argument. .. _startup_settings: -- cgit v1.2.3 From 1ec0ca5c5325953adb4e96313f7ff8bbedb87e13 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:36:44 -0600 Subject: Move sentence from project docs to logging docs --- docs/narr/logging.rst | 1 + docs/narr/project.rst | 6 ++---- 2 files changed, 3 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 7b60beda9..c8b3c0041 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -32,6 +32,7 @@ you to send messages to :mod:`Python standard library logging package :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created when you use our cookiecutter include a basic configuration for the Python :mod:`logging` package. +These ini file sections are passed to the `logging module's config file configuration engine `_. PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser format `. This is the same format used as the Python diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 3522ea964..d84b740e3 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -658,10 +658,8 @@ only (``127.0.0.1``). .. _myproject_ini_logging: The sections after ``# logging configuration`` represent Python's standard -library :mod:`logging` module configuration for your application. These -sections are passed to the `logging module's config file configuration engine -`_ when the -``pserve`` or ``pshell`` commands are executed. The default configuration +library :mod:`logging` module configuration for your application. +The default configuration sends application logging output to the standard error output of your terminal. For more information about logging configuration, see :ref:`logging_chapter`. -- cgit v1.2.3 From 1ce9ea211e266d85ed0f62be9553b27e91073ef1 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:37:08 -0600 Subject: Update to point to latest python docs --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index c8b3c0041..92006ab51 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -32,7 +32,7 @@ you to send messages to :mod:`Python standard library logging package :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created when you use our cookiecutter include a basic configuration for the Python :mod:`logging` package. -These ini file sections are passed to the `logging module's config file configuration engine `_. +These ini file sections are passed to the `logging module's config file configuration engine `_. PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser format `. This is the same format used as the Python -- cgit v1.2.3 From 6faa22ebcd16fd69d82b756907693f43b0cc29f1 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 18 Nov 2018 23:42:34 -0600 Subject: Shorten sentence --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index d84b740e3..81fe4032c 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -661,7 +661,7 @@ The sections after ``# logging configuration`` represent Python's standard library :mod:`logging` module configuration for your application. The default configuration sends application logging output to the standard error output of your terminal. -For more information about logging configuration, see :ref:`logging_chapter`. +For more information see :ref:`logging_chapter`. See the :term:`PasteDeploy` documentation for more information about other types of things you can put into this ``.ini`` file, such as other -- cgit v1.2.3 From 481ff76158333826f1de599c3b76e81981a2e8f0 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 00:41:20 -0600 Subject: Make index entries for statup distinct --- docs/narr/project.rst | 2 +- docs/narr/startup.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 81fe4032c..a5433b278 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -297,7 +297,7 @@ path to the module on which we want to run tests and coverage. single: running an application single: pserve single: reload - single: startup + single: starting .. _running_the_project_application: diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 5582f5ff4..5db45458d 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -18,7 +18,7 @@ on your keyboard after typing ``pserve development.ini`` and the time the lines ``Serving on http://localhost:6543`` are output to your console. .. index:: - single: startup + single: startup process pair: settings; .ini .. _the_startup_process: -- cgit v1.2.3 From 0435a459de25acb087881e8bf3b0e21aa8fca5fb Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 07:44:54 -0600 Subject: Shorter sentences are better --- docs/glossary.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 649daf79e..0ff87a5ee 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1209,5 +1209,6 @@ Glossary A route prefix can be set via :meth:`pyramid.config.Configurator.include` or :meth:`pyramid.config.Configurator.route_prefix_context`. commit - An operation applied to a :term:`configurator` which checks for conflicts in :term:`configuration declaration`\s, and if none are found applies all pending :term:`action`\s. + An operation applied to a :term:`configurator`. + A commit checks for conflicts in :term:`configuration declaration`\s, and if none are found applies all pending :term:`action`\s. It is possible, although not necessarily recommended, to invoke :term:`commit`\s using :meth:`pyramid.config.Configurator.commit` to :ref:`manually resolve ` configuration conflicts. -- cgit v1.2.3 From 34009af1bea519367d69c69e05c1af4df957db46 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 08:15:12 -0600 Subject: Shorter sentences are better --- docs/narr/advconfig.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 0d583029e..4c969487c 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -168,7 +168,8 @@ Using ``config.commit()`` You can manually commit a configuration by using the :meth:`~pyramid.config.Configurator.commit` method between configuration calls. -After a commit :term:`configuration declaration`\s which would otherwise result in a conflict may be added to a :term:`configurator` and will override previously committed directives. +After a commit more :term:`configuration declaration`\s may be added to a :term:`configurator`. +New declarations will not conflict with committed declarations, they will override them. For example, we prevent conflicts from occurring in the application we examined previously by adding a ``commit``. -- cgit v1.2.3 From 52312cec91f3570fb862eadc9e43cdd5702afcc5 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 08:17:20 -0600 Subject: Consitent use of .ini --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 92006ab51..2acdb33f4 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -32,7 +32,7 @@ you to send messages to :mod:`Python standard library logging package :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created when you use our cookiecutter include a basic configuration for the Python :mod:`logging` package. -These ini file sections are passed to the `logging module's config file configuration engine `_. +These ``.ini`` file sections are passed to the `logging module's config file configuration engine `_. PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser format `. This is the same format used as the Python -- cgit v1.2.3 From fecab4645f4f546aaa5e9aa69ea31fea1ffa2446 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 08:22:12 -0600 Subject: Put reference to startup in a seealso --- docs/narr/project.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index a5433b278..69e80fcfb 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -869,6 +869,8 @@ also informs Python that the directory which contains it is a *package*. Line 11 returns a :term:`WSGI` application to the caller of the function (Pyramid's pserve). +.. seealso:: + See :ref:`the_startup_process` for more about the application's :ref:`settings ` and ``main``\'s :ref:`arguments ` and statements. -- cgit v1.2.3 From 55b6122999b900b6f505dd9f7afbc91e2f22470b Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 09:31:48 -0600 Subject: One sentence per line --- docs/narr/startup.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 5db45458d..138ddbe67 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -167,9 +167,6 @@ Here's a high-level time-ordered overview of what happens when you press Deployment Settings ------------------- -Note that an augmented version of the values passed as ``**settings`` to the -:class:`~pyramid.config.Configurator` constructor will be available in -:app:`Pyramid` :term:`view callable` code as ``request.registry.settings``. You -can create objects you wish to access later from view code, and put them into -the dictionary you pass to the configurator as ``settings``. They will then be -present in the ``request.registry.settings`` dictionary at application runtime. +Note that an augmented version of the values passed as ``**settings`` to the :class:`~pyramid.config.Configurator` constructor will be available in :app:`Pyramid` :term:`view callable` code as ``request.registry.settings``. +You can create objects you wish to access later from view code, and put them into the dictionary you pass to the configurator as ``settings``. +They will then be present in the ``request.registry.settings`` dictionary at application runtime. -- cgit v1.2.3 From 617c68524a30fd32b742d7124b180e77845cc2da Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 09:32:46 -0600 Subject: Change from future to present tense --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 138ddbe67..65e74b262 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -167,6 +167,6 @@ Here's a high-level time-ordered overview of what happens when you press Deployment Settings ------------------- -Note that an augmented version of the values passed as ``**settings`` to the :class:`~pyramid.config.Configurator` constructor will be available in :app:`Pyramid` :term:`view callable` code as ``request.registry.settings``. +Note that an augmented version of the values passed as ``**settings`` to the :class:`~pyramid.config.Configurator` constructor is available in :app:`Pyramid` :term:`view callable` code as ``request.registry.settings``. You can create objects you wish to access later from view code, and put them into the dictionary you pass to the configurator as ``settings``. They will then be present in the ``request.registry.settings`` dictionary at application runtime. -- cgit v1.2.3 From d03e047c7e4e7cf79b84116379dddf0b82bdbfca Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 10:23:18 -0600 Subject: Add "settings" to the glossary --- docs/glossary.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 0ff87a5ee..ae10ad272 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1212,3 +1212,9 @@ Glossary An operation applied to a :term:`configurator`. A commit checks for conflicts in :term:`configuration declaration`\s, and if none are found applies all pending :term:`action`\s. It is possible, although not necessarily recommended, to invoke :term:`commit`\s using :meth:`pyramid.config.Configurator.commit` to :ref:`manually resolve ` configuration conflicts. + + settings + Settings control the runtime behavior of a Pyramid application. + They are the aggregation of configuration file declarations, process environment values, other additions generated by Pyramid or its plugins and :term:`tween`\s, and values produced by your own code during application initialization. + Settings can affect all the components which make up the the application. + Pyramid itself, any tweens or Pyramid plugins used, and :ref:`your own code may reference ` and act on settings. -- cgit v1.2.3 From 1a36d9a0d1295cc8c9e95e2ccc6d7f182f451792 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 10:25:20 -0600 Subject: Shorter sentences are better --- docs/narr/startup.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 65e74b262..8e637f64c 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -114,9 +114,9 @@ Here's a high-level time-ordered overview of what happens when you press pyramid.includes = pyramid_debugtoolbar}``. See :ref:`environment_chapter` for the meanings of these keys. -#. The ``main`` function first constructs a - :class:`~pyramid.config.Configurator` instance. - It holds the application's settings and is able to :term:`commit` any :term:`configuration declaration`\s the settings contain because the dictionary captured via the ``**settings`` kwarg is passed to the :class:`~pyramid.config.Configurator` in its``settings`` argument. +#. The ``main`` function begins by making a :term:`configurator`. + The dictionary captured via the ``**settings`` kwarg is passed to the :class:`~pyramid.config.Configurator` constructor in its ``settings`` argument. + The new configurator holds the application's :term:`settings` and is able to :term:`commit` any :term:`configuration declaration`\s the settings contain. .. _startup_settings: -- cgit v1.2.3 From 8d2a89f53c99634443af5407fb8d1078d14c51d7 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 10:25:51 -0600 Subject: The point of knowing what's in settings is to be able to use them --- docs/narr/startup.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 8e637f64c..17926c716 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -124,6 +124,7 @@ Here's a high-level time-ordered overview of what happens when you press section of our .ini file except the ``use`` option (which is internal to PasteDeploy) such as ``pyramid.reload_templates``, ``pyramid.debug_authorization``, etc. + It is :ref:`available for use ` in your code. #. The ``main`` function then calls various methods on the instance of the class :class:`~pyramid.config.Configurator` created in the previous step. -- cgit v1.2.3 From bf266438734bb93c9ff518b733ce7671a4eb111c Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 11:59:05 -0600 Subject: Clarify that settings are set at startup --- docs/glossary.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index ae10ad272..15a144898 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1215,6 +1215,7 @@ Glossary settings Settings control the runtime behavior of a Pyramid application. - They are the aggregation of configuration file declarations, process environment values, other additions generated by Pyramid or its plugins and :term:`tween`\s, and values produced by your own code during application initialization. - Settings can affect all the components which make up the the application. + They are the aggregation of configuration file declarations, process environment values, other additions generated by Pyramid or its plugins and :term:`tween`\s, and values produced by your own code. + Settings are collected at application startup. + They can affect all the components which make up the the application. Pyramid itself, any tweens or Pyramid plugins used, and :ref:`your own code may reference ` and act on settings. -- cgit v1.2.3 From 5fc9ed4bed9d0a80009a5cf5d3d191d535b8150f Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 11:59:37 -0600 Subject: Link to "settings" glossary entry when settings are first introduced --- docs/narr/project.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 69e80fcfb..14f0d083e 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -139,8 +139,8 @@ or install your application for deployment or development. An ``.ini`` file named ``development.ini`` will be created in the project directory. You will use this ``.ini`` file to configure a server, to run your -application, and to debug your application. It contains configuration that -enables an interactive debugger and settings optimized for development. +application, and to debug your application. +It contains configuration that enables an interactive debugger and :term:`settings` optimized for development. Another ``.ini`` file named ``production.ini`` will also be created in the project directory. It contains configuration that disables any interactive -- cgit v1.2.3 From ebe4a2418ca55533fc7d20ac57f2cf727318b23d Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Mon, 19 Nov 2018 12:07:06 -0600 Subject: Link to "settings" golssary term at first occurance in narrative docs --- docs/narr/firstapp.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 917482976..6769c0d38 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -190,9 +190,8 @@ WSGI Application Creation After configuring views and ending configuration, the script creates a WSGI *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app` method. -A call to ``make_wsgi_app`` implies that all configuration is finished -(meaning all method calls to the configurator, which sets up views and various -other configuration settings, have been performed). The ``make_wsgi_app`` +A call to ``make_wsgi_app`` implies that all configuration is finished (meaning all method calls to the configurator, which sets up views and various other configuration :term:`settings`, have been performed). +The ``make_wsgi_app`` method returns a :term:`WSGI` application object that can be used by any WSGI server to present an application to a requestor. :term:`WSGI` is a protocol that allows servers to talk to Python applications. We don't discuss -- cgit v1.2.3 From 0929046410929b332bdcfac2f362dd3c0f16445c Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 20 Nov 2018 06:25:14 -0600 Subject: Pyrmaid has add-ons, not plugins --- docs/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 15a144898..7f396dc7d 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1215,7 +1215,7 @@ Glossary settings Settings control the runtime behavior of a Pyramid application. - They are the aggregation of configuration file declarations, process environment values, other additions generated by Pyramid or its plugins and :term:`tween`\s, and values produced by your own code. + They are the aggregation of configuration file declarations, process environment values, other additions generated by Pyramid or its add-ons and :term:`tween`\s, and values produced by your own code. Settings are collected at application startup. They can affect all the components which make up the the application. - Pyramid itself, any tweens or Pyramid plugins used, and :ref:`your own code may reference ` and act on settings. + Pyramid itself, any tweens or Pyramid add-ons used, and :ref:`your own code may reference ` and act on settings. -- cgit v1.2.3 From 1c83f5359a0d049b9a8587d016cb118e649edfdf Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 20 Nov 2018 07:48:31 -0600 Subject: Add comma per Steve Piercy --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 4c969487c..e0ced10f0 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -168,7 +168,7 @@ Using ``config.commit()`` You can manually commit a configuration by using the :meth:`~pyramid.config.Configurator.commit` method between configuration calls. -After a commit more :term:`configuration declaration`\s may be added to a :term:`configurator`. +After a commit, more :term:`configuration declaration`\s may be added to a :term:`configurator`. New declarations will not conflict with committed declarations, they will override them. For example, we prevent conflicts from occurring in the application we examined -- cgit v1.2.3 From 7414c862e8be7f4267e0e5ba7fc30e123f65a816 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 20 Nov 2018 07:48:50 -0600 Subject: Split into 2 sentences --- docs/narr/advconfig.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index e0ced10f0..33edb0eae 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -169,7 +169,8 @@ Using ``config.commit()`` You can manually commit a configuration by using the :meth:`~pyramid.config.Configurator.commit` method between configuration calls. After a commit, more :term:`configuration declaration`\s may be added to a :term:`configurator`. -New declarations will not conflict with committed declarations, they will override them. +New declarations will not conflict with committed declarations. +The new declarations will override committed declarations. For example, we prevent conflicts from occurring in the application we examined previously by adding a ``commit``. -- cgit v1.2.3 From d9e13bef1c8252f65febfdda5eae341eba987c9a Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Wed, 21 Nov 2018 15:14:51 -0600 Subject: Revert "Link to "settings" golssary term at first occurance in narrative docs" This reverts commit ebe4a2418ca55533fc7d20ac57f2cf727318b23d. --- docs/narr/firstapp.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 6769c0d38..917482976 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -190,8 +190,9 @@ WSGI Application Creation After configuring views and ending configuration, the script creates a WSGI *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app` method. -A call to ``make_wsgi_app`` implies that all configuration is finished (meaning all method calls to the configurator, which sets up views and various other configuration :term:`settings`, have been performed). -The ``make_wsgi_app`` +A call to ``make_wsgi_app`` implies that all configuration is finished +(meaning all method calls to the configurator, which sets up views and various +other configuration settings, have been performed). The ``make_wsgi_app`` method returns a :term:`WSGI` application object that can be used by any WSGI server to present an application to a requestor. :term:`WSGI` is a protocol that allows servers to talk to Python applications. We don't discuss -- cgit v1.2.3