From 8027d1621e859f44e94a063c7b87c818d9096c85 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 12 Jul 2011 00:01:30 -0400 Subject: remove unnecessary clause --- docs/narr/firstapp.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index f5adad905..87487b444 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -12,8 +12,7 @@ more detail how it works. Hello World, Goodbye 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 :linenos: -- cgit v1.2.3 From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/firstapp.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 87487b444..42711784b 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -1,3 +1,6 @@ +.. index:: + single: hello world program + .. _firstapp_chapter: Creating Your First :app:`Pyramid` Application -- cgit v1.2.3 From 8cb68208d42899b50025418812bb339f578d553f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 07:16:14 -0400 Subject: - Reordered chapters in narrative section for better new user friendliness. - Added more indexing markers to sections in documentation. --- docs/narr/firstapp.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 42711784b..6c53f3de0 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -322,6 +322,3 @@ 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`. -- cgit v1.2.3 From afe76b3bc0f378030d2dbffeb63faba829139f8f Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sat, 23 Jul 2011 22:11:31 -0700 Subject: remove extra word --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 6c53f3de0..eb05f8e6d 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -153,7 +153,7 @@ defined imports and function definitions, placed within the confines of an 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 84bd9544083c38ded264b58f13958ab945c92e5e Mon Sep 17 00:00:00 2001 From: Carlos de la Guardia Date: Sat, 23 Jul 2011 22:29:03 -0700 Subject: typo --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index eb05f8e6d..66632e123 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -182,7 +182,7 @@ 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 +registrations to be made in an :term:`application registry` associated with the application. .. _adding_configuration: -- cgit v1.2.3 From e518931f909d31014af5dbbab24d1bfd44e0a19b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Aug 2011 16:49:51 -0400 Subject: reduce awkwardness of phrasing --- docs/narr/firstapp.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 66632e123..62389ec5f 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -166,17 +166,19 @@ Configurator Construction 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 -- cgit v1.2.3 From d36b566a83addddb80d221aa042b828268f185f2 Mon Sep 17 00:00:00 2001 From: Dylan Jay Date: Thu, 25 Aug 2011 13:05:52 +1000 Subject: use routes in firstapp as they are more familar to most and put hello world on the front page to make grab framework shoppers attention. --- docs/narr/firstapp.rst | 154 +++++++++++++++---------------------------------- 1 file changed, 47 insertions(+), 107 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 62389ec5f..447348be3 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -12,30 +12,14 @@ more detail how it works. .. _helloworld_imperative: -Hello World, Goodbye World --------------------------- +Hello World +----------- 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 - - def hello_world(request): - return Response('Hello world!') - - def goodbye_world(request): - return Response('Goodbye world!') - - 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') When this code is inserted into a Python script named ``helloworld.py`` and executed by a Python interpreter which has the :app:`Pyramid` software @@ -46,9 +30,8 @@ installed, an HTTP server is started on TCP port 8080: $ python helloworld.py serving on 0.0.0.0:8080 view at http://127.0.0.1:8080 -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!" +When port 8080 is visited by a browser on the URL (``/hello/world``), the server +will simply serve up the text "Hello world!" Press ``Ctrl-C`` to stop the application. @@ -61,21 +44,15 @@ Imports 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-2 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 @@ -85,25 +62,18 @@ itself. 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!') - - 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!``. +This function doesn't do anything very difficult. The functions accepts a +single argument (``request``). The ``hello_world`` function returns a value +computed from arguments matched from the url route. -Each of these functions is known as a :term:`view callable`. A view callable +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, @@ -118,9 +88,7 @@ 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. +class. In the ``hello_world`` function, the string 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 @@ -143,26 +111,18 @@ 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: - - 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') + :lines: 7-12 Let's break this down piece-by-piece. Configurator Construction ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: python +.. literalinclude:: helloworld.py :linenos: - - if __name__ == '__main__': - config = Configurator() + :lines: 7-8 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 @@ -193,44 +153,32 @@ Adding Configuration ~~~~~~~~~~~~~~~~~~~~ .. ignore-next-block -.. code-block:: python +.. literalinclude:: helloworld.py :linenos: - - 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 + :lines: 9-10 + +First line is to call the :meth:`pyramid.config.Configurator.add_route` +which registers a :term:`route` to match any url with ``/hello/`` followed +by a string. The :meth:`pyramid.config.Configurator.add_view` method of +a configurator registers a :term:`view configuration` within the +:term:`application registry`. A :term:`view configuration` and +:term:`route 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 +The line ``config.add_view(hello_world, route_name='hello')`` 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. +This line calls ``add_view`` with a ``route_name`` ``predicate`` value of +``hello``. This means that we're instructing +:app:`Pyramid` to invoke the ``hello_world`` view callable if the +:term:`route` is matched is ``hello``. In :app:`Pyramid` the use of a +:term:`route` is only one of ways you can link a url to a :term:`view callable` +and is called :term:`URL Dispatch`. Each invocation of the ``add_view`` method registers a :term:`view configuration`. Each :term:`predicate` provided as a keyword argument to the @@ -240,14 +188,8 @@ 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. +predicates) is always invoked. In this application, :app:`Pyramid` chooses the most specific view callable +based only on view :term:`predicate` applicability. .. index:: single: make_wsgi_app @@ -257,10 +199,9 @@ WSGI Application Creation ~~~~~~~~~~~~~~~~~~~~~~~~~ .. ignore-next-block -.. code-block:: python +.. literalinclude:: helloworld.py :linenos: - - app = config.make_wsgi_app() + :lines: 11 After configuring views and ending configuration, the script creates a WSGI *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app` @@ -280,17 +221,16 @@ 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. +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') + :lines: 12 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 -- cgit v1.2.3 From d73be153fa9544f453510524f34d55a7602e0896 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 25 Aug 2011 02:23:51 -0400 Subject: use Response; fix text --- docs/narr/firstapp.rst | 89 ++++++++++++++++++-------------------------------- 1 file changed, 31 insertions(+), 58 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 447348be3..55829bef0 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -20,7 +20,6 @@ Here's one of the very simplest :app:`Pyramid` applications: .. literalinclude:: helloworld.py :linenos: - 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: @@ -30,8 +29,8 @@ installed, an HTTP server is started on TCP port 8080: $ python helloworld.py serving on 0.0.0.0:8080 view at http://127.0.0.1:8080 -When port 8080 is visited by a browser on the URL (``/hello/world``), the server -will simply serve up the text "Hello world!" +When port 8080 is visited by a browser on the URL ``/hello/world``, the +server will simply serve up the text "Hello world!" Press ``Ctrl-C`` to stop the application. @@ -46,7 +45,7 @@ statements: .. literalinclude:: helloworld.py :linenos: - :lines: 1-2 + :lines: 1-3 The script imports the :class:`~pyramid.config.Configurator` class from the :mod:`pyramid.config` module. An instance of the @@ -59,6 +58,9 @@ protocol to connect an application and a web server together. The convenience, as the ``paste`` package is a dependency of :app:`Pyramid` itself. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -70,8 +72,10 @@ named ``hello_world``. :pyobject: hello_world This function doesn't do anything very difficult. The functions accepts a -single argument (``request``). The ``hello_world`` function returns a value -computed from arguments matched from the url route. +single argument (``request``). The ``hello_world`` function returns an +instance of the :class:`pyramid.response.Response`. The single argument to +the class' constructor is value computed from arguments matched from the url +route. This value becomes the body of the response. This function is known as a :term:`view callable`. A view callable accepts a single argument, ``request``. It is expected to return a @@ -85,16 +89,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 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 @@ -113,7 +112,7 @@ defined imports and function definitions, placed within the confines of an .. literalinclude:: helloworld.py :linenos: - :lines: 7-12 + :lines: 8-13 Let's break this down piece-by-piece. @@ -122,7 +121,7 @@ Configurator Construction .. literalinclude:: helloworld.py :linenos: - :lines: 7-8 + :lines: 8-9 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 @@ -155,41 +154,15 @@ Adding Configuration .. ignore-next-block .. literalinclude:: helloworld.py :linenos: - :lines: 9-10 - -First line is to call the :meth:`pyramid.config.Configurator.add_route` -which registers a :term:`route` to match any url with ``/hello/`` followed -by a string. The :meth:`pyramid.config.Configurator.add_view` method of -a configurator registers a :term:`view configuration` within the -:term:`application registry`. A :term:`view configuration` and -:term:`route 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, route_name='hello')`` 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 ``route_name`` ``predicate`` value of -``hello``. This means that we're instructing -:app:`Pyramid` to invoke the ``hello_world`` view callable if the -:term:`route` is matched is ``hello``. In :app:`Pyramid` the use of a -:term:`route` is only one of ways you can link a url to a :term:`view callable` -and is called :term:`URL Dispatch`. - -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. + :lines: 10-11 + +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. + +The second line, ``config.add_view(hello_world, route_name='hello')``, +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 @@ -201,7 +174,7 @@ WSGI Application Creation .. ignore-next-block .. literalinclude:: helloworld.py :linenos: - :lines: 11 + :lines: 12 After configuring views and ending configuration, the script creates a WSGI *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app` @@ -230,7 +203,7 @@ WSGI Application Serving .. ignore-next-block .. literalinclude:: helloworld.py :linenos: - :lines: 12 + :lines: 13 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 @@ -243,9 +216,9 @@ 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). +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`` in +the terminal we used to start it). Conclusion ~~~~~~~~~~ -- 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/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 55829bef0..45d65402c 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -209,7 +209,7 @@ 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 +"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 don't specify a TCP port number to listen on; this -- cgit v1.2.3 From 8912639e65535a7a6842c48d2773daef1a98aec7 Mon Sep 17 00:00:00 2001 From: alexander-travov Date: Wed, 26 Oct 2011 02:20:42 +0400 Subject: Removing some minor misprints in documentation. --- docs/narr/firstapp.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 45d65402c..ccc2b8b18 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -134,7 +134,7 @@ 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 +``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. @@ -208,7 +208,7 @@ WSGI Application Serving 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 +we wish to serve. We also pass in an argument ``host='0.0.0.0'``, meaning "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 -- cgit v1.2.3 From 5999a8c3ae406902987989cf7c48d3c08b6638cf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 1 Dec 2011 22:26:50 -0800 Subject: Attempt to correct grammar in this paragraph. Uncertain whether it is both technically and grammatically correct now. Please verify. --- docs/narr/firstapp.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index ccc2b8b18..2c8e346b1 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -71,11 +71,11 @@ named ``hello_world``. :linenos: :pyobject: hello_world -This function doesn't do anything very difficult. The functions accepts a +This function doesn't do anything very difficult. The function accepts a single argument (``request``). The ``hello_world`` function returns an -instance of the :class:`pyramid.response.Response`. The single argument to -the class' constructor is value computed from arguments matched from the url -route. This value becomes the body of the response. +instance of the :class:`pyramid.response.Response` class. The single +argument to the class' constructor value is computed from arguments +matched from the url route. This value becomes the body of the response. This function is known as a :term:`view callable`. A view callable accepts a single argument, ``request``. It is expected to return a -- cgit v1.2.3 From f0a1b9b491bab0ac90be6765ddf56a0696d4f863 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 2 Dec 2011 09:44:21 -0600 Subject: Attempted to clean this up further. --- docs/narr/firstapp.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 2c8e346b1..c082f616b 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -71,11 +71,10 @@ named ``hello_world``. :linenos: :pyobject: hello_world -This function doesn't do anything very difficult. The function accepts a -single argument (``request``). The ``hello_world`` function returns an +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 value is computed from arguments -matched from the url route. This value becomes the body of the response. +argument to the class' constructor is a string computed from parameters +matched from the URL. This value becomes the body of the response. This function is known as a :term:`view callable`. A view callable accepts a single argument, ``request``. It is expected to return a @@ -157,7 +156,7 @@ Adding Configuration :lines: 10-11 First line above calls the :meth:`pyramid.config.Configurator.add_route` -method, which registers a :term:`route` to match any url path that begins +method, which registers a :term:`route` to match any URL path that begins with ``/hello/`` followed by a string. The second line, ``config.add_view(hello_world, route_name='hello')``, -- cgit v1.2.3 From 10f1b5c35072c5499f3504dc261fb3c67a90c70d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 16 Dec 2011 04:54:09 -0500 Subject: stamp out paste.httpserver usage --- docs/narr/firstapp.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index c082f616b..922b0ea82 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -54,9 +54,8 @@ The script imports the :class:`~pyramid.config.Configurator` class from the 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. @@ -205,14 +204,17 @@ WSGI Application Serving :lines: 13 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 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. +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 ios , +passing it the ``app`` object (a :term:`router`), which is the 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 -- cgit v1.2.3 From b63a4605608eca76c1b0afac194e189a9220995d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 Jan 2012 04:28:07 -0500 Subject: fix output expectations for wsgiref, add indication that a virtualenv should be used to run helloworld --- docs/narr/firstapp.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 922b0ea82..0d1c9e3c7 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -22,13 +22,21 @@ Here's one of the very simplest :app:`Pyramid` applications: 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: +installed, an HTTP server is started on TCP port 8080. + +On UNIX: + +.. code-block:: text + + $ /path/to/your/virtualenv/bin/python helloworld.py + +On Windows: .. code-block:: text - $ python helloworld.py - serving on 0.0.0.0:8080 view at http://127.0.0.1:8080 + C:\> \path\to\your\virtualenv\Scripts\python 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!" -- cgit v1.2.3 From 7c33c92fb8a85fde5227773c53c812f6cc75891d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 Jan 2012 04:28:46 -0500 Subject: fix Windows break sequence --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 0d1c9e3c7..562fc18c2 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -40,7 +40,7 @@ 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!" -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. -- cgit v1.2.3 From 612f18fc76c2bf96435d38a8a6804e2c49b5587f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 Jan 2012 04:29:49 -0500 Subject: fix Windows break sequence --- docs/narr/firstapp.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 562fc18c2..5e6ce54e0 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -226,8 +226,8 @@ 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`` in -the terminal we used to start it). +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 ~~~~~~~~~~ -- cgit v1.2.3 From 08e5df4288e11957349cf91b863238aea7d8edf1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 Jan 2012 04:33:41 -0500 Subject: guess we have to be drooly here --- docs/narr/firstapp.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 5e6ce54e0..f9439e6cb 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -38,7 +38,9 @@ On Windows: 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!" +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. Press ``Ctrl-C`` (or ``Ctrl-Break`` on Windows) to stop the application. -- cgit v1.2.3 From 6c78bb95850d0ded75b7415b3a639598cb895a74 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 Jan 2012 04:36:43 -0500 Subject: typos --- docs/narr/firstapp.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index f9439e6cb..0565ee7ea 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -220,11 +220,10 @@ 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 ios , -passing it the ``app`` object (a :term:`router`), which is the 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. +which is 8080, passing it as the second argument. The final argument is the +``app`` object (a :term:`router`), which is the 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 -- cgit v1.2.3 From b95a5e23b2db563d069d5ab1e40663bf1c26cc20 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 Jan 2012 04:47:35 -0500 Subject: ugh --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 0565ee7ea..8511647ac 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -34,7 +34,7 @@ On Windows: .. code-block:: text - C:\> \path\to\your\virtualenv\Scripts\python helloworld.py + C:\> \path\to\your\virtualenv\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 -- cgit v1.2.3 From b20d68703af695c80e7844e8aae61ccf31cedaaa Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 16 Jan 2012 04:59:21 -0500 Subject: explain logging --- docs/narr/firstapp.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 8511647ac..1ca188d7e 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -42,6 +42,12 @@ 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. +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`` (or ``Ctrl-Break`` on Windows) to stop the application. Now that we have a rudimentary understanding of what the application does, -- cgit v1.2.3 From c746ba4d0893ed7f4322492fdba548f3cd2a1ac5 Mon Sep 17 00:00:00 2001 From: Wayne Witzel III Date: Fri, 3 Aug 2012 00:44:41 -0700 Subject: Adding helpful link to installing chapter from first app --- docs/narr/firstapp.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 1ca188d7e..a86826d86 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -8,7 +8,8 @@ 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: -- cgit v1.2.3 From a0243a5264371a3e69fd188cee17c6fbfd8341a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Fidosz?= Date: Sun, 5 Aug 2012 10:33:07 +0200 Subject: fixed line numbers in firstapp --- docs/narr/firstapp.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index a86826d86..dbdc48549 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -127,7 +127,7 @@ defined imports and function definitions, placed within the confines of an .. literalinclude:: helloworld.py :linenos: - :lines: 8-13 + :lines: 9-15 Let's break this down piece-by-piece. @@ -136,7 +136,7 @@ Configurator Construction .. literalinclude:: helloworld.py :linenos: - :lines: 8-9 + :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 @@ -169,7 +169,7 @@ Adding Configuration .. ignore-next-block .. literalinclude:: helloworld.py :linenos: - :lines: 10-11 + :lines: 11-12 First line above calls the :meth:`pyramid.config.Configurator.add_route` method, which registers a :term:`route` to match any URL path that begins @@ -189,7 +189,7 @@ WSGI Application Creation .. ignore-next-block .. literalinclude:: helloworld.py :linenos: - :lines: 12 + :lines: 13 After configuring views and ending configuration, the script creates a WSGI *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app` @@ -218,7 +218,7 @@ WSGI Application Serving .. ignore-next-block .. literalinclude:: helloworld.py :linenos: - :lines: 13 + :lines: 14 Finally, we actually serve the application to requestors by starting up a WSGI server. We happen to use the :mod:`wsgiref` ``make_server`` server -- cgit v1.2.3 From eb403ffe22501ae0546c02c7c24b54b5e3d1eb83 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 23 Aug 2012 09:57:35 -0500 Subject: exposed the serve_forever line to the helloworld narrative --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index dbdc48549..ccaa6e9e2 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -218,7 +218,7 @@ WSGI Application Serving .. ignore-next-block .. literalinclude:: helloworld.py :linenos: - :lines: 14 + :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 -- cgit v1.2.3 From 10bf7ee0e6eba03e693a15c68048c7568dbba3ec Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 29 Dec 2012 07:43:35 +0200 Subject: typo --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index ccaa6e9e2..0b85d68d3 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -228,7 +228,7 @@ 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 the application we wish to +``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. -- cgit v1.2.3 From 8e5b2d196a1d7825ecd59a39709ef0dbd2c134e1 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 16 Jan 2013 00:39:52 +0200 Subject: improve flow --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 0b85d68d3..9aea50185 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -200,7 +200,7 @@ and various other configuration settings have been performed). The 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 +but you can learn more about it by visiting `wsgi.org `_. The :app:`Pyramid` application object, in particular, is an instance of a -- cgit v1.2.3 From 362d8b0548410e7ab3e28d0d420342121496a1d2 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 16 Jan 2013 00:44:45 +0200 Subject: improve flow --- docs/narr/firstapp.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 0b85d68d3..45cb917f7 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -194,8 +194,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 set up views, -and various other configuration settings have been performed). The +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 -- cgit v1.2.3 From e241c7e479b411a7f465b0a3d86021301702f8af Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 18 Jan 2013 23:58:04 +0200 Subject: make example links clickable, for convenience --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 0b85d68d3..50aa02692 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -40,7 +40,7 @@ On Windows: 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`` +running on your local system, using ``_ in a browser will show this result. Each time you visit a URL served by the application in a browser, a logging -- cgit v1.2.3 From 04a662656deeafe0a8db61d29c64733181badb73 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 11:55:14 +0200 Subject: DRY --- docs/narr/firstapp.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index d61d95685..ab6a46c2f 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -175,9 +175,9 @@ 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. -The second line, ``config.add_view(hello_world, route_name='hello')``, -registers the ``hello_world`` function as a :term:`view callable` and makes -sure that it will be called when the ``hello`` route is matched. +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 -- cgit v1.2.3 From f73f0e332658fac2583f51247dcd49bd36d63ce4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Mar 2013 23:05:17 +0200 Subject: consistency: use $VENV whenever virtualenv binaries are used --- docs/narr/firstapp.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index ab6a46c2f..6d3786d8e 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -29,13 +29,13 @@ On UNIX: .. code-block:: text - $ /path/to/your/virtualenv/bin/python helloworld.py + $ $VENV/bin/python helloworld.py On Windows: .. code-block:: text - C:\> \path\to\your\virtualenv\Scripts\python.exe helloworld.py + 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 -- cgit v1.2.3 From 1ad8de2b9032b5a452b75274b8f908645c732e57 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 22 Mar 2013 17:24:32 +0200 Subject: remove unused ignore-next-block directive --- docs/narr/firstapp.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 6d3786d8e..e73ef66ac 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -166,7 +166,6 @@ the application. Adding Configuration ~~~~~~~~~~~~~~~~~~~~ -.. ignore-next-block .. literalinclude:: helloworld.py :linenos: :lines: 11-12 @@ -186,7 +185,6 @@ The second line registers the ``hello_world`` function as a WSGI Application Creation ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. ignore-next-block .. literalinclude:: helloworld.py :linenos: :lines: 13 @@ -215,7 +213,6 @@ to its ``add_view`` and ``add_route`` methods. WSGI Application Serving ~~~~~~~~~~~~~~~~~~~~~~~~ -.. ignore-next-block .. literalinclude:: helloworld.py :linenos: :lines: 14-15 -- cgit v1.2.3 From cbd2b039e5c57df5f17ef543c52056bc983f8ccf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 4 Oct 2015 02:14:38 -0700 Subject: grammar, rst heading underline fixes --- docs/narr/firstapp.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index e73ef66ac..ee7511770 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -4,7 +4,7 @@ .. _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 @@ -52,7 +52,7 @@ done by the wsgiref server we've used to serve this application. It logs an 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 ~~~~~~~ @@ -129,7 +129,7 @@ defined imports and function definitions, placed within the confines of an :linenos: :lines: 9-15 -Let's break this down piece-by-piece. +Let's break this down piece by piece. Configurator Construction ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -145,7 +145,7 @@ 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 +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 @@ -170,7 +170,7 @@ Adding Configuration :linenos: :lines: 11-12 -First line above calls the :meth:`pyramid.config.Configurator.add_route` +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. @@ -220,7 +220,7 @@ WSGI Application Serving 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 +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, -- cgit v1.2.3 From f9abe1811133966d99ae2321d9fc24e86fd22f7f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 8 Oct 2015 23:27:15 -0700 Subject: wrap 79 cols --- docs/narr/firstapp.rst | 183 ++++++++++++++++++++++++------------------------- 1 file changed, 90 insertions(+), 93 deletions(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index ee7511770..b85c1f3d1 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -37,17 +37,17 @@ On Windows: 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 ``_ -in a browser will show this result. +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 ``_ in a browser +will show this result. 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. +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`` (or ``Ctrl-Break`` on Windows) to stop the application. @@ -57,8 +57,7 @@ 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: .. literalinclude:: helloworld.py :linenos: @@ -71,32 +70,32 @@ The script imports the :class:`~pyramid.config.Configurator` class from the Like many other Python web frameworks, :app:`Pyramid` uses the :term:`WSGI` protocol to connect an application and a web server together. The -:mod:`wsgiref` server is used in this example as a WSGI server for -convenience, as it is shipped within the Python standard library. +: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. +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 a function -named ``hello_world``. +The above script, beneath its set of imports, defines a function named +``hello_world``. .. literalinclude:: helloworld.py :linenos: :pyobject: 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. +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. -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. +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 @@ -105,10 +104,10 @@ 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 :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. +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 @@ -120,10 +119,10 @@ a string is passed as the body to the response. 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: .. literalinclude:: helloworld.py :linenos: @@ -140,26 +139,26 @@ Configurator Construction 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 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. +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 an :term:`application registry` associated with -the application. +registrations to be made in an :term:`application registry` associated with the +application. .. _adding_configuration: @@ -171,12 +170,12 @@ Adding Configuration :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. +method, which registers a :term:`route` to match any URL path that begins with +``/hello/`` followed by a string. -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. +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 @@ -190,25 +189,24 @@ WSGI Application Creation :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 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 -`_. - -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. +*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 `_. + +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 ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -217,37 +215,36 @@ WSGI Application Serving :linenos: :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). +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`. - -- cgit v1.2.3 From a54e4cf75402575ba7b12a03acc0738126c16e2d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 8 Oct 2015 23:52:05 -0700 Subject: wrap 79 cols --- docs/narr/firstapp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/firstapp.rst') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index b85c1f3d1..6a952dec9 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -190,7 +190,7 @@ 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 +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 -- cgit v1.2.3