From 71b83e5ea328b654f8463f567ecc054a55a7a90b Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Tue, 6 Aug 2013 10:12:42 -0400 Subject: Move sample code into subdirectories. Add sections for requests and views. --- docs/getting_started/quick_glance.rst | 180 ++++++++++++++++++++++------------ 1 file changed, 117 insertions(+), 63 deletions(-) (limited to 'docs/getting_started/quick_glance.rst') diff --git a/docs/getting_started/quick_glance.rst b/docs/getting_started/quick_glance.rst index da65f2e51..d58303e29 100644 --- a/docs/getting_started/quick_glance.rst +++ b/docs/getting_started/quick_glance.rst @@ -3,92 +3,141 @@ Quick Glance ============ Pyramid lets you start small and finish big. This :doc:`index` guide -walks you through many of the key features. Let's put the emphasis on -*start* by doing a quick tour through Pyramid. - -This *Quick Glance* is provides snippets instead of full examples. For -working code, see the *Getting Started* chapters on each topic. +walks you through many of Pyramid's key features. Let's put the +emphasis on *start* by doing a quick tour through Pyramid, with +snippets of code to illustrate major concepts. .. note:: Like the rest of Getting Started, we're using Python 3 in - our samples. You can too, or you can use Python 2.7. + our samples. Pyramid was one of the first (October 2011) web + frameworks to fully support Python 3. You can use Python 3 + as well for this guide, but you can also use Python 2.7. -Setup -===== +Python Setup +============ -This is just a "quick glance", so we won't kill ourselves showing -installation details. The guides fully cover each topic, -including setup. In a nutshell: +First things first: we need our Python environment in ship-shape. +Pyramid encourages standard Python development practices (virtual +environments, packaging tools, etc.) so let's get our working area in +place. For Python 3.3: .. code-block:: bash $ pyvenv-3.3 env33 $ source env33/bin/activate - $ curl -O http://python-distribute.org/distribute_setup.py - $ python3.3 ./distribute_setup.py - $ rm distribute* + $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python $ easy_install-3.3 pip - $ pip-3.3 install pyramid -We use Python 3.3's builtin virtual environment tool ``pyvenv`` to make -an isolated Python. It is so isolated, we don't have package -installation tools! After setting those up and cleaning up, -we install Pyramid into our virtual environment. +We make a :term:`virtualenv` then activate it. We then get Python +packaging tools installed so we can use the popular ``pip`` tool for +installing packages. Normal first steps for any Python project. -.. note:: +Pyramid Installation +==================== - Note the use of ``3.3`` on many of the commands, as a way to emphasize - in this document which versions of the commands we are using. This is - optional. +We now have a standard starting point for Python. Getting Pyramid +installed is easy: +.. code-block:: bash + $ pip install pyramid -The Smallest -============ +Our virtual environment now has the Pyramid software available to its +Python. + +Hello World +=========== Microframeworks have shown that learning starts best from a very small first step. Here's a tiny application in Pyramid: -.. literalinclude:: quick_glance/app1.py +.. literalinclude:: quick_glance/hello_world/app.py + :linenos: This simple example is easy to run. Save this as ``app.py`` and run it: .. code-block:: bash - $ python3 ./app.py + $ python ./app.py -Finally, open `http://localhost:8081/ `_ in a +Next, open `http://localhost:6543/ `_ in a browser and you will see the ``Hello World!`` message. -At a high level, we wrote a Python module, which when executed, -started an HTTP server. This HTTP server ran a WSGI application with -one "view". This view handled the ``http://localhost:8081/`` URL. +New to Python web programming? If so, some lines in module merit +explanation: -More specifically: +#. *Line 10*. ``if __name__ == '__main__':`` is Python's way of + saying "Start here when running from the command line". -#. We imported an HTTP server (``make_server``), a configuration system - (``Configurator``), and a way to send HTTP responses (``Response``). +#. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect + :term:`view` code to particular URL :term:`route`. -#. We made a ``hello_world`` function that returned a ``Response``. +#. *Lines 6-7*. Implement the view code that generates the + :term:`response`. -#. Our ``main`` function started the configuration, added a "route", - and then mapped that route to a "view". +#. *Lines 14-16*. Publish a :term:`WSGI` app using an HTTP server. -#. To finish, we then made a WSGI app and served it. - ``if __name__ == '__main__':`` is a standard Python technique to - execute code when it is run from the command line instead of - imported into another module. +Handling Web Requests With webob +================================ -.. note:: +Developing for the web means processing web requests. As this is a +critical part of a web application, web developers need a robust, +mature set of software for web requests. + +Pyramid has always fit nicely into the existing world of Python web +development (virtual environments, packaging, scaffolding, +first to embrace Python 3, etc.) For request handling, Pyramid turned +to the well-regarded :term:`WebOb` Python library for request and +response handling. In our example +above, Pyramid hands ``hello_world`` a ``request`` that is +:ref:`based on WebOb `. + +Let's see some features of requests and responses in action: + +.. literalinclude:: quick_glance/requests/app.py + :pyobject: hello_world + + + +Views +===== - The configuration of the route and the view are split. Other systems - let you bundle those together. Pyramid makes you do the extra step, - but for a reason: this lets you control the ordering. More on this - later. +In the example above, the ``hello_world`` function is a "view" (or more +specifically, a :term:`view callable`. Views are the primary way to +accept web requests and return responses. -Using Decorators and Matchdicts -=============================== +So far the view, its registration with the configuration, and the route +to map it to a URL are all in the same Python module as the WSGI +application launching. Let's move the views out to their own ``views +.py`` module and change the ``app.py`` to scan that module looking for +decorators that setup the views. First, our revised ``app.py``: + +.. literalinclude:: quick_glance/views/app.py + :linenos: + +We added some more routes, but we also removed the view code. +Our views, and their registrations (via decorators) are now in a module +``views.py`` which is scanned via: + +.. code-block:: python + + config.scan('views') + +Our ``views.py`` is now more self-contained: + +.. literalinclude:: quick_glance/views/views.py + :linenos: + + + +- Raise exception, redirect +- Change header +- request object +- "callable" + +Routing With Decorators and Matchdicts +====================================== Let's repeat the smallest step, but make it a little more functional and elegant by adding: @@ -101,20 +150,27 @@ and elegant by adding: Let's make update our ``app.py`` module: -.. literalinclude:: quick_glance/app2.py +.. literalinclude:: quick_glance/routing/app.py :linenos: -When you run ``python3 ./app.py`` and visit a URL such as -``http://localhost:8081/hello/amy``, the response includes ``amy`` in +When you run ``python ./app.py`` and visit a URL such as +``http://localhost:6543/hello/amy``, the response includes ``amy`` in the HTML. This module, while small, starts to show how many Pyramid applications are composed: -#. We use a decorator around the view, to put the configuration closer - to the code. +#. *Line 7*. Pyramid's configuration supports + :term:`imperative configuration`, such as the ``config.add_view`` in + the previous example. You can also use + :term:`declarative configuration`, in which a Python + :term:`decorator` is placed on the line above the view. + +#. *Line 14*. When setting up the route, mark off a section of the URL + to be data available to the view's :term:`matchdict`. + +#. *Line 15*. Tell the configurator to go look for decorators. -#. We tell the ``Configurator`` to go look for decorators. Templates ========= @@ -139,7 +195,7 @@ argument tell Pyramid to pass the response through Jinja2: .. code-block:: python - @view_config(route_name='hello', renderer="app3.jinja2") + @view_config(route_name='hello', renderer="hello_world.jinja2") def hello_world(request): return dict(name=request.matchdict['name']) @@ -170,7 +226,7 @@ Pyramid will serve some static assets. First, another call to the config.add_static_view(name='static', path='static') This tells our WSGI application to map requests under -``http://localhost:8081/static/`` to files and directories inside a +``http://localhost:6543/static/`` to files and directories inside a ``static`` directory alongside our Python module. Next, make a directory ``static`` and place ``app.css`` inside: @@ -309,7 +365,7 @@ instructions*, we need to install this as a development package: .. code-block:: bash $ cd hello_world - $ python3.3 ./setup.py develop + $ python ./setup.py develop What did we get? A top-level directory ``hello_world`` that includes some packaging files and a subdirectory ``hello_world`` that has @@ -444,7 +500,7 @@ First, change your ``setup.py`` to say: .. code-block:: bash - $ python3.3 ./setup.py develop + $ python ./setup.py develop The Python package was now installed into our environment but we haven't told our web app to use it. We can do so imperatively in code: @@ -489,7 +545,7 @@ the ``coverage`` tool which yells at us for code that isn't tested: ) We changed ``setup.py`` which means we need to re-run -``python3.3 ./setup.py develop``. We can now run all our tests: +``python ./setup.py develop``. We can now run all our tests: .. code-block:: bash @@ -626,7 +682,7 @@ scaffold! $ pcreate --scaffold alchemy hello_sqlalchemy $ cd hello_sqlalchemy - $ python3.3 setup.py develop + $ python setup.py develop We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a console script to @@ -714,8 +770,6 @@ Authorization Notes -- Change 8081 -> 6543 - - See also, interlinking, teasers or "3 Extras" at the end of each section, links to a downloadable version of the Python module @@ -733,4 +787,4 @@ Notes - Explain and link to WSGI, Python Packages -- Richer routing \ No newline at end of file +- Richer routing -- cgit v1.2.3