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/paste.rst | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/narr/paste.rst (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst new file mode 100644 index 000000000..39ae4f373 --- /dev/null +++ b/docs/narr/paste.rst @@ -0,0 +1,99 @@ +.. _paste_chapter: + +Paste +===== + +Packages generated via a :term:`scaffold` make use of a system created by Ian +Bicking named :term:`Paste`. Paste provides the following features: + +- A way to declare :term:`WSGI` application configuration in an ``.ini`` file + (PasteDeploy). + +- A :term:`WSGI` server runner (``paster serve``) which can accept + PasteDeploy ``.ini`` file values as input. + +- A mechanism for rendering scaffolds into projects (``paster create``). + +Paste is not a particularly integral part of Pyramid. It's more or less used +directly only in projects created from scaffolds. It's possible to create a +Pyramid application which does not use Paste at all. We show a Pyramid +application that doesn't use Paste in :ref:`firstapp_chapter`. However, all +Pyramid scaffolds use the system, to provide new developers with a +standardized way of starting, stopping, and setting deployment values. This +chapter is not a replacement for documentation about Paste or PasteDeploy; it +only contextualizes the use of Paste within Pyramid. For detailed +documentation, see http://pythonpaste.org. + +PasteDeploy +----------- + +:term:`PasteDeploy` is the system that Pyramid uses to allow +:term:`deployment settings` to be spelled using an ``.ini`` configuration +file format. It also allows the ``paster serve`` command to work. Its +configuration format provides a convenient place to define application +:term:`deployment settings` and WSGI server settings, and its server runner +allows you to stop and start a Pyramid application easily. + +.. _pastedeploy_entry_points: + +Entry Points and PasteDeploy ``.ini`` Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the :ref:`project_narr` chapter, we breezed over the meaning of a +configuration line in the ``deployment.ini`` file. This was the ``use = +egg:MyProject`` line in the ``[app:main]`` section. We breezed over it +because it's pretty confusing and "too much information" for an introduction +to the system. We'll try to give it a bit of attention here. Let's see the +config file again: + +.. literalinclude:: MyProject/development.ini + :language: ini + :linenos: + +The line in ``[app:main]`` above that says ``use = egg:MyProject`` is +actually shorthand for a longer spelling: ``use = egg:MyProject#main``. The +``#main`` part is omitted for brevity, as ``#main`` is a default defined by +PasteDeploy. ``egg:MyProject#main`` is a string which has meaning to +PasteDeploy. It points at a :term:`setuptools` :term:`entry point` named +``main`` defined in the ``MyProject`` project. + +Take a look at the generated ``setup.py`` file for this project. + +.. literalinclude:: MyProject/setup.py + :language: python + :linenos: + +Note that the ``entry_point`` line in ``setup.py`` points at a string which +looks a lot like an ``.ini`` file. This string representation of an ``.ini`` +file has a section named ``[paste.app_factory]``. Within this section, there +is a key named ``main`` (the entry point name) which has a value +``myproject:main``. The *key* ``main`` is what our ``egg:MyProject#main`` +value of the ``use`` section in our config file is pointing at, although it +is actually shortened to ``egg:MyProject`` there. The value represents a +:term:`dotted Python name` path, which refers to a callable in our +``myproject`` package's ``__init__.py`` module. + +The ``egg:`` prefix in ``egg:MyProject`` indicates that this is an entry +point *URI* specifier, where the "scheme" is "egg". An "egg" is created when +you run ``setup.py install`` or ``setup.py develop`` within your project. + +In English, this entry point can thus be referred to as a "Paste application +factory in the ``MyProject`` project which has the entry point named ``main`` +where the entry point refers to a ``main`` function in the ``mypackage`` +module". Indeed, if you open up the ``__init__.py`` module generated within +any scaffold-generated package, you'll see a ``main`` function. This is the +function called by :term:`PasteDeploy` when the ``paster serve`` command is +invoked against our application. It accepts a global configuration object +and *returns* an instance of our application. + +``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can add a ``[DEFAULT]`` section to your PasteDeploy ``.ini`` file. Such +a section should consists of global parameters that are shared by all the +applications, servers and :term:`middleware` defined within the configuration +file. The values in a ``[DEFAULT]`` section will be passed to your +application's ``main`` function as ``global_config`` (see the reference to +the ``main`` function in :ref:`init_py`). + + -- cgit v1.2.3 From cfb2b5596b8ef366aeef3bce5b61eafc7a2f175d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Oct 2011 03:05:29 -0400 Subject: remove all reference to the paster command-line utility --- docs/narr/paste.rst | 45 ++++++++++++++++++++++----------------------- 1 file changed, 22 insertions(+), 23 deletions(-) (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index 39ae4f373..5c7d4c3fb 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -1,26 +1,25 @@ .. _paste_chapter: -Paste -===== +PasteDeploy Configuration Files +=============================== Packages generated via a :term:`scaffold` make use of a system created by Ian -Bicking named :term:`Paste`. Paste provides the following features: - -- A way to declare :term:`WSGI` application configuration in an ``.ini`` file - (PasteDeploy). - -- A :term:`WSGI` server runner (``paster serve``) which can accept - PasteDeploy ``.ini`` file values as input. - -- A mechanism for rendering scaffolds into projects (``paster create``). - -Paste is not a particularly integral part of Pyramid. It's more or less used -directly only in projects created from scaffolds. It's possible to create a -Pyramid application which does not use Paste at all. We show a Pyramid -application that doesn't use Paste in :ref:`firstapp_chapter`. However, all -Pyramid scaffolds use the system, to provide new developers with a -standardized way of starting, stopping, and setting deployment values. This -chapter is not a replacement for documentation about Paste or PasteDeploy; it +Bicking named :term:`PasteDeploy`. PasteDeploy defines a way to declare +:term:`WSGI` application configuration in an ``.ini`` file. + +Pyramid uses this configuration file format in input to its :term:`WSGI` +server runner ``pserve``, as well as other commands such as ``pviews``, +``pshell``, ``proutes``, and ``ptweens``. + +PasteDeploy is not a particularly integral part of Pyramid. It's possible to +create a Pyramid application which does not use PasteDeploy at all. We show +a Pyramid application that doesn't use PasteDeploy in +:ref:`firstapp_chapter`. However, all Pyramid scaffolds render PasteDeploy +configuration files, to provide new developers with a standardized way of +setting deployment values, and to provide new users with a standardized way +of starting, stopping, and debugging an application. + +This chapter is not a replacement for documentation about PasteDeploy; it only contextualizes the use of Paste within Pyramid. For detailed documentation, see http://pythonpaste.org. @@ -29,7 +28,7 @@ PasteDeploy :term:`PasteDeploy` is the system that Pyramid uses to allow :term:`deployment settings` to be spelled using an ``.ini`` configuration -file format. It also allows the ``paster serve`` command to work. Its +file format. It also allows the ``pserve`` command to work. Its configuration format provides a convenient place to define application :term:`deployment settings` and WSGI server settings, and its server runner allows you to stop and start a Pyramid application easily. @@ -82,9 +81,9 @@ factory in the ``MyProject`` project which has the entry point named ``main`` where the entry point refers to a ``main`` function in the ``mypackage`` module". Indeed, if you open up the ``__init__.py`` module generated within any scaffold-generated package, you'll see a ``main`` function. This is the -function called by :term:`PasteDeploy` when the ``paster serve`` command is -invoked against our application. It accepts a global configuration object -and *returns* an instance of our application. +function called by :term:`PasteDeploy` when the ``pserve`` command is invoked +against our application. It accepts a global configuration object and +*returns* an instance of our application. ``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 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/paste.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index 5c7d4c3fb..cf8f96c8a 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -20,7 +20,7 @@ setting deployment values, and to provide new users with a standardized way of starting, stopping, and debugging an application. This chapter is not a replacement for documentation about PasteDeploy; it -only contextualizes the use of Paste within Pyramid. For detailed +only contextualizes the use of PasteDeploy within Pyramid. For detailed documentation, see http://pythonpaste.org. PasteDeploy @@ -76,14 +76,14 @@ The ``egg:`` prefix in ``egg:MyProject`` indicates that this is an entry point *URI* specifier, where the "scheme" is "egg". An "egg" is created when you run ``setup.py install`` or ``setup.py develop`` within your project. -In English, this entry point can thus be referred to as a "Paste application -factory in the ``MyProject`` project which has the entry point named ``main`` -where the entry point refers to a ``main`` function in the ``mypackage`` -module". Indeed, if you open up the ``__init__.py`` module generated within -any scaffold-generated package, you'll see a ``main`` function. This is the -function called by :term:`PasteDeploy` when the ``pserve`` command is invoked -against our application. It accepts a global configuration object and -*returns* an instance of our application. +In English, this entry point can thus be referred to as a "PasteDeploy +application factory in the ``MyProject`` project which has the entry point +named ``main`` where the entry point refers to a ``main`` function in the +``mypackage`` module". Indeed, if you open up the ``__init__.py`` module +generated within any scaffold-generated package, you'll see a ``main`` +function. This is the function called by :term:`PasteDeploy` when the +``pserve`` command is invoked against our application. It accepts a global +configuration object and *returns* an instance of our application. ``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 253df134a73613574e6c895b1edde4d3bb441253 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Dec 2011 00:43:16 -0500 Subject: whitespace --- docs/narr/paste.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index cf8f96c8a..86b047aec 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -17,7 +17,7 @@ a Pyramid application that doesn't use PasteDeploy in :ref:`firstapp_chapter`. However, all Pyramid scaffolds render PasteDeploy configuration files, to provide new developers with a standardized way of setting deployment values, and to provide new users with a standardized way -of starting, stopping, and debugging an application. +of starting, stopping, and debugging an application. This chapter is not a replacement for documentation about PasteDeploy; it only contextualizes the use of PasteDeploy within Pyramid. For detailed -- cgit v1.2.3 From 62ea1b60f18d8ac0bab2331852f9ef8bee1fad57 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 01:10:49 +0200 Subject: fix link --- docs/narr/paste.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index 86b047aec..efec1f092 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -85,6 +85,8 @@ function. This is the function called by :term:`PasteDeploy` when the ``pserve`` command is invoked against our application. It accepts a global configuration object and *returns* an instance of our application. +.. _defaults_section_of_pastedeploy_file: + ``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 6ad5fb2a48c9a0c081eb3e2b138752bc8c4e63fb Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 18 Feb 2013 23:14:16 +0200 Subject: fix links --- docs/narr/paste.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index efec1f092..0b3457d1e 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -21,7 +21,7 @@ of starting, stopping, and debugging an application. This chapter is not a replacement for documentation about PasteDeploy; it only contextualizes the use of PasteDeploy within Pyramid. For detailed -documentation, see http://pythonpaste.org. +documentation, see http://pythonpaste.org/deploy/. PasteDeploy ----------- -- cgit v1.2.3 From c4c182b47d1abdf899077ecd433a268618f4f493 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 18:30:02 +0200 Subject: be more concise, and simplify * It should be obvious which file is referred to * Fix a typo * 'points at a string' is not ideal when referring to Python --- docs/narr/paste.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index 86b047aec..aee5f9069 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -62,7 +62,7 @@ Take a look at the generated ``setup.py`` file for this project. :language: python :linenos: -Note that the ``entry_point`` line in ``setup.py`` points at a string which +Note that ``entry_points`` is assigned a string which looks a lot like an ``.ini`` file. This string representation of an ``.ini`` file has a section named ``[paste.app_factory]``. Within this section, there is a key named ``main`` (the entry point name) which has a value -- cgit v1.2.3 From daa0964624bb4d2818cad62351418c09a7326b5a Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 11 Nov 2013 23:23:58 -0600 Subject: easiest commit ever --- docs/narr/paste.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index 3427b6d53..f1fb70869 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -87,7 +87,7 @@ configuration object and *returns* an instance of our application. .. _defaults_section_of_pastedeploy_file: -``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File +``[DEFAULT]`` Section of a PasteDeploy ``.ini`` File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can add a ``[DEFAULT]`` section to your PasteDeploy ``.ini`` file. Such -- cgit v1.2.3 From fc3f6b05e086ed4e111013fcd5b09454982d58f3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 18 Oct 2015 02:48:55 -0700 Subject: minor grammar, rewrap 79 cols, .rst syntax fixes --- docs/narr/paste.rst | 96 ++++++++++++++++++++++++++--------------------------- 1 file changed, 47 insertions(+), 49 deletions(-) (limited to 'docs/narr/paste.rst') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index f1fb70869..0a217e6e3 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -7,54 +7,54 @@ Packages generated via a :term:`scaffold` make use of a system created by Ian Bicking named :term:`PasteDeploy`. PasteDeploy defines a way to declare :term:`WSGI` application configuration in an ``.ini`` file. -Pyramid uses this configuration file format in input to its :term:`WSGI` -server runner ``pserve``, as well as other commands such as ``pviews``, -``pshell``, ``proutes``, and ``ptweens``. +Pyramid uses this configuration file format as input to its :term:`WSGI` server +runner ``pserve``, as well as other commands such as ``pviews``, ``pshell``, +``proutes``, and ``ptweens``. PasteDeploy is not a particularly integral part of Pyramid. It's possible to -create a Pyramid application which does not use PasteDeploy at all. We show -a Pyramid application that doesn't use PasteDeploy in -:ref:`firstapp_chapter`. However, all Pyramid scaffolds render PasteDeploy -configuration files, to provide new developers with a standardized way of -setting deployment values, and to provide new users with a standardized way -of starting, stopping, and debugging an application. - -This chapter is not a replacement for documentation about PasteDeploy; it -only contextualizes the use of PasteDeploy within Pyramid. For detailed +create a Pyramid application which does not use PasteDeploy at all. We show a +Pyramid application that doesn't use PasteDeploy in :ref:`firstapp_chapter`. +However, all Pyramid scaffolds render PasteDeploy configuration files, to +provide new developers with a standardized way of setting deployment values, +and to provide new users with a standardized way of starting, stopping, and +debugging an application. + +This chapter is not a replacement for documentation about PasteDeploy; it only +contextualizes the use of PasteDeploy within Pyramid. For detailed documentation, see http://pythonpaste.org/deploy/. PasteDeploy ----------- -:term:`PasteDeploy` is the system that Pyramid uses to allow -:term:`deployment settings` to be spelled using an ``.ini`` configuration -file format. It also allows the ``pserve`` command to work. Its -configuration format provides a convenient place to define application -:term:`deployment settings` and WSGI server settings, and its server runner -allows you to stop and start a Pyramid application easily. +:term:`PasteDeploy` is the system that Pyramid uses to allow :term:`deployment +settings` to be specified using an ``.ini`` configuration file format. It also +allows the ``pserve`` command to work. Its configuration format provides a +convenient place to define application :term:`deployment settings` and WSGI +server settings, and its server runner allows you to stop and start a Pyramid +application easily. .. _pastedeploy_entry_points: Entry Points and PasteDeploy ``.ini`` Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the :ref:`project_narr` chapter, we breezed over the meaning of a configuration line in the ``deployment.ini`` file. This was the ``use = -egg:MyProject`` line in the ``[app:main]`` section. We breezed over it -because it's pretty confusing and "too much information" for an introduction -to the system. We'll try to give it a bit of attention here. Let's see the -config file again: +egg:MyProject`` line in the ``[app:main]`` section. We breezed over it because +it's pretty confusing and "too much information" for an introduction to the +system. We'll try to give it a bit of attention here. Let's see the config +file again: .. literalinclude:: MyProject/development.ini :language: ini :linenos: -The line in ``[app:main]`` above that says ``use = egg:MyProject`` is -actually shorthand for a longer spelling: ``use = egg:MyProject#main``. The -``#main`` part is omitted for brevity, as ``#main`` is a default defined by -PasteDeploy. ``egg:MyProject#main`` is a string which has meaning to -PasteDeploy. It points at a :term:`setuptools` :term:`entry point` named -``main`` defined in the ``MyProject`` project. +The line in ``[app:main]`` above that says ``use = egg:MyProject`` is actually +shorthand for a longer spelling: ``use = egg:MyProject#main``. The ``#main`` +part is omitted for brevity, as ``#main`` is a default defined by PasteDeploy. +``egg:MyProject#main`` is a string which has meaning to PasteDeploy. It points +at a :term:`setuptools` :term:`entry point` named ``main`` defined in the +``MyProject`` project. Take a look at the generated ``setup.py`` file for this project. @@ -62,19 +62,19 @@ Take a look at the generated ``setup.py`` file for this project. :language: python :linenos: -Note that ``entry_points`` is assigned a string which -looks a lot like an ``.ini`` file. This string representation of an ``.ini`` -file has a section named ``[paste.app_factory]``. Within this section, there -is a key named ``main`` (the entry point name) which has a value -``myproject:main``. The *key* ``main`` is what our ``egg:MyProject#main`` -value of the ``use`` section in our config file is pointing at, although it -is actually shortened to ``egg:MyProject`` there. The value represents a -:term:`dotted Python name` path, which refers to a callable in our -``myproject`` package's ``__init__.py`` module. +Note that ``entry_points`` is assigned a string which looks a lot like an +``.ini`` file. This string representation of an ``.ini`` file has a section +named ``[paste.app_factory]``. Within this section, there is a key named +``main`` (the entry point name) which has a value ``myproject:main``. The +*key* ``main`` is what our ``egg:MyProject#main`` value of the ``use`` section +in our config file is pointing at, although it is actually shortened to +``egg:MyProject`` there. The value represents a :term:`dotted Python name` +path, which refers to a callable in our ``myproject`` package's ``__init__.py`` +module. -The ``egg:`` prefix in ``egg:MyProject`` indicates that this is an entry -point *URI* specifier, where the "scheme" is "egg". An "egg" is created when -you run ``setup.py install`` or ``setup.py develop`` within your project. +The ``egg:`` prefix in ``egg:MyProject`` indicates that this is an entry point +*URI* specifier, where the "scheme" is "egg". An "egg" is created when you run +``setup.py install`` or ``setup.py develop`` within your project. In English, this entry point can thus be referred to as a "PasteDeploy application factory in the ``MyProject`` project which has the entry point @@ -88,13 +88,11 @@ configuration object and *returns* an instance of our application. .. _defaults_section_of_pastedeploy_file: ``[DEFAULT]`` Section of a PasteDeploy ``.ini`` File -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can add a ``[DEFAULT]`` section to your PasteDeploy ``.ini`` file. Such -a section should consists of global parameters that are shared by all the -applications, servers and :term:`middleware` defined within the configuration +You can add a ``[DEFAULT]`` section to your PasteDeploy ``.ini`` file. Such a +section should consist of global parameters that are shared by all the +applications, servers, and :term:`middleware` defined within the configuration file. The values in a ``[DEFAULT]`` section will be passed to your -application's ``main`` function as ``global_config`` (see the reference to -the ``main`` function in :ref:`init_py`). - - +application's ``main`` function as ``global_config`` (see the reference to the +``main`` function in :ref:`init_py`). -- cgit v1.2.3