Merge remote-tracking branch 'refs/remotes/Pylons/master'

1 files changed, 133 insertions, 208 deletions

diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index f5adad905..6a952dec9 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -1,111 +1,101 @@
+.. index::
+   single: hello world program
+
 .. _firstapp_chapter:
 
 Creating Your First :app:`Pyramid` Application
-=================================================
+==============================================
 
 In this chapter, we will walk through the creation of a tiny :app:`Pyramid`
 application.  After we're finished creating the application, we'll explain in
-more detail how it works.
+more detail how it works. It assumes you already have :app:`Pyramid` installed.
+If you do not, head over to the :ref:`installing_chapter` section.
 
 .. _helloworld_imperative:
 
-Hello World, Goodbye World
---------------------------
+Hello World
+-----------
 
-Here's one of the very simplest :app:`Pyramid` applications, configured
-imperatively:
+Here's one of the very simplest :app:`Pyramid` applications:
 
-.. code-block:: python
+.. literalinclude:: helloworld.py
    :linenos:
 
-   from pyramid.config import Configurator
-   from pyramid.response import Response
-   from paste.httpserver import serve
+When this code is inserted into a Python script named ``helloworld.py`` and
+executed by a Python interpreter which has the :app:`Pyramid` software
+installed, an HTTP server is started on TCP port 8080.
 
-   def hello_world(request):
-       return Response('Hello world!')
+On UNIX:
 
-   def goodbye_world(request):
-       return Response('Goodbye world!')
+.. code-block:: text
 
-   if __name__ == '__main__':
-       config = Configurator()
-       config.add_view(hello_world)
-       config.add_view(goodbye_world, name='goodbye')
-       app = config.make_wsgi_app()
-       serve(app, host='0.0.0.0')
+   $ $VENV/bin/python helloworld.py
 
-When this code is inserted into a Python script named ``helloworld.py`` and
-executed by a Python interpreter which has the :app:`Pyramid` software
-installed, an HTTP server is started on TCP port 8080:
+On Windows:
 
 .. code-block:: text
 
-   $ python helloworld.py
-   serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
+   C:\> %VENV%\Scripts\python.exe helloworld.py
+
+This command will not return and nothing will be printed to the console. When
+port 8080 is visited by a browser on the URL ``/hello/world``, the server will
+simply serve up the text "Hello world!".  If your application is running on
+your local system, using `<http://localhost:8080/hello/world>`_ in a browser
+will show this result.
 
-When port 8080 is visited by a browser on the root URL (``/``), the server
-will simply serve up the text "Hello world!"  When visited by a browser on
-the URL ``/goodbye``, the server will serve up the text "Goodbye world!"
+Each time you visit a URL served by the application in a browser, a logging
+line will be emitted to the console displaying the hostname, the date, the
+request method and path, and some additional information.  This output is done
+by the wsgiref server we've used to serve this application.  It logs an "access
+log" in Apache combined logging format to the console.
 
-Press ``Ctrl-C`` to stop the application.
+Press ``Ctrl-C`` (or ``Ctrl-Break`` on Windows) to stop the application.
 
 Now that we have a rudimentary understanding of what the application does,
-let's examine it piece-by-piece.
+let's examine it piece by piece.
 
 Imports
 ~~~~~~~
 
-The above ``helloworld.py`` script uses the following set of import
-statements:
+The above ``helloworld.py`` script uses the following set of import statements:
 
-.. code-block:: python
+.. literalinclude:: helloworld.py
    :linenos:
-
-   from pyramid.config import Configurator
-   from pyramid.response import Response
-   from paste.httpserver import serve
+   :lines: 1-3
 
 The script imports the :class:`~pyramid.config.Configurator` class from the
 :mod:`pyramid.config` module.  An instance of the
 :class:`~pyramid.config.Configurator` class is later used to configure your
 :app:`Pyramid` application.
 
-The script uses the :class:`pyramid.response.Response` class later in the
-script to create a :term:`response` object.
-
 Like many other Python web frameworks, :app:`Pyramid` uses the :term:`WSGI`
 protocol to connect an application and a web server together.  The
-:mod:`paste.httpserver` server is used in this example as a WSGI server for
-convenience, as the ``paste`` package is a dependency of :app:`Pyramid`
-itself.
+:mod:`wsgiref` server is used in this example as a WSGI server for convenience,
+as it is shipped within the Python standard library.
+
+The script also imports the :class:`pyramid.response.Response` class for later
+use.  An instance of this class will be used to create a web response.
 
 View Callable Declarations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The above script, beneath its set of imports, defines two functions: one
-named ``hello_world`` and one named ``goodbye_world``.
+The above script, beneath its set of imports, defines a function named
+``hello_world``.
 
-.. code-block:: python
+.. literalinclude:: helloworld.py
    :linenos:
+   :pyobject: hello_world
 
-   def hello_world(request):
-       return Response('Hello world!')
+The function accepts a single argument (``request``) and it returns an instance
+of the :class:`pyramid.response.Response` class.  The single argument to the
+class' constructor is a string computed from parameters matched from the URL. 
+This value becomes the body of the response.
 
-   def goodbye_world(request):
-       return Response('Goodbye world!')
-
-These functions don't do anything very difficult.  Both functions accept a
-single argument (``request``).  The ``hello_world`` function does nothing but
-return a response instance with the body ``Hello world!``.  The
-``goodbye_world`` function returns a response instance with the body
-``Goodbye world!``.
-
-Each of these functions is known as a :term:`view callable`.  A view callable
-accepts a single argument, ``request``.  It is expected to return a
-:term:`response` object.  A view callable doesn't need to be a function; it
-can be represented via another type of object, like a class or an instance,
-but for our purposes here, a function serves us well.
+This function is known as a :term:`view callable`.  A view callable accepts a
+single argument, ``request``.  It is expected to return a :term:`response`
+object.  A view callable doesn't need to be a function; it can be represented
+via another type of object, like a class or an instance, but for our purposes
+here, a function serves us well.
 
 A view callable is always called with a :term:`request` object.  A request
 object is a representation of an HTTP request sent to :app:`Pyramid` via the
@@ -113,18 +103,11 @@ active :term:`WSGI` server.
 
 A view callable is required to return a :term:`response` object because a
 response object has all the information necessary to formulate an actual HTTP
-response; this object is then converted to text by the upstream :term:`WSGI`
-server and sent back to the requesting browser.  To return a response, each
-view callable creates an instance of the :class:`~pyramid.response.Response`
-class.  In the ``hello_world`` function, the string ``'Hello world!'`` is
-passed to the ``Response`` constructor as the *body* of the response.  In the
-``goodbye_world`` function, the string ``'Goodbye world!'`` is passed.
-
-.. note:: As we'll see in later chapters, returning a literal
-   :term:`response` object from a view callable is not always required; we
-   can instead use a :term:`renderer` in our view configurations.  If we use
-   a renderer, our view callable is allowed to return a value that the
-   renderer understands, and the renderer generates a response on our behalf.
+response; this object is then converted to text by the :term:`WSGI` server
+which called Pyramid and it is sent back to the requesting browser.  To return
+a response, each view callable creates an instance of the
+:class:`~pyramid.response.Response` class.  In the ``hello_world`` function, a
+string is passed as the body to the response.
 
 .. index::
    single: imperative configuration
@@ -136,114 +119,63 @@ passed to the ``Response`` constructor as the *body* of the response.  In the
 Application Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the above script, the following code represents the *configuration* of
-this simple application. The application is configured using the previously
-defined imports and function definitions, placed within the confines of an
-``if`` statement:
+In the above script, the following code represents the *configuration* of this
+simple application. The application is configured using the previously defined
+imports and function definitions, placed within the confines of an ``if``
+statement:
 
-.. code-block:: python
+.. literalinclude:: helloworld.py
    :linenos:
+   :lines: 9-15
 
-   if __name__ == '__main__':
-       config = Configurator()
-       config.add_view(hello_world)
-       config.add_view(goodbye_world, name='goodbye')
-       app = config.make_wsgi_app()
-       serve(app, host='0.0.0.0')
-
-Let's break this down this piece-by-piece.
+Let's break this down piece by piece.
 
 Configurator Construction
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: python
+.. literalinclude:: helloworld.py
    :linenos:
-
-   if __name__ == '__main__':
-       config = Configurator()
+   :lines: 9-10
 
 The ``if __name__ == '__main__':`` line in the code sample above represents a
 Python idiom: the code inside this if clause is not invoked unless the script
-containing this code is run directly from the command line. For example, if
-the file named ``helloworld.py`` contains the entire script body, the code
-within the ``if`` statement will only be invoked when ``python
-helloworld.py`` is executed from the operating system command line.
-
-``helloworld.py`` in this case is a Python :term:`module`.  Using the ``if``
-clause is necessary -- or at least best practice -- because code in any
-Python module may be imported by another Python module.  By using this idiom,
-the script is indicating that it does not want the code within the ``if``
-statement to execute if this module is imported; the code within the ``if``
-block should only be run during a direct script execution.
+containing this code is run directly from the operating system command line.
+For example, if the file named ``helloworld.py`` contains the entire script
+body, the code within the ``if`` statement will only be invoked when ``python
+helloworld.py`` is executed from the command line.
+
+Using the ``if`` clause is necessary—or at least best practice—because code in
+a Python ``.py`` file may be eventually imported via the Python ``import``
+statement by another ``.py`` file.  ``.py`` files that are imported by other
+``.py`` files are referred to as *modules*.  By using the ``if __name__ ==
+'__main__':`` idiom, the script above is indicating that it does not want the
+code within the ``if`` statement to execute if this module is imported from
+another; the code within the ``if`` block should only be run during a direct
+script execution.
 
 The ``config = Configurator()`` line above creates an instance of the
 :class:`~pyramid.config.Configurator` class.  The resulting ``config`` object
 represents an API which the script uses to configure this particular
 :app:`Pyramid` application.  Methods called on the Configurator will cause
-registrations to be made in a :term:`application registry` associated with
-the application.
+registrations to be made in an :term:`application registry` associated with the
+application.
 
 .. _adding_configuration:
 
 Adding Configuration
 ~~~~~~~~~~~~~~~~~~~~
 
-.. ignore-next-block
-.. code-block:: python
+.. literalinclude:: helloworld.py
    :linenos:
+   :lines: 11-12
+
+The first line above calls the :meth:`pyramid.config.Configurator.add_route`
+method, which registers a :term:`route` to match any URL path that begins with
+``/hello/`` followed by a string.
 
-   config.add_view(hello_world)
-   config.add_view(goodbye_world, name='goodbye')
-
-Each of these lines calls the :meth:`pyramid.config.Configurator.add_view`
-method.  The ``add_view`` method of a configurator registers a :term:`view
-configuration` within the :term:`application registry`.  A :term:`view
-configuration` represents a set of circumstances related to the
-:term:`request` that will cause a specific :term:`view callable` to be
-invoked.  This "set of circumstances" is provided as one or more keyword
-arguments to the ``add_view`` method.  Each of these keyword arguments is
-known as a view configuration :term:`predicate`.
-
-The line ``config.add_view(hello_world)`` registers the ``hello_world``
-function as a view callable.  The ``add_view`` method of a Configurator must
-be called with a view callable object or a :term:`dotted Python name` as its
-first argument, so the first argument passed is the ``hello_world`` function.
-This line calls ``add_view`` with a *default* value for the :term:`predicate`
-argument, named ``name``.  The ``name`` predicate defaults to a value
-equalling the empty string (``''``).  This means that we're instructing
-:app:`Pyramid` to invoke the ``hello_world`` view callable when the
-:term:`view name` is the empty string.  We'll learn in later chapters what a
-:term:`view name` is, and under which circumstances a request will have a
-view name that is the empty string; in this particular application, it means
-that the ``hello_world`` view callable will be invoked when the root URL
-``/`` is visited by a browser.
-
-The line ``config.add_view(goodbye_world, name='goodbye')`` registers the
-``goodbye_world`` function as a view callable.  The line calls ``add_view``
-with the view callable as the first required positional argument, and a
-:term:`predicate` keyword argument ``name`` with the value ``'goodbye'``.
-The ``name`` argument supplied in this :term:`view configuration` implies
-that only a request that has a :term:`view name` of ``goodbye`` should cause
-the ``goodbye_world`` view callable to be invoked.  In this particular
-application, this means that the ``goodbye_world`` view callable will be
-invoked when the URL ``/goodbye`` is visited by a browser.
-
-Each invocation of the ``add_view`` method registers a :term:`view
-configuration`.  Each :term:`predicate` provided as a keyword argument to the
-``add_view`` method narrows the set of circumstances which would cause the
-view configuration's callable to be invoked.  In general, a greater number of
-predicates supplied along with a view configuration will more strictly limit
-the applicability of its associated view callable.  When :app:`Pyramid`
-processes a request, the view callable with the *most specific* view
-configuration (the view configuration that matches the most specific set of
-predicates) is always invoked.
-
-In this application, :app:`Pyramid` chooses the most specific view callable
-based only on view :term:`predicate` applicability.  The ordering of calls to
-:meth:`~pyramid.config.Configurator.add_view` is never very important.  We can
-register ``goodbye_world`` first and ``hello_world`` second; :app:`Pyramid`
-will still give us the most specific callable when a request is dispatched to
-it.
+The second line registers the ``hello_world`` function as a :term:`view
+callable` and makes sure that it will be called when the ``hello`` route is
+matched.
 
 .. index::
    single: make_wsgi_app
@@ -252,74 +184,67 @@ it.
 WSGI Application Creation
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ignore-next-block
-.. code-block:: python
+.. literalinclude:: helloworld.py
    :linenos:
-
-   app = config.make_wsgi_app()
+   :lines: 13
 
 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 set 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 :term:`WSGI` in any depth within this book,
-however, you can learn more about it by visiting `wsgi.org
-<http://wsgi.org>`_.
-
-The :app:`Pyramid` application object, in particular, is an instance of a
-class representing a :app:`Pyramid` :term:`router`.  It has a reference to
-the :term:`application registry` which resulted from method calls to the
-configurator used to configure it.  The :term:`router` consults the registry
-to obey the policy choices made by a single application.  These policy
-choices were informed by method calls to the :term:`Configurator` made
-earlier; in our case, the only policy choices made were implied by two calls
-to its ``add_view`` method.
+*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``
+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
+:term:`WSGI` in any depth within this book, but you can learn more about it by
+visiting `wsgi.org <http://wsgi.org>`_.
+
+The :app:`Pyramid` application object, in particular, is an instance of a class
+representing a :app:`Pyramid` :term:`router`.  It has a reference to the
+:term:`application registry` which resulted from method calls to the
+configurator used to configure it.  The :term:`router` consults the registry to
+obey the policy choices made by a single application.  These policy choices
+were informed by method calls to the :term:`Configurator` made earlier; in our
+case, the only policy choices made were implied by calls to its ``add_view``
+and ``add_route`` methods.
 
 WSGI Application Serving
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ignore-next-block
-.. code-block:: python
+.. literalinclude:: helloworld.py
    :linenos:
-
-   serve(app, host='0.0.0.0')
-
-Finally, we actually serve the application to requestors by starting up a
-WSGI server.  We happen to use the :func:`paste.httpserver.serve` WSGI server
-runner, passing it the ``app`` object (a :term:`router`) as the application
-we wish to serve.  We also pass in an argument ``host=='0.0.0.0'``, meaning
-"listen on all TCP interfaces."  By default, the Paste HTTP server listens
-only on the ``127.0.0.1`` interface, which is problematic if you're running
-the server on a remote system and you wish to access it with a web browser
-from a local system.  We don't specify a TCP port number to listen on; this
-means we want to use the default TCP port, which is 8080.
-
-When this line is invoked, it causes the server to start listening on TCP
-port 8080.  It will serve requests forever, or at least until we stop it by
-killing the process which runs it (usually by pressing ``Ctrl-C`` in the
-terminal we used to start it).
+   :lines: 14-15
+
+Finally, we actually serve the application to requestors by starting up a WSGI
+server.  We happen to use the :mod:`wsgiref` ``make_server`` server maker for
+this purpose.  We pass in as the first argument ``'0.0.0.0'``, which means
+"listen on all TCP interfaces".  By default, the HTTP server listens only on
+the ``127.0.0.1`` interface, which is problematic if you're running the server
+on a remote system and you wish to access it with a web browser from a local
+system.  We also specify a TCP port number to listen on, which is 8080, passing
+it as the second argument.  The final argument is the ``app`` object (a
+:term:`router`), which is the application we wish to serve.  Finally, we call
+the server's ``serve_forever`` method, which starts the main loop in which it
+will wait for requests from the outside world.
+
+When this line is invoked, it causes the server to start listening on TCP port
+8080.  The server will serve requests forever, or at least until we stop it by
+killing the process which runs it (usually by pressing ``Ctrl-C`` or
+``Ctrl-Break`` in the terminal we used to start it).
 
 Conclusion
 ~~~~~~~~~~
 
 Our hello world application is one of the simplest possible :app:`Pyramid`
 applications, configured "imperatively".  We can see that it's configured
-imperatively because the full power of Python is available to us as we
-perform configuration tasks.
+imperatively because the full power of Python is available to us as we perform
+configuration tasks.
 
 References
 ----------
 
-For more information about the API of a :term:`Configurator` object,
-see :class:`~pyramid.config.Configurator` .
+For more information about the API of a :term:`Configurator` object, see
+:class:`~pyramid.config.Configurator` .
 
 For more information about :term:`view configuration`, see
 :ref:`view_config_chapter`.
-
-An example of using *declarative* configuration (:term:`ZCML`) instead of
-imperative configuration to create a similar "hello world" is available
-within the documentation for :term:`pyramid_zcml`.