diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/request.rst | 2 | ||||
| -rw-r--r-- | docs/glossary.rst | 19 | ||||
| -rw-r--r-- | docs/narr/advconfig.rst | 8 | ||||
| -rw-r--r-- | docs/narr/logging.rst | 24 | ||||
| -rw-r--r-- | docs/narr/project.rst | 20 | ||||
| -rw-r--r-- | docs/narr/startup.rst | 56 |
6 files changed, 88 insertions, 41 deletions
diff --git a/docs/api/request.rst b/docs/api/request.rst index 0c169adaf..50a34884b 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -14,7 +14,7 @@ model_url, resource_url, resource_path, set_property, effective_principals, authenticated_userid, unauthenticated_userid, has_permission, - invoke_exception_view + invoke_exception_view, localizer .. attribute:: context diff --git a/docs/glossary.rst b/docs/glossary.rst index e21ae2fdc..9c6027209 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1207,3 +1207,22 @@ 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`. + 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 <manually_resolving_conflicts>` 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 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 add-ons used, and :ref:`your own code may reference <deployment_settings>` and act on settings. + + constructor + A function returning a Pyramid :term:`WSGI` application. + Every Pyramid application has a single constructor function named ``main``. + It returns a Pyramid :term:`router` generated by a :term:`configurator`, and is written by you. + The Pyramid constructor is the application's :term:`entry point`. + diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 322741648..33edb0eae 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -168,9 +168,13 @@ 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. +The new declarations will override committed declarations. + 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: diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 7b60beda9..58bd2d4ec 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -32,19 +32,25 @@ 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 <https://docs.python.org/3.7/howto/logging.html#configuring-logging>`_. PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser format <ConfigParser>`. This is the same format used as the Python :ref:`logging module's Configuration file format <logging-config-fileformat>`. -The application-related and logging-related sections in the configuration file -can coexist peacefully, and the logging-related sections in the file are used -from when you run ``pserve``. - -The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, -a thin wrapper around the :func:`logging.config.fileConfig` using the specified -``.ini`` file, if it contains a ``[loggers]`` section (all of the -cookiecutter-generated ``.ini`` files do). ``setup_logging`` reads the logging -configuration from the ini file upon which ``pserve`` was invoked. +The application-related and logging-related sections in the configuration file can coexist peacefully. +The logging-related sections in the file configure logging when you run ``pserve``. + +.. index:: + pair: logging; startup + +If the configuration ``.ini`` file, specified when invoking ``pserve``, contains a ``[loggers]`` section then on :ref:`startup <the_startup_process>` the following process takes place: + +#. The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, passing the ``.ini`` file. + +#. ``setup_logging`` is a thin wrapper which calls the Python standard library's :func:`logging.config.fileConfig`. + +#. :func:`logging.config.fileConfig` reads the logging configuration from the ``.ini`` file and configures logging. + Default logging configuration is provided in both the default ``development.ini`` and the ``production.ini`` files. If you use our cookiecutter to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 725263407..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 @@ -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: @@ -658,12 +658,10 @@ 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 -<https://docs.python.org/2/howto/logging.html#configuring-logging>`_ 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`. +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 @@ -856,7 +854,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`. @@ -871,6 +869,10 @@ 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 <startup_settings>` and ``main``\'s :ref:`arguments <startup_constructor_arguments>` and statements. + .. index:: single: routes.py diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 90792c0ff..37825d2da 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -21,6 +21,8 @@ on your keyboard after typing ``pserve development.ini`` and the time the lines single: startup process pair: settings; .ini +.. _the_startup_process: + The Startup Process ------------------- @@ -45,10 +47,16 @@ Here's a high-level time-ordered overview of what happens when you press the :term:`PasteDeploy` library and returns a parser that can understand the format. + .. _ini_section_discovery: + #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, - ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. This - section represents the configuration of a :term:`WSGI` application that will - be served. If you're using a simple application (e.g., ``[app:main]``), the + ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. + This section configures the :term:`WSGI` webserver which serves your application. + As such it is the ``ini`` section for your application and can be the source for many of your application's :term:`settings`. + + .. _entry_point_discovery: + + If you're using a simple application (e.g., ``[app:main]``), the application's ``paste.app_factory`` :term:`entry point` will be named on the ``use=`` line within the section's configuration. If instead of a simple application, you're using a WSGI :term:`pipeline` (e.g., a @@ -61,17 +69,20 @@ Here's a high-level time-ordered overview of what happens when you press will have a single ``[app:main]`` section in it, and this will be the application served. + .. index:: + pair: logging; startup + + .. _startup_logging_initialization: + #. The framework finds all :mod:`logging` related configuration in the ``.ini`` file and uses it to configure the Python standard library logging system for - this application. See :ref:`logging_config` for more information. + the application. See :ref:`logging_config` for more information. -#. The application's *constructor* named by the entry point referenced on the - ``use=`` line of the section representing your :app:`Pyramid` application is - passed the key/value parameters mentioned within the section in which it's - defined. The constructor is meant to return a :term:`router` instance, - which is a :term:`WSGI` application. +#. The application's entry point, usually the entry point referenced on the :ref:`above mentioned <entry_point_discovery>` ``use=`` line, is the application's :term:`constructor`. + It is passed the key/value parameters in :ref:`the application's .ini section <ini_section_discovery>`. + The constructor should return a :term:`router` instance, which is a :term:`WSGI` application. - For :app:`Pyramid` applications, the constructor will be a function named + For :app:`Pyramid` applications, the constructor is a function named ``main`` in the ``__init__.py`` file within the :term:`package` in which your application lives. If this function succeeds, it will return a :app:`Pyramid` :term:`router` instance. Here's the contents of an example @@ -81,6 +92,12 @@ 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, which is a dictionary of key/value pairs mentioned in the ``[DEFAULT]`` section of an ``.ini`` file (if :ref:`[DEFAULT] @@ -106,15 +123,17 @@ 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, passing the ``settings`` - dictionary captured via the ``**settings`` kwarg as 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: 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``, ``pyramid.debug_authorization``, etc. + It is :ref:`available for use <deployment_settings>` 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. @@ -158,9 +177,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 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. |