Permalink
Browse files

- 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.
  • Loading branch information...
1 parent 6413015 commit 3d338ea5737b7c113b17120b40684e2694cf3fa9 @mcdonc mcdonc committed Aug 22, 2011
Showing with 223 additions and 283 deletions.
  1. +2 −5 TODO.txt
  2. +1 −0 docs/index.rst
  3. +1 −0 docs/latexindex.rst
  4. +1 −5 docs/narr/MyProject/development.ini
  5. +1 −5 docs/narr/MyProject/production.ini
  6. +3 −3 docs/narr/commandline.rst
  7. +4 −4 docs/narr/environment.rst
  8. +2 −2 docs/narr/i18n.rst
  9. +20 −6 docs/narr/logging.rst
  10. +99 −0 docs/narr/paste.rst
  11. +37 −84 docs/narr/project.rst
  12. +1 −1 docs/narr/security.rst
  13. +12 −11 docs/narr/startup.rst
  14. +3 −3 docs/narr/templates.rst
  15. +1 −1 docs/narr/vhosting.rst
  16. +3 −10 docs/tutorials/wiki/basiclayout.rst
  17. +1 −5 docs/tutorials/wiki/src/authorization/development.ini
  18. +1 −5 docs/tutorials/wiki/src/authorization/production.ini
  19. +1 −5 docs/tutorials/wiki/src/basiclayout/development.ini
  20. +1 −5 docs/tutorials/wiki/src/basiclayout/production.ini
  21. +1 −5 docs/tutorials/wiki/src/models/development.ini
  22. +1 −5 docs/tutorials/wiki/src/models/production.ini
  23. +1 −5 docs/tutorials/wiki/src/tests/development.ini
  24. +1 −5 docs/tutorials/wiki/src/tests/production.ini
  25. +1 −5 docs/tutorials/wiki/src/views/development.ini
  26. +1 −5 docs/tutorials/wiki/src/views/production.ini
  27. +4 −3 docs/tutorials/wiki2/basiclayout.rst
  28. +1 −5 docs/tutorials/wiki2/src/authorization/development.ini
  29. +1 −5 docs/tutorials/wiki2/src/authorization/production.ini
  30. +1 −5 docs/tutorials/wiki2/src/basiclayout/development.ini
  31. +1 −5 docs/tutorials/wiki2/src/basiclayout/production.ini
  32. +1 −5 docs/tutorials/wiki2/src/models/development.ini
  33. +1 −5 docs/tutorials/wiki2/src/models/production.ini
  34. +1 −5 docs/tutorials/wiki2/src/tests/development.ini
  35. +1 −5 docs/tutorials/wiki2/src/tests/production.ini
  36. +1 −5 docs/tutorials/wiki2/src/views/development.ini
  37. +1 −5 docs/tutorials/wiki2/src/views/production.ini
  38. +1 −5 pyramid/scaffolds/alchemy/development.ini_tmpl
  39. +1 −5 pyramid/scaffolds/alchemy/production.ini_tmpl
  40. +1 −5 pyramid/scaffolds/routesalchemy/development.ini_tmpl
  41. +1 −5 pyramid/scaffolds/routesalchemy/production.ini_tmpl
  42. +1 −5 pyramid/scaffolds/starter/development.ini_tmpl
  43. +1 −5 pyramid/scaffolds/starter/production.ini_tmpl
  44. +1 −5 pyramid/scaffolds/zodb/development.ini_tmpl
  45. +1 −5 pyramid/scaffolds/zodb/production.ini_tmpl
View
@@ -1,14 +1,11 @@
Pyramid TODOs
=============
-Should-Have
------------
-
-- Name WSGI app "main" instead of pipeline in scaffold configs?
-
Nice-to-Have
------------
+- Flesh out "paste" chapter.
+
- Move configuration-related stuff in "static" to config/views, from
"settings" to config/settings, "renderers" to config/rendering, "asset" to
config/assets, and possibly mako/chameleon rendering stuff to
View
@@ -54,6 +54,7 @@ Narrative documentation in chapter form explaining how to use
narr/events
narr/environment
narr/logging
+ narr/paste
narr/commandline
narr/i18n
narr/vhosting
View
@@ -42,6 +42,7 @@ Narrative Documentation
narr/events
narr/environment
narr/logging
+ narr/paste
narr/commandline
narr/i18n
narr/vhosting
@@ -1,4 +1,4 @@
-[app:MyProject]
+[app:main]
use = egg:MyProject
pyramid.reload_templates = true
@@ -9,10 +9,6 @@ pyramid.debug_templates = true
pyramid.default_locale_name = en
pyramid.includes = pyramid_debugtoolbar
-[pipeline:main]
-pipeline =
- MyProject
-
[server:main]
use = egg:Paste#http
host = 0.0.0.0
@@ -1,4 +1,4 @@
-[app:MyProject]
+[app:main]
use = egg:MyProject
pyramid.reload_templates = false
@@ -8,10 +8,6 @@ pyramid.debug_routematch = false
pyramid.debug_templates = false
pyramid.default_locale_name = en
-[pipeline:main]
-pipeline =
- MyProject
-
[server:main]
use = egg:Paste#http
host = 0.0.0.0
@@ -127,12 +127,12 @@ The argument to ``pshell`` follows the format ``config_file#section_name``
where ``config_file`` is the path to your application's ``.ini`` file and
``section_name`` is the ``app`` section name inside the ``.ini`` file which
points to your application. For example, if your application ``.ini`` file
-might have a ``[app:MyProject]`` section that looks like so:
+might have a ``[app:main]`` section that looks like so:
.. code-block:: ini
:linenos:
- [app:MyProject]
+ [app:main]
use = egg:MyProject
pyramid.reload_templates = true
pyramid.debug_authorization = false
@@ -401,7 +401,7 @@ tween chain is used:
.. code-block:: text
:linenos:
- [app:starter]
+ [app:main]
use = egg:starter
reload_templates = true
debug_authorization = false
@@ -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
View
@@ -787,7 +787,7 @@ application's Paster ``.ini`` file:
:linenos:
[app:main]
- use = egg:MyProject#app
+ use = egg:MyProject
pyramid.reload_templates = true
pyramid.debug_authorization = false
pyramid.debug_notfound = false
@@ -847,7 +847,7 @@ Allow a deployer to modify your application's PasteDeploy .ini file:
:linenos:
[app:main]
- use = egg:MyProject#app
+ use = egg:MyProject
# ...
available_languages = fr de en ru
View
@@ -301,22 +301,36 @@ requests using the `Apache Combined Log Format
with a FileHandler can be used to create an ``access.log`` file similar to
Apache's.
-Like any standard middleware with a Paste entry point, TransLogger can be
-configured to wrap your application in the ``[app:main]`` section of the ini
-file:
+Like any standard middleware with a Paste entry point, TransLogger can be
+configured to wrap your application using ``.ini`` file syntax. First,
+rename your Pyramid ``.ini`` file's ``[app:main]`` section to
+``[app:mypyramidapp]``, then add a ``[filter:translogger]`` section, then use
+a ``[pipeline:main]`` section file to form a WSGI pipeline with both the
+translogger and your application in it. For instance, change from this:
.. code-block:: ini
+ [app:main]
+ use = egg:MyProject
+
+To this:
+
+.. code-block:: ini
+
+ [app:mypyramidapp]
+ use = egg:MyProject
+
[filter:translogger]
paste.filter_app_factory = egg:Paste#translogger
setup_console_handler = False
[pipeline:main]
pipeline = translogger
- myapp
+ mypyramidapp
-This is equivalent to wrapping your app in a TransLogger instance via the
-bottom the ``main`` function of your project's ``__init__`` file:
+Using PasteDeploy this way to form and serve a pipeline is equivalent to
+wrapping your app in a TransLogger instance via the bottom the ``main``
+function of your project's ``__init__`` file:
.. code-block:: python
View
@@ -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`).
+
+
Oops, something went wrong.

0 comments on commit 3d338ea

Please sign in to comment.