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/glossary.rst | 12 +++++++++ docs/narr/project.rst | 71 +++++++++++++++++++++++++++++++-------------------- 2 files changed, 56 insertions(+), 27 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index e4de15bd6..8307c0472 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -983,3 +983,15 @@ Glossary :meth:`pyramid.path.AssetResolver.resolve` method. It supports the methods and attributes documented in :class:`pyramid.interfaces.IAssetDescriptor`. + + Waitress + A :term:`WSGI` server that runs on UNIX and Windows under Python 2.6+ + and Python 3.2+. Projects generated via Pyramid scaffolding use + Waitress as a WGSI server. See + http://docs.pylonsproject.org/projects/waitress/en/latest/ for detailed + information. + + Green Unicorn + Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under + Python 2.5+ (although at the time of this writing does not support + Python 3). See http://gunicorn.org/ for detailed information. 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