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') 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') 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') 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') 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') 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') 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') 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 c3a36b9b11b9414caabff957e07d4baa2d3367ad Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 18 Jan 2012 16:38:36 -0500 Subject: untangle some docs about using alternate wsgi servers (divide into 2 sections, one about pserve, the other about waitress vs. others) --- docs/narr/project.rst | 71 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 44 insertions(+), 27 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 896b65249..5696b0b73 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -881,37 +881,54 @@ configuration as would be loaded if you were running your Pyramid application via ``pserve``. This can be a useful debugging tool. See :ref:`interactive_shell` for more details. -.. _alternate_wsgi_server: +What Is This ``pserve`` Thing +----------------------------- -Using an Alternate WSGI Server ------------------------------- - -The code generated by :app:`Pyramid` scaffolding assumes that you will be +The code generated by an :app:`Pyramid` scaffold assumes that you will be using the ``pserve`` command to start your application while you do -development. The default rendering of Pyramid scaffolding uses the -*waitress* WSGI server, which is a server that is suited for production -usage. It's not very fast, or very featureful: its main feature is that it -works on all platforms and all systems, making it a good choice as a default -server from the perspective of Pyramid's developers. +development. ``pserve`` is a command that reads a :term:`PasteDeploy` +``.ini`` file (e.g. ``development.ini``) and configures a server to serve a +Pyramid application based on the data in the file. ``pserve`` is by no means the only way to start up and serve a :app:`Pyramid` application. As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be invoked at all to run a :app:`Pyramid` application. The use of ``pserve`` to run a :app:`Pyramid` application is purely conventional based on the output -of its scaffold. - -Any :term:`WSGI` server is capable of running a :app:`Pyramid` application. -Some WSGI servers don't require the :term:`PasteDeploy` framework's -``pserve`` command to do server process management at all. Each :term:`WSGI` -server has its own documentation about how it creates a process to run an -application, and there are many of them, so we cannot provide the details for -each here. But the concepts are largely the same, whatever server you happen -to use. - -One popular production alternative to a ``pserve``-invoked server is -:term:`mod_wsgi`. You can also use :term:`mod_wsgi` to serve your -:app:`Pyramid` application using the Apache web server rather than any -"pure-Python" server that is started as a result of ``pserve``. See -:ref:`modwsgi_tutorial` for details. However, it is usually easier to -*develop* an application using a ``pserve`` -invoked webserver, as -exception and debugging output will be sent to the console. +of its scaffolding. But we strongly recommend using while developing your +application, because many other convenience introspection commands (such as +``pviews``, ``prequest``, ``proutes`` and others) are also implemented in +terms of configuration availaibility of this ``.ini`` file format. It also +configures Pyramid logging and provides the ``--reload`` switch for +convenient restarting of the server when code changes. + +.. _alternate_wsgi_server: + +Using an Alternate WSGI Server +------------------------------ + +Pyramid scaffolds generate projects which use the :term:`Waitress` WSGI +server. Waitress is a server that is suited for development and light +production usage. It's not the fastest nor the most featureful WSGI server. +Instead, its main feature is that it works on all platforms that Pyramid +needs to run on, making it a good choice as a default server from the +perspective of Pyramid's developers. + +Any WSGI server is capable of running a :app:`Pyramid` application. But we +suggest you stick with the default server for development, and that you wait +to investigate other server options until you're ready to deploy your +application to production. Unless for some reason you need to develop on a +non-local system, investigating alternate server options is usually a +distraction until you're ready to deploy. But we recommend developing using +the default configuration on a local system that you have complete control +over; it will provide the best development experience. + +One popular production alternative to the default Waitress server is +:term:`mod_wsgi`. You can use mod_wsgi to serve your :app:`Pyramid` +application using the Apache web server rather than any "pure-Python" server +like Waitress. It is fast and featureful. See :ref:`modwsgi_tutorial` for +details. + +Another good production alternative is :term:`Green Unicorn` (aka +``gunicorn``). It's faster than Waitress and slightly easier to configure +than mod_wsgi, although it depends, in its default configuration, on having a +buffering HTTP proxy in front of it. -- cgit v1.2.3