From ae901436a61563968cc31cc636f1fbeb5e85b528 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Sun, 11 Aug 2013 09:53:00 -0400 Subject: Per discussion with Chris, just wrap up "getting started" as the Quick Tour. Still need to do more linking and perhaps add a section on root factories, authorization, authentication. --- docs/quick_tour.rst | 789 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 789 insertions(+) create mode 100644 docs/quick_tour.rst (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst new file mode 100644 index 000000000..cc4afe67d --- /dev/null +++ b/docs/quick_tour.rst @@ -0,0 +1,789 @@ +===================== +Quick Tour of Pyramid +===================== + +Pyramid lets you start small and finish big. This *Quick Tour* guide +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:: + + We use Python 3 in 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. + +Python Setup +============ + +First things first: we need our Python environment in ship-shape. +Pyramid encourages standard Python development practices (virtual +environments, packaging tools, logging, 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 + $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python + $ easy_install-3.3 pip + +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. + +Pyramid Installation +==================== + +We now have a standard starting point for Python. Getting Pyramid +installed is easy: + +.. code-block:: bash + + $ pip install pyramid + +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_tour/hello_world/app.py + :linenos: + +This simple example is easy to run. Save this as ``app.py`` and run it: + +.. code-block:: bash + + $ python ./app.py + +Next, open `http://localhost:6543/ `_ in a +browser and you will see the ``Hello World!`` message. + +New to Python web programming? If so, some lines in module merit +explanation: + +#. *Line 10*. The ``if __name__ == '__main__':`` is Python's way of + saying "Start here when running from the command line". + +#. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect + :term:`view` code to particular URL :term:`route`. + +#. *Lines 6-7*. Implement the view code that generates the + :term:`response`. + +#. *Lines 14-16*. Publish a :term:`WSGI` app using an HTTP server. + +As shown in this example, the :term:`configurator` plays a central role +in Pyramid development. Building an application from loosely-coupled +parts via :doc:`../narr/configuration` is a central idea in Pyramid, +one that we will revisit regurlarly in this *Quick Tour*. + +Handling Web Requests and Responses +=================================== + +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_tour/requests/app.py + :pyobject: hello_world + +In this Pyramid view, we get the URL being visited from ``request.url``. +Also, if you visited ``http://localhost:6543/?name=alice``, +the name is included in the body of the response:: + + URL http://localhost:6543/?name=alice with name: alice + +Finally, we set the response's content type and return the Response. + +Views +===== + +For the examples above, the ``hello_world`` function is a "view". In +Pyramid, views are the primary way to accept web requests and return +responses. + +So far our examples place everything in one file: + +- the view function + +- its registration with the configurator + +- the route to map it to a URL + +- the WSGI application launcher + +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_tour/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 ``config.scan('views')``. + +We now have a ``views.py`` module that is focused on handling requests +and responses: + +.. literalinclude:: quick_tour/views/views.py + :linenos: + +We have 4 views, each leading to the other. If you start at +``http://localhost:6543/``, you get a response with a link to the next +view. The ``hello_view`` (available at the URL ``/howdy``) has a link +to the ``redirect_view``, which shows issuing a redirect to the final +view. + +Earlier we saw ``config.add_view`` as one way to configure a view. This +section introduces ``@view_config``. 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. Both approaches result in the same final +configuration, thus usually, it is simply a matter of taste. + + +Routing +======= + +Writing web applications usually means sophisticated URL design. We +just saw some Pyramid machinery for requests and views. Let's look at +features that help in routing. + +Above we saw the basics of routing URLs to views in Pyramid: + +- Your project's "setup" code registers a route name to be used when + matching part of the URL + +- Elsewhere, a view is configured to be called for that route name + +.. note:: + + Why do this twice? Other systems don't make us repeat this! As + illustrated in :ref:`routes_need_ordering`, multiple routes might + match the same URL pattern. Rather than provide ways to help guess, + Pyramid lets you be explicit in ordering. Pyramid also gives + facilities to avoid the problem. + +What if we want part of the URL to be available as data in my view? This +route declaration: + +.. literalinclude:: quick_tour/routing/app.py + :start-after: Start Route 1 + :end-before: End Route 1 + +With this, URLs such as ``/howdy/amy/smith`` will assign ``amy`` to +``first`` and ``smith`` to ``last``. We can then use this data in our +view: + +.. literalinclude:: quick_tour/routing/views.py + :start-after: Start Route 1 + :end-before: End Route 1 + +``request.matchdict`` contains values from the URL that match the +"replacement patterns" (the curly braces) in the route declaration. +This information can then be used in your view. + +As you might imagine, Pyramid provides +:doc:`many more features in routing <../narr/urldispatch>` +(route factories, custom predicates, security statements, +etc.) We will see more features later in *Geting Started*. + +Templating +========== + +Ouch. We have been making our own ``Response`` and filling the response +body with HTML. You usually won't embed an HTML string directly in +Python, but instead, will use a templating language. + +Pyramid doesn't mandate a particular database system, form library, +etc. It encourages replaceability. This applies equally to templating, +which is fortunate: developers have strong views about template +languages. That said, Pyramid bundles Chameleon and Mako, +so in this step, let's use Chameleon as an example: + +.. literalinclude:: quick_tour/templating/views.py + :start-after: Start View 1 + :end-before: End View 1 + +Ahh, that looks better. We have a view that is focused on Python code. +Our ``@view_config`` decorator specifies a :term:`renderer` that points +our template file. Our view then simply returns data which is then +supplied to our template: + +.. literalinclude:: quick_tour/templating/hello_world.pt + :language: html + +Since our view returned ``dict(name=request.matchdict['name'])``, +we can use ``name`` as a variable in our template via +``${name}``. + +Templating With ``jinja2`` +========================== + +We just said Pyramid doesn't prefer one templating language over +another. Time to prove it. Jinja2 is a popular templating system, +modelled after Django's templates. Let's add ``pyramid_jinja2``, +a Pyramid :term:`add-on` which enables Jinja2 as a :term:`renderer` in +our Pyramid applications: + +.. code-block:: bash + + $ pip install pyramid_jinja2 + +With the package installed, we can include the template bindings into +our configuration: + +.. code-block:: python + + config.include('pyramid_jinja2') + +The only change in our view...point the renderer at the ``.jinja2`` file: + +.. literalinclude:: quick_tour/jinja2/views.py + :start-after: Start View 1 + :end-before: End View 1 + +Our Jinja2 template is very similar to our previous template: + +.. literalinclude:: quick_tour/jinja2/hello_world.jinja2 + :language: jinja + +Pyramid's templating add-ons register a new kind of renderer into your +application. The renderer registration maps to different kinds of +filename extensions. In this case, changing the extension from ``.pt`` +to ``.jinja2`` passed the view response through the ``pyramid_jinja2`` +renderer. + +.. note:: + + At the time of this writing, Jinja2 had not released a version + compatible with Python 3.3. + + +Static Assets +============= + +Of course the Web is more than just markup. You need static assets: +CSS, JS, and images. Let's point our web app at a directory where +Pyramid will serve some static assets. First, another call to the +:term:`configurator`: + +.. literalinclude:: quick_tour/static_assets/app.py + :start-after: Start Static 1 + :end-before: End Static 1 + +This tells our WSGI application to map requests under +``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: + +.. literalinclude:: quick_tour/static_assets/static/app.css + :language: css + +All we need to do now is point to it in the ```` of our Jinja2 +template: + +.. literalinclude:: quick_tour/static_assets/hello_world.pt + :language: html + :start-after: Start Link 1 + :end-before: End Link 1 + +This link presumes that our CSS is at a URL starting with ``/static/``. +What if the site is later moved under ``/somesite/static/``? Or perhaps +web developer changes the arrangement on disk? Pyramid gives a helper +that provides flexibility on URL generation: + +.. literalinclude:: quick_tour/static_assets/hello_world.pt + :language: html + :start-after: Start Link 2 + :end-before: End Link 2 + +By using ``request.static_url`` to generate the full URL to the static +assets, you both ensure you stay in sync with the configuration and +gain refactoring flexibility later. + +Returning JSON +============== + +Modern web apps are more than rendered HTML. Dynamic pages now use +JavaScript to update the UI in the browser by requesting server data as +JSON. Pyramid supports this with a JSON renderer: + +.. literalinclude:: quick_tour/json/views.py + :start-after: Start View 1 + :end-before: End View 2 + +This wires up a view that returns some data through the JSON +:term:`renderer`, which calls Python's JSON support to serialize the data +into JSON and set the appropriate HTTP headers. + +View Classes +============ + +So far our views have been simple, free-standing functions. Many times +your views are related: different ways to look at or work on the same +data or a REST API that handles multiple operations. Grouping these +together as a +:ref:`view class ` makes sense: + +- Group views + +- Centralize some repetitive defaults + +- Share some state and helpers + +The following shows a "Hello World" example with three operations: view +a form, save a change, or press the delete button: + +.. literalinclude:: quick_tour/view_classes/views.py + :start-after: Start View 1 + :end-before: End View 1 + +As you can see, the three views are logically grouped together. +Specifically: + +- The first view is returned when you go to ``/howdy/amy``. This URL is + mapped to the ``hello`` route that we centrally set using the optional + ``@view_defaults``. + +- The second view is returned when the form data contains a field with + ``form.edit``, such as clicking on + ````. This rule + is specified in the ``@view_config`` for that view. + +- The third view is returned when clicking on a button such + as ````. + +Only one route needed, stated in one place atop the view class. Also, +the assignment of the ``name`` is done in the ``__init__``. Our +templates can then use ``{{ view.name }}``. + +Quick Project Startup with Scaffolds +==================================== + +So far we have done all of our *Quick Glance* as a single Python file. +No Python packages, no structure. Most Pyramid projects, though, +aren't developed this way. + +To ease the process of getting started, Pyramid provides *scaffolds* +that generate sample projects from templates in Pyramid and Pyramid +add-ons. Pyramid's ``pcreate`` command can list the available scaffolds: + +.. code-block:: bash + + $ pcreate --list + Available scaffolds: + alchemy: Pyramid SQLAlchemy project using url dispatch + pyramid_jinja2_starter: pyramid jinja2 starter project + starter: Pyramid starter project + zodb: Pyramid ZODB project using traversal + +The ``pyramid_jinja2`` add-on gave us a scaffold that we can use. From +the parent directory of where we want our Python package to be generated, +let's use that scaffold to make our project: + +.. code-block:: bash + + $ pcreate --scaffold pyramid_jinja2_starter hello_world + +We next use the normal Python development to setup our package for +development: + +.. code-block:: bash + + $ cd hello_world + $ python ./setup.py develop + +We are moving in the direction of a full-featured Pyramid project, +with a proper setup for Python standards (packaging) and Pyramid +configuration. This includes a new way of running your application: + +.. code-block:: bash + + $ pserve development.ini + +Let's look at ``pserve`` and configuration in more depth. + +Application Running with ``pserve`` +=================================== + +Prior to scaffolds, our project mixed a number of operations details +into our code. Why should my main code care with HTTP server I want and +what port number to run on? + +``pserve`` is Pyramid's application runner, separating operational +details from your code. When you install Pyramid, a small command +program called ``pserve`` is written to your ``bin`` directory. This +program is an executable Python module. It's very small, getting most +of its brains via import. + +You can run ``pserve`` with ``--help`` to see some of its options. +Doing so reveals that you can ask ``pserve`` to watch your development +files and reload the server when they change: + +.. code-block:: bash + + $ pserve development.ini --reload + +The ``pserve`` command has a number of other options and operations. +Most of the work, though, comes from your project's wiring, as +expressed in the configuration file you supply to ``pserve``. Let's +take a look at this configuration file. + +Configuration with ``.ini`` Files +================================= + +Earlier in *Quick Glance* we first met Pyramid's configuration system. +At that point we did all configuration in Python code. For example, +the port number chosen for our HTTP server was right there in Python +code. Our scaffold has moved this decision, and more, into the +``development.ini`` file: + +.. literalinclude:: quick_tour/package/development.ini + :language: ini + +Let's take a quick high-level look. First, the ``.ini`` file is divided +into sections: + +- ``[app:hello_world]`` configures our WSGI app + +- ``[pipeline:main]`` sets up our WSGI "pipeline" + +- ``[server:main]`` holds our WSGI server settings + +- Various sections afterwards configure our Python logging system + +We have a few decisions made for us in this configuration: + +#. *Choice of web server*. The ``use = egg:pyramid#wsgiref`` tell + ``pserve`` to the ``wsgiref`` server that is wrapped in the Pyramid + package. + +#. *Port number*. ``port = 6543`` tells ``wsgiref`` to listen on port + 6543. + +#. *WSGI app*. What package has our WSGI application in it? + ``use = egg:hello_world`` in the app section tells the + configuration what application to load. + +#. *Easier development by automatic template reloading*. In development + mode, you shouldn't have to restart the server when editing a Jinja2 + template. ``reload_templates = true`` sets this policy, + which might be different in production. + +Additionally, the ``development.ini`` generated by this scaffold wired +up Python's standard logging. We'll now see in the console, for example, +a log on every request that comes in, as well traceback information. + +Easier Development with ``debugtoolbar`` +======================================== + +As we introduce the basics we also want to show how to be productive in +development and debugging. For example, we just discussed template +reloading and earlier we showed ``--reload`` for application reloading. + +``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes +several tools available in your browser. Adding it to your project +illustrates several points about configuration. + +First, change your ``setup.py`` to say: + +.. literalinclude:: quick_tour/package/setup.py + :start-after: Start Requires + :end-before: End Requires + +...and re-run your setup: + +.. code-block:: bash + + $ python ./setup.py develop + +The Python package was now installed into our environment. The package +is a Pyramid add-on, which means we need to include its configuration +into our web application. We could do this with imperative +configuration, as we did above for the ``pyramid_jinja2`` add-on: + +.. literalinclude:: quick_tour/package/hello_world/__init__.py + :start-after: Start Include + :end-before: End Include + +Now that we have a configuration file, we can use the +``pyramid.includes`` facility and place this in our +``development.ini`` instead: + +.. literalinclude:: quick_tour/package/development.ini + :language: ini + :start-after: Start Includes + :end-before: End Includes + +You'll now see an attractive (and +collapsible) menu in the right of your browser, providing introspective +access to debugging information. Even better, if your web application +generates an error, you will see a nice traceback on the screen. When +you want to disable this toolbar, no need to change code: you can +remove it from ``pyramid.includes`` in the relevant ``.ini`` +configuration file. + +Unit Tests and ``nose`` +======================= + +Yikes! We got this far and we haven't yet discussed tests. Particularly +egregious, as Pyramid has had a deep commitment to full test coverage +since before it was released. + +Our ``pyramid_jinja2_starter`` scaffold generated a ``tests.py`` module +with one unit test in it. To run it, let's install the handy ``nose`` +test runner by editing ``setup.py``. While we're at it, we'll throw in +the ``coverage`` tool which yells at us for code that isn't tested: + +.. code-block:: python + + setup(name='hello_world', + # Some lines removed... + extras_require={ + 'testing': ['nose', 'coverage'], + } + ) + +We changed ``setup.py`` which means we need to re-run +``python ./setup.py develop``. We can now run all our tests: + +.. code-block:: bash + + $ cd hello_world + $ nosetests . + . + Name Stmts Miss Cover Missing + --------------------------------------------------- + hello_world 12 8 33% 11-23 + hello_world.models 5 1 80% 8 + hello_world.tests 14 0 100% + hello_world.views 4 0 100% + --------------------------------------------------- + TOTAL 35 9 74% + ---------------------------------------------------------------------- + Ran 1 test in 0.931s + + OK + +Our unit test passed. What did our test look like? + +.. literalinclude:: quick_tour/package/hello_world/tests.py + +Pyramid supplies helpers for test writing, which we use in the +test setup and teardown. Our one test imports the view, +makes a dummy request, and sees if the view returns what we expected. + +Logging +======= + +It's important to know what is going on inside our web application. +In development we might need to collect some output. In production, +we might need to detect situations when other people use the site. We +need *logging*. + +Fortunately Pyramid uses the normal Python approach to logging. The +scaffold generated, in your ``development.ini``, a number of lines that +configure the logging for you to some reasonable defaults. You then see +messages sent by Pyramid (for example, when a new request comes in.) + +Maybe you would like to log messages in your code? In your Python +module, import and setup the logging: + +.. literalinclude:: quick_tour/package/hello_world/views.py + :start-after: Start Logging 1 + :end-before: End Logging 1 + +You can now, in your code, log messages: + +.. literalinclude:: quick_tour/package/hello_world/views.py + :start-after: Start Logging 2 + :end-before: End Logging 2 + +This will log ``Some Message`` at a ``debug`` log level, +to the application-configured logger in your ``development.ini``. What +controls that? These sections in the configuration file: + +.. literalinclude:: quick_tour/package/development.ini + :language: ini + :start-after: Start Sphinx Include + :end-before: End Sphinx Include + +Our application, a package named ``hello_world``, is setup as a logger +and configured to log messages at a ``DEBUG`` or higher level. When you +visit ``http://localhost:6543`` your console will now show:: + + 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message + +Sessions +======== + +When people use your web application, they frequently perform a task +that requires semi-permanent data to be saved. For example, a shopping +cart. This is called a :term:`session`. + +Pyramid has basic built-in support for sessions, with add-ons such as +*Beaker* (or your own custom sessioning engine) that provide richer +session support. Let's take a look at the +:doc:`built-in sessioning support <../narr/sessions>`. In our +``__init__.py`` we first import the kind of sessioning we want: + +.. literalinclude:: quick_tour/package/hello_world/__init__.py + :start-after: Start Sphinx Include 1 + :end-before: End Sphinx Include 1 + +.. warning:: + + As noted in the session docs, this example implementation is + not intended for use in settings with security implications. + +Now make a "factory" and pass it to the :term:`configurator`'s +``session_factory`` argument: + +.. literalinclude:: quick_tour/package/hello_world/__init__.py + :start-after: Start Sphinx Include 2 + :end-before: End Sphinx Include 2 + +Pyramid's :term:`request` object now has a ``session`` attribute +that we can use in our view code: + +.. literalinclude:: quick_tour/package/hello_world/views.py + :start-after: Start Sphinx Include 1 + :end-before: End Sphinx Include 1 + +With this, each reload will increase the counter displayed in our +Jinja2 template: + +.. literalinclude:: quick_tour/package/hello_world/templates/mytemplate.jinja2 + :language: jinja + :start-after: Start Sphinx Include 1 + :end-before: End Sphinx Include 1 + + +Databases +========= + +Web applications mean data. Data means databases. Frequently SQL +databases. SQL Databases frequently mean an "ORM" +(object-relational mapper.) In Python, ORM usually leads to the +mega-quality *SQLAlchemy*, a Python package that greatly eases working +with databases. + +Pyramid and SQLAlchemy are great friends. That friendship includes a +scaffold! + +.. code-block:: bash + + $ pcreate --scaffold alchemy sqla_demo + $ cd sqla_demo + $ python setup.py develop + +We now have a working sample SQLAlchemy application with all +dependencies installed. The sample project provides a console script to +initialize a SQLite database with tables. Let's run it and then start +the application: + +.. code-block:: bash + + $ initialize_sqla_demo_db development.ini + $ pserve development.ini + +The ORM eases the mapping of database structures into a programming +language. SQLAlchemy uses "models" for this mapping. The scaffold +generated a sample model: + +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models.py + :start-after: Start Sphinx Include + :end-before: End Sphinx Include + +View code, which mediates the logic between web requests and the rest +of the system, can then easily get at the data thanks to SQLAlchemy: + +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/views.py + :start-after: Start Sphinx Include + :end-before: End Sphinx Include + +Forms +===== + +Developers have lots of opinions about web forms, and thus there are many +form libraries for Python. Pyramid doesn't directly bundle a form +library, but *Deform* is a popular choice for forms, +along with its related *Colander* schema system. + +As an example, imagine we want a form that edits a wiki page. The form +should have two fields on it, one of them a required title and the +other a rich text editor for the body. With Deform we can express this +as a Colander schema: + +.. code-block:: python + + class WikiPage(colander.MappingSchema): + title = colander.SchemaNode(colander.String()) + body = colander.SchemaNode( + colander.String(), + widget=deform.widget.RichTextWidget() + ) + +With this in place, we can render the HTML for a form, +perhaps with form data from an existing page: + +.. code-block:: python + + form = self.wiki_form.render() + +We'd like to handle form submission, validation, and saving: + +.. code-block:: python + + # Get the form data that was posted + controls = self.request.POST.items() + try: + # Validate and either raise a validation error + # or return deserialized data from widgets + appstruct = wiki_form.validate(controls) + except deform.ValidationFailure as e: + # Bail out and render form with errors + return dict(title=title, page=page, form=e.render()) + + # Change the content and redirect to the view + page['title'] = appstruct['title'] + page['body'] = appstruct['body'] + +Deform and Colander provide a very flexible combination for forms, +widgets, schemas, and validation. Recent versions of Deform also +include a +`retail mode `_ +for gaining Deform +features on custom forms. + +Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform +widgets using attractive CSS from Bootstrap and more powerful widgets +from Chosen. + + +Conclusion +========== + +This *Quick Tour* covered a little about a lot. We introduced a long list +of concepts in Pyramid, many of which are expanded on more fully in the +Pyramid developer docs. \ No newline at end of file -- cgit v1.2.3 From b853e5c9c0b19e6c6349d65dca52d6c3fe249358 Mon Sep 17 00:00:00 2001 From: kusut Date: Mon, 12 Aug 2013 21:09:36 +0700 Subject: use easy_install instead of pip in quick_tour guide. - consistent with another docs (pyramid/substanced uses easy_install). - prevent pip/easy_install namespace package fiasco since the docs uses setup.py develop instead of pip install -e --- docs/quick_tour.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index cc4afe67d..fcf799c6d 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -26,11 +26,9 @@ area in place. For Python 3.3: $ pyvenv-3.3 env33 $ source env33/bin/activate $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python - $ easy_install-3.3 pip 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. +packaging tools installed. Pyramid Installation ==================== @@ -40,7 +38,7 @@ installed is easy: .. code-block:: bash - $ pip install pyramid + $ easy_install pyramid Our virtual environment now has the Pyramid software available to its Python. @@ -245,7 +243,7 @@ our Pyramid applications: .. code-block:: bash - $ pip install pyramid_jinja2 + $ easy_install pyramid_jinja2 With the package installed, we can include the template bindings into our configuration: -- cgit v1.2.3 From 5b47ba8ce8c8bdb149b92a2b35a5e7607ca6fc00 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Mon, 12 Aug 2013 14:20:04 -0400 Subject: About to give Intersphinx a shot. --- docs/quick_tour.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 50 insertions(+), 4 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index cc4afe67d..13d936a6b 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -2,6 +2,10 @@ Quick Tour of Pyramid ===================== +TODO: + +- Convert all the See Also below into Intersphinx links + Pyramid lets you start small and finish big. This *Quick Tour* guide walks you through many of Pyramid's key features. Let's put the emphasis on *start* by doing a quick tour through Pyramid, with @@ -32,6 +36,10 @@ 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. +See Also: http://docs.python.org/dev/library/venv.html, +https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions, +http://www.pip-installer.org/en/latest/, narr/install.html#before-you-install + Pyramid Installation ==================== @@ -45,6 +53,8 @@ installed is easy: Our virtual environment now has the Pyramid software available to its Python. +See Also: narr/install.html#installing-pyramid-on-a-unix-system, + Hello World =========== @@ -82,6 +92,9 @@ in Pyramid development. Building an application from loosely-coupled parts via :doc:`../narr/configuration` is a central idea in Pyramid, one that we will revisit regurlarly in this *Quick Tour*. +See Also: narr/firstapp, +http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/single_file_tasks/single_file_tasks.html + Handling Web Requests and Responses =================================== @@ -110,6 +123,10 @@ the name is included in the body of the response:: Finally, we set the response's content type and return the Response. +See Also: http://localhost:8080/projects/pyramid/docs +.gettingstarted/docs/_build/narr/webob.html#webob-chapter, + + Views ===== @@ -158,6 +175,8 @@ configuration`, in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually, it is simply a matter of taste. +See Also: narr/views.html, narr/viewconfig, +narr/viewconfig.html#debugging-view-configuration Routing ======= @@ -200,10 +219,8 @@ view: "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view. -As you might imagine, Pyramid provides -:doc:`many more features in routing <../narr/urldispatch>` -(route factories, custom predicates, security statements, -etc.) We will see more features later in *Geting Started*. +See Also: narr/urldispatch, narr/urldispatch +.html#debugging-route-matching, narr/router Templating ========== @@ -234,6 +251,9 @@ Since our view returned ``dict(name=request.matchdict['name'])``, we can use ``name`` as a variable in our template via ``${name}``. +See Also: narr/templates, narr/templates.html#debugging-templates, +templates.html#templating-with-mako-templates, + Templating With ``jinja2`` ========================== @@ -276,6 +296,7 @@ renderer. At the time of this writing, Jinja2 had not released a version compatible with Python 3.3. +See Also: Jinja2, pyramid_jinja2, Static Assets ============= @@ -320,6 +341,9 @@ By using ``request.static_url`` to generate the full URL to the static assets, you both ensure you stay in sync with the configuration and gain refactoring flexibility later. +See Also: narr/assets, narr/environment.html#preventing-http-caching, +narr/viewconfig.html#influencing-http-caching, + Returning JSON ============== @@ -335,6 +359,9 @@ This wires up a view that returns some data through the JSON :term:`renderer`, which calls Python's JSON support to serialize the data into JSON and set the appropriate HTTP headers. +See Also: narr/renderers.html#json-renderer, +narr/renderers.html#adding-and-overriding-renderers + View Classes ============ @@ -376,6 +403,8 @@ Only one route needed, stated in one place atop the view class. Also, the assignment of the ``name`` is done in the ``__init__``. Our templates can then use ``{{ view.name }}``. +See Also: narr/views.html#defining-a-view-callable-as-a-class + Quick Project Startup with Scaffolds ==================================== @@ -422,6 +451,8 @@ configuration. This includes a new way of running your application: Let's look at ``pserve`` and configuration in more depth. +See Also: narr/project.html#creating-a-pyramid-project, narr/scaffolding.html + Application Running with ``pserve`` =================================== @@ -493,6 +524,9 @@ Additionally, the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well traceback information. +See Also: narr/environment.html#environment-variables-and-ini-file +-settings, narr/paste.html + Easier Development with ``debugtoolbar`` ======================================== @@ -542,6 +576,8 @@ you want to disable this toolbar, no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. +See Also: pyramid_debugtoolbar + Unit Tests and ``nose`` ======================= @@ -592,6 +628,9 @@ Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. +See Also: nose, narr/testing +.html#unit-integration-and-functional-testing, + Logging ======= @@ -633,6 +672,8 @@ visit ``http://localhost:6543`` your console will now show:: 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message +See Also: narr/sessions.html, narr/sessions.html#flash-messages, + Sessions ======== @@ -677,6 +718,7 @@ Jinja2 template: :start-after: Start Sphinx Include 1 :end-before: End Sphinx Include 1 +See Also: narr/sessions.html#sessions, api/session.html Databases ========= @@ -721,6 +763,9 @@ of the system, can then easily get at the data thanks to SQLAlchemy: :start-after: Start Sphinx Include :end-before: End Sphinx Include +See Also: sqlalchemy, narr/commandline + .html#making-your-script-into-a-console-script, pyramid_tm, + Forms ===== @@ -780,6 +825,7 @@ Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets using attractive CSS from Bootstrap and more powerful widgets from Chosen. +See Also: Deform, Colander Conclusion ========== -- cgit v1.2.3 From 49d634bd813e63c3db5e56d29376126c2646182a Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Mon, 12 Aug 2013 19:29:23 -0400 Subject: All wrapped up, pre-merge. --- docs/quick_tour.rst | 100 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 57 insertions(+), 43 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 13d936a6b..28fefb49c 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -1,11 +1,9 @@ +.. _quick_tour: + ===================== Quick Tour of Pyramid ===================== -TODO: - -- Convert all the See Also below into Intersphinx links - Pyramid lets you start small and finish big. This *Quick Tour* guide walks you through many of Pyramid's key features. Let's put the emphasis on *start* by doing a quick tour through Pyramid, with @@ -36,9 +34,12 @@ 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. -See Also: http://docs.python.org/dev/library/venv.html, -https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions, -http://www.pip-installer.org/en/latest/, narr/install.html#before-you-install +.. seealso:: See Also: Python 3's :mod:`venv module `, + the ``setuptools`` `installation + instructions `_, + documentation for `pip `_, + and + Pyramid's :ref:`Before You Install ` Pyramid Installation ==================== @@ -53,7 +54,7 @@ installed is easy: Our virtual environment now has the Pyramid software available to its Python. -See Also: narr/install.html#installing-pyramid-on-a-unix-system, +.. seealso:: See Also: :ref:`installing_unix` Hello World =========== @@ -92,8 +93,8 @@ in Pyramid development. Building an application from loosely-coupled parts via :doc:`../narr/configuration` is a central idea in Pyramid, one that we will revisit regurlarly in this *Quick Tour*. -See Also: narr/firstapp, -http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/single_file_tasks/single_file_tasks.html +.. seealso:: See Also: :ref:`firstapp_chapter` and + :ref:`Single File Tasks tutorial ` Handling Web Requests and Responses =================================== @@ -123,9 +124,7 @@ the name is included in the body of the response:: Finally, we set the response's content type and return the Response. -See Also: http://localhost:8080/projects/pyramid/docs -.gettingstarted/docs/_build/narr/webob.html#webob-chapter, - +.. seealso:: See Also: :ref:`webob_chapter` Views ===== @@ -175,8 +174,9 @@ configuration`, in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually, it is simply a matter of taste. -See Also: narr/views.html, narr/viewconfig, -narr/viewconfig.html#debugging-view-configuration +.. seealso:: See Also: :doc:`../narr/views`, + :doc:`../narr/viewconfig`, and + :ref:`debugging_view_configuration` Routing ======= @@ -219,8 +219,9 @@ view: "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view. -See Also: narr/urldispatch, narr/urldispatch -.html#debugging-route-matching, narr/router +.. seealso:: See Also: :doc:`../narr/urldispatch`, + :ref:`debug_routematch_section`, and + :doc:`../narr/router` Templating ========== @@ -251,8 +252,9 @@ Since our view returned ``dict(name=request.matchdict['name'])``, we can use ``name`` as a variable in our template via ``${name}``. -See Also: narr/templates, narr/templates.html#debugging-templates, -templates.html#templating-with-mako-templates, +.. seealso:: See Also: :doc:`../narr/templates`, + :ref:`debugging_templates`, and + :ref:`mako_templates` Templating With ``jinja2`` ========================== @@ -291,12 +293,9 @@ filename extensions. In this case, changing the extension from ``.pt`` to ``.jinja2`` passed the view response through the ``pyramid_jinja2`` renderer. -.. note:: - - At the time of this writing, Jinja2 had not released a version - compatible with Python 3.3. - -See Also: Jinja2, pyramid_jinja2, +.. seealso:: See Also: `Jinja2 homepage `_, + and + :ref:`pyramid_jinja2 Overview ` Static Assets ============= @@ -341,8 +340,9 @@ By using ``request.static_url`` to generate the full URL to the static assets, you both ensure you stay in sync with the configuration and gain refactoring flexibility later. -See Also: narr/assets, narr/environment.html#preventing-http-caching, -narr/viewconfig.html#influencing-http-caching, +.. seealso:: See Also: :doc:`../narr/assets`, + :ref:`preventing_http_caching`, and + :ref:`influencing_http_caching` Returning JSON ============== @@ -359,8 +359,9 @@ This wires up a view that returns some data through the JSON :term:`renderer`, which calls Python's JSON support to serialize the data into JSON and set the appropriate HTTP headers. -See Also: narr/renderers.html#json-renderer, -narr/renderers.html#adding-and-overriding-renderers +.. seealso:: See Also: :ref:`views_which_use_a_renderer`, + :ref:`json_renderer`, and + :ref:`adding_and_overriding_renderers` View Classes ============ @@ -403,7 +404,7 @@ Only one route needed, stated in one place atop the view class. Also, the assignment of the ``name`` is done in the ``__init__``. Our templates can then use ``{{ view.name }}``. -See Also: narr/views.html#defining-a-view-callable-as-a-class +.. seealso:: See Also: :ref:`class_as_view` Quick Project Startup with Scaffolds ==================================== @@ -451,7 +452,8 @@ configuration. This includes a new way of running your application: Let's look at ``pserve`` and configuration in more depth. -See Also: narr/project.html#creating-a-pyramid-project, narr/scaffolding.html +.. seealso:: See Also: :ref:`project_narr` and + :doc:`../narr/scaffolding` Application Running with ``pserve`` =================================== @@ -479,6 +481,8 @@ Most of the work, though, comes from your project's wiring, as expressed in the configuration file you supply to ``pserve``. Let's take a look at this configuration file. +.. seealso:: See Also: :ref:`what_is_this_pserve_thing` + Configuration with ``.ini`` Files ================================= @@ -524,8 +528,9 @@ Additionally, the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well traceback information. -See Also: narr/environment.html#environment-variables-and-ini-file --settings, narr/paste.html +.. seealso:: See Also: :ref:`environment_chapter` and + :doc:`../narr/paste` + Easier Development with ``debugtoolbar`` ======================================== @@ -576,7 +581,8 @@ you want to disable this toolbar, no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. -See Also: pyramid_debugtoolbar +.. seealso:: See Also: `pyramid_debugtoolbar + `_ Unit Tests and ``nose`` ======================= @@ -604,8 +610,7 @@ We changed ``setup.py`` which means we need to re-run .. code-block:: bash - $ cd hello_world - $ nosetests . + $ nosetests hello_world/tests.py . Name Stmts Miss Cover Missing --------------------------------------------------- @@ -628,8 +633,7 @@ Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. -See Also: nose, narr/testing -.html#unit-integration-and-functional-testing, +.. seealso:: See Also: :ref:`testing_chapter` Logging ======= @@ -672,7 +676,7 @@ visit ``http://localhost:6543`` your console will now show:: 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message -See Also: narr/sessions.html, narr/sessions.html#flash-messages, +.. seealso:: See Also: :ref:`logging_chapter` Sessions ======== @@ -718,7 +722,11 @@ Jinja2 template: :start-after: Start Sphinx Include 1 :end-before: End Sphinx Include 1 -See Also: narr/sessions.html#sessions, api/session.html +.. seealso:: See Also: + :ref:`sessions_chapter`, :ref:`flash_messages`, + :ref:`session_module`, and + `Beaker sessioning middleware + `_ Databases ========= @@ -763,8 +771,11 @@ of the system, can then easily get at the data thanks to SQLAlchemy: :start-after: Start Sphinx Include :end-before: End Sphinx Include -See Also: sqlalchemy, narr/commandline - .html#making-your-script-into-a-console-script, pyramid_tm, +.. seealso:: See Also: `SQLAlchemy `_, + :ref:`making_a_console_script`, + :ref:`bfg_sql_wiki_tutorial`, and + `Application Transactions With pyramid_tm + `_ Forms ===== @@ -825,7 +836,10 @@ Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets using attractive CSS from Bootstrap and more powerful widgets from Chosen. -See Also: Deform, Colander +.. seealso:: See Also: + `Deform `_, + `Colander `_, and + `deform_bootstrap `_ Conclusion ========== -- cgit v1.2.3 From c90471defdd552b4a8c2073914cfd49e7d9f2ca0 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Mon, 12 Aug 2013 19:59:33 -0400 Subject: Forgot to add the subdir --- docs/quick_tour.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 28fefb49c..4229c1f39 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -581,8 +581,7 @@ you want to disable this toolbar, no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. -.. seealso:: See Also: `pyramid_debugtoolbar - `_ +.. seealso:: See Also: :ref:`pyramid_debugtoolbar ` Unit Tests and ``nose`` ======================= -- cgit v1.2.3 From bf84d90b4dccb9fc52c8fe385e52f7a63e9a5535 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Tue, 13 Aug 2013 07:36:48 -0400 Subject: Add Intersphinx for Beaker, clean up some broken references, change from pip to virtualenv (and give an explanation), explain virtualenv on Python 2.7. --- docs/quick_tour.rst | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index cb07826cf..ba2a517ef 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -29,15 +29,25 @@ area in place. For Python 3.3: $ source env33/bin/activate $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python -We make a :term:`virtualenv` then activate it. We then get Python -packaging tools installed. +We make a :term:`virtualenv` then activate it. Next we download +Python's packaging support and install it, giving us the +``easy_install`` command-line script for adding new packages. Python +2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make +their virtual environment. + +.. note:: + + Why ``easy_install`` and not ``pip``? Pyramid encourages use of + namespace packages which, until recently, ``pip`` didn't permit. + Also, Pyramid has some optional C extensions for performance. With + ``easy_install``, Windows users can get these extensions without + needing a C compiler. .. seealso:: See Also: Python 3's :mod:`venv module `, the ``setuptools`` `installation instructions `_, - documentation for `pip `_, - and - Pyramid's :ref:`Before You Install ` + `easy_install help `_, + and Pyramid's :ref:`Before You Install `. Pyramid Installation ==================== @@ -722,8 +732,7 @@ Jinja2 template: .. seealso:: See Also: :ref:`sessions_chapter`, :ref:`flash_messages`, :ref:`session_module`, and - `Beaker sessioning middleware - `_ + :ref:`Beaker sessioning middleware ` Databases ========= @@ -771,8 +780,7 @@ of the system, can then easily get at the data thanks to SQLAlchemy: .. seealso:: See Also: `SQLAlchemy `_, :ref:`making_a_console_script`, :ref:`bfg_sql_wiki_tutorial`, and - `Application Transactions With pyramid_tm - `_ + :ref:`Application Transactions With pyramid_tm ` Forms ===== @@ -823,10 +831,7 @@ We'd like to handle form submission, validation, and saving: Deform and Colander provide a very flexible combination for forms, widgets, schemas, and validation. Recent versions of Deform also -include a -`retail mode `_ -for gaining Deform +include a :ref:`retail mode ` for gaining Deform features on custom forms. Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform @@ -834,8 +839,8 @@ widgets using attractive CSS from Bootstrap and more powerful widgets from Chosen. .. seealso:: See Also: - `Deform `_, - `Colander `_, and + :ref:`Deform `, + :ref:`Colander `, and `deform_bootstrap `_ Conclusion -- cgit v1.2.3 From 2d81001b80195e31a45c4d088285c5ed93712989 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 14 Aug 2013 16:07:17 -0400 Subject: Changes recommended by Lisa Ballard at PyLadies via Steve Piercy, thanks Lisa! --- docs/quick_tour.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index ba2a517ef..e191de198 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -29,8 +29,16 @@ area in place. For Python 3.3: $ source env33/bin/activate $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python -We make a :term:`virtualenv` then activate it. Next we download -Python's packaging support and install it, giving us the +If ``wget`` complains with a certificate error, run it with: + +.. code-block:: bash + + $ wget --no-check-certificate + +In these steps above we first made a :term:`virtualenv` and then +"activated" it, which adjusted our path to look first in +``env33/bin`` for commands (such as ``python``.) We next downloaded +Python's packaging support and installed it, giving us the ``easy_install`` command-line script for adding new packages. Python 2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make their virtual environment. @@ -202,7 +210,8 @@ Above we saw the basics of routing URLs to views in Pyramid: .. note:: - Why do this twice? Other systems don't make us repeat this! As + Why do this twice? Other Python web frameworks let you create a + route and associate it with a view in one step. As illustrated in :ref:`routes_need_ordering`, multiple routes might match the same URL pattern. Rather than provide ways to help guess, Pyramid lets you be explicit in ordering. Pyramid also gives -- cgit v1.2.3 From b3cfa2a91925b008fbfedf7f87371b56cd086213 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 15 Aug 2013 23:17:21 +0200 Subject: fix misplaced symbol --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index e191de198..f75533220 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -37,7 +37,7 @@ If ``wget`` complains with a certificate error, run it with: In these steps above we first made a :term:`virtualenv` and then "activated" it, which adjusted our path to look first in -``env33/bin`` for commands (such as ``python``.) We next downloaded +``env33/bin`` for commands (such as ``python``). We next downloaded Python's packaging support and installed it, giving us the ``easy_install`` command-line script for adding new packages. Python 2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make -- cgit v1.2.3 From 540fcdd99f11d93f6d821152217537fc21ecd4dc Mon Sep 17 00:00:00 2001 From: Wes Turner Date: Mon, 2 Sep 2013 15:15:34 -0500 Subject: DOC: Update quick_tour.rst: Typo: with -> which --- docs/quick_tour.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index f75533220..e55730a0d 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -476,7 +476,7 @@ Application Running with ``pserve`` =================================== Prior to scaffolds, our project mixed a number of operations details -into our code. Why should my main code care with HTTP server I want and +into our code. Why should my main code care which HTTP server I want and what port number to run on? ``pserve`` is Pyramid's application runner, separating operational @@ -857,4 +857,4 @@ Conclusion This *Quick Tour* covered a little about a lot. We introduced a long list of concepts in Pyramid, many of which are expanded on more fully in the -Pyramid developer docs. \ No newline at end of file +Pyramid developer docs. -- cgit v1.2.3 From 70784a80c07cc831ab20c2e22e82b14afe834feb Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 6 Sep 2013 00:38:30 -0500 Subject: fix some more broken references --- docs/quick_tour.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index e55730a0d..9a354b009 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -250,8 +250,9 @@ Python, but instead, will use a templating language. Pyramid doesn't mandate a particular database system, form library, etc. It encourages replaceability. This applies equally to templating, which is fortunate: developers have strong views about template -languages. That said, Pyramid bundles Chameleon and Mako, -so in this step, let's use Chameleon as an example: +languages. That said, the Pylons Project officially supports bindings for +Chameleon, Jinja2 and Mako, so in this step, let's use Chameleon as an +example: .. literalinclude:: quick_tour/templating/views.py :start-after: Start View 1 @@ -271,7 +272,7 @@ we can use ``name`` as a variable in our template via .. seealso:: See Also: :doc:`../narr/templates`, :ref:`debugging_templates`, and - :ref:`mako_templates` + :ref:`available_template_system_bindings` Templating With ``jinja2`` ========================== -- cgit v1.2.3 From bd5a7ff20d9bdeaf36ef4154cbb0322696a46e2b Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 6 Sep 2013 00:48:24 -0500 Subject: apostrophe --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 9a354b009..4b23f7858 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -18,7 +18,7 @@ snippets of code to illustrate major concepts. Python Setup ============ -First things first: we need our Python environment in ship-shape. +First thing's first: we need our Python environment in ship-shape. Pyramid encourages standard Python development practices (virtual environments, packaging tools, logging, etc.) so let's get our working area in place. For Python 3.3: -- cgit v1.2.3 From b0b28ede912c817a62a84b97c332e39eda02d166 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 16 Sep 2013 02:14:53 +0200 Subject: s/env/venv just for sake of consistency --- docs/quick_tour.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 4b23f7858..2303e9a5c 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -25,9 +25,9 @@ area in place. For Python 3.3: .. code-block:: bash - $ pyvenv-3.3 env33 - $ source env33/bin/activate - $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python + $ pyvenv-3.3 venv + $ source venv/bin/activate + (venv)$ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python If ``wget`` complains with a certificate error, run it with: @@ -37,7 +37,7 @@ If ``wget`` complains with a certificate error, run it with: In these steps above we first made a :term:`virtualenv` and then "activated" it, which adjusted our path to look first in -``env33/bin`` for commands (such as ``python``). We next downloaded +``venv/bin`` for commands (such as ``python``). We next downloaded Python's packaging support and installed it, giving us the ``easy_install`` command-line script for adding new packages. Python 2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make -- cgit v1.2.3 From 9b7f4d11b6beb3c60a2b11a280bc9c18ab01ad34 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 24 Sep 2013 04:35:57 -0700 Subject: Update Requirements section --- docs/quick_tour.rst | 255 +++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 212 insertions(+), 43 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 2303e9a5c..ca2b0f826 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -4,73 +4,242 @@ Quick Tour of Pyramid ===================== -Pyramid lets you start small and finish big. This *Quick Tour* guide -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. +Pyramid lets you start small and finish big. This *Quick Tour* of Pyramid is +for those who want to evaluate Pyramid and are not yet familiar with it. + + +Conventions +=========== +This guide uses conventions to keep the introduction focused and concise. +Details, references, and deeper discussions are mentioned in "See Also" +notes. + +.. seealso:: This is an example "See Also" note. + +Pyramid encourages standard Python development practices with packaging tools, +virtual environments, logging, and so on. There are many variations, +implementations, and opinions across the Python community, each of which may +have its proper usage. For the sake of consistency, ease of documentation +maintenance, and to minimize confusion, the Pyramid documentation has adopted +specific conventions: + +* Pyramid fully supports Python 3.2 or greater as well as Python 2.6 and 2.7. + This guide uses Python 3. +* We use ``pyvenv`` for isolating Python environments. +* We use ``setuptools`` for package management. +* We organize our file system where our home directory contains all of our + projects, which contains our workspaces, which contain both Python virtual + environments and projects. +* Commands in this guide use UNIX syntax and paths. Windows users should + adjust commands accordingly. .. note:: - We use Python 3 in 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. + Pyramid was one of the first web frameworks to fully support Python 3 in + October 2011. -Python Setup +Requirements ============ -First thing's first: we need our Python environment in ship-shape. -Pyramid encourages standard Python development practices (virtual -environments, packaging tools, logging, etc.) so let's get our working -area in place. For Python 3.3: +* :ref:`install-python-3.2-or-greater` +* :ref:`create-a-project-directory-structure` +* :ref:`set-an-environment-variable` +* :ref:`create-a-virtual-environment` +* :ref:`install-setuptools-(python-packaging-tools)` +* :ref:`install-pyramid` + +.. warning:: The current state of isolated Python environments using + ``pyvenv`` on Windows is suboptimal in comparison to Mac and Linux. See + http://stackoverflow.com/q/15981111/95735 for a discussion of the issue. + When it is resolved, or if any Windows user would like to step forward, + we would gratefully accept a pull request to update our documentation. + + Until then, we recommend that Windows users follow the procedure + :ref:`Installing Pyramid on a Windows System ` + +.. _install-python-3.2-or-greater: + +Install Python 3.2 or greater +----------------------------- + +Download the latest standard Python 3 release (not development release) from +`python.org `_. On that page, you +must click the latest version, then scroll down to the "Downloads" section +for your operating system. + +Windows and Mac OS X users can download and run an installer. + +Windows users should also install the `Python for Windows extensions +`_. Carefully read the +``README.txt`` file at the end of the list of builds, and follow its +directions. Make sure you get the proper 32- or 64-bit build and Python +version. + +Linux users can either use their package manager to install Python 3 or may +`build Python 3 from source +`_. + + +.. _create-a-project-directory-structure: + +Create a project directory structure +------------------------------------ + +From your user home directory, create the following initial directory structure +as indicated in the figure below. + +.. figure:: _static/directory_structure_initial.png + :alt: initial directory structure + + An initial directory structure. + +The commands to do so are as follows: + +.. code-block:: bash + + # Mac and Linux + $ cd ~ + $ mkdir projects + $ cd projects + $ mkdir pyramid + + # Windows + c:\> cd \ + c:\> mkdir projects + c:\> cd projects + c:\> mkdir pyramid + +In the above figure, your user home directory is represented by ``~``. In +your home directory, all of your projects are in the ``projects`` directory. +This is a general convention not specific to Pyramid that many developers use. +Windows users will do well to use ``c:\`` as the location for ``projects`` in +order to avoid spaces in any of the path names. + +Next within ``projects`` is your workspace directory, here named ``pyramid``. +A workspace is a common term used by integrated development environments (IDE) +like PyCharm and PyDev that stores isolated Python environments (virtualenvs) +and specific project files and repositories. + + +.. _set-an-environment-variable: + +Set an Environment Variable +--------------------------- + +We set an environment variable to save typing later. .. code-block:: bash + + # Mac and Linux + $ export VENV=~/projects/pyramid/env33/bin/ + + # Windows + # TODO: This command does not work + c:\> set VENV=c:\projects\pyramid\env33 - $ pyvenv-3.3 venv - $ source venv/bin/activate - (venv)$ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | python -If ``wget`` complains with a certificate error, run it with: +.. _create-a-virtual-environment: + +Create a Virtual Environment +---------------------------- +``pyvenv`` is a tool to create isolated Python environments. Create one. .. code-block:: bash - $ wget --no-check-certificate + # Mac and Linux + $ pyvenv $VENV + + # Windows + # TODO: This command does work, but we should improve it with %VENV% + c:\> .\Python33\python -m venv c:\projects\pyramid\env33 -In these steps above we first made a :term:`virtualenv` and then -"activated" it, which adjusted our path to look first in -``venv/bin`` for commands (such as ``python``). We next downloaded -Python's packaging support and installed it, giving us the -``easy_install`` command-line script for adding new packages. Python -2.7 users will need to use ``virtualenv`` instead of ``pyvenv`` to make -their virtual environment. +.. note:: ``pyvenv`` is a tool to create isolated Python environments. The + venv module provides support for creating lightweight "virtual + environments" with their own site directories, optionally isolated from + system site directories. Each virtual environment has its own Python binary + (allowing creation of environments with various Python versions) and can + have its own independent set of installed Python packages in its site + directories. -.. note:: +.. seealso:: See also Python 3's :mod:`venv module ` and Python + 2's `virtualenv `_ package. - Why ``easy_install`` and not ``pip``? Pyramid encourages use of - namespace packages which, until recently, ``pip`` didn't permit. - Also, Pyramid has some optional C extensions for performance. With - ``easy_install``, Windows users can get these extensions without - needing a C compiler. -.. seealso:: See Also: Python 3's :mod:`venv module `, - the ``setuptools`` `installation - instructions `_, - `easy_install help `_, - and Pyramid's :ref:`Before You Install `. +.. _install-setuptools-(python-packaging-tools): -Pyramid Installation -==================== +Install ``setuptools`` (Python packaging tools) +----------------------------------------------- -We now have a standard starting point for Python. Getting Pyramid -installed is easy: +The following command will download a script to install ``setuptools``, then +pipe it to your environment's version of Python. .. code-block:: bash - $ easy_install pyramid + # Mac and Linux + $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/python + + # Windows + # TODO Something goes here + +If ``wget`` complains with a certificate error, then run this command instead: + +.. code-block:: bash + + # Mac and Linux + $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/python + + # Windows + # TODO Something goes here + + +.. _install-pyramid: + +Install Pyramid +--------------- + +.. code-block:: bash + + # Mac and Linux + $ easy_install pyramid + + # Windows + # TODO Something goes here + +Our Python environment now has the Pyramid software available. Your directory structure should now look like the following image. + +.. figure:: _static/directory_structure_pyramid.png + :alt: Pyramid directory structure + + A Pyramid directory structure. + + +.. note:: + + Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace + packages which, until recently, ``pip`` didn't permit. Also, Pyramid has + some optional C extensions for performance. With ``easy_install``, Windows + users can get these extensions without needing a C compiler. + +.. seealso:: See Also: :ref:`installing_unix`. For instructions to set up your + Python environment for development using Windows or Python 2, see Pyramid's + :ref:`Before You Install `. + + See also Python 3's :mod:`venv module `, the `setuptools` `installation instructions + `_, + and `easy_install help `_. + +.. note:: A generic representation of project directory structure is shown in + the following figure. We could create multiple isolated Python + environments for multiple versions of Python. We could also add more + projects within our workspace directory, which is a common practice in the + Pyramid tutorials. + +.. figure:: _static/directory_structure_generic.png + :alt: generic directory structure -Our virtual environment now has the Pyramid software available to its -Python. + A generic directory structure. -.. seealso:: See Also: :ref:`installing_unix` Hello World =========== -- cgit v1.2.3 From 6a6d539409630343b7cf79f277eb0b3c402ee1ba Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 24 Sep 2013 05:03:37 -0700 Subject: Change python version to 3.3 --- docs/quick_tour.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index ca2b0f826..e6bca0760 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -41,7 +41,7 @@ specific conventions: Requirements ============ -* :ref:`install-python-3.2-or-greater` +* :ref:`install-python-3.3-or-greater` * :ref:`create-a-project-directory-structure` * :ref:`set-an-environment-variable` * :ref:`create-a-virtual-environment` @@ -57,9 +57,9 @@ Requirements Until then, we recommend that Windows users follow the procedure :ref:`Installing Pyramid on a Windows System ` -.. _install-python-3.2-or-greater: +.. _install-python-3.3-or-greater: -Install Python 3.2 or greater +Install Python 3.3 or greater ----------------------------- Download the latest standard Python 3 release (not development release) from -- cgit v1.2.3 From 7801c187762357f6e36ce4cfe555038113af08fb Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 24 Sep 2013 05:13:02 -0700 Subject: add mention of PEP 453 --- docs/quick_tour.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index e6bca0760..c6cda54a6 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -50,9 +50,11 @@ Requirements .. warning:: The current state of isolated Python environments using ``pyvenv`` on Windows is suboptimal in comparison to Mac and Linux. See - http://stackoverflow.com/q/15981111/95735 for a discussion of the issue. - When it is resolved, or if any Windows user would like to step forward, - we would gratefully accept a pull request to update our documentation. + http://stackoverflow.com/q/15981111/95735 for a discussion of the issue + and `PEP 453 `_ for a proposed + resolution. When it is resolved, or if any Windows user would like to step + forward, we would gratefully accept a pull request to update our + documentation. Until then, we recommend that Windows users follow the procedure :ref:`Installing Pyramid on a Windows System ` -- cgit v1.2.3 From b731b5fca253d9d95b3307490aa585e194676c01 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Thu, 26 Sep 2013 17:41:44 -0400 Subject: Quick Tour: shorten the setup part and point to Quick Tutorial Requirements for more explanation. Cross link each Quick Tour section with its Quick Tutorial match. --- docs/quick_tour.rst | 365 ++++++++++++++++------------------------------------ 1 file changed, 112 insertions(+), 253 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index c6cda54a6..434dbdad5 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -5,216 +5,42 @@ Quick Tour of Pyramid ===================== Pyramid lets you start small and finish big. This *Quick Tour* of Pyramid is -for those who want to evaluate Pyramid and are not yet familiar with it. +for those who want to evaluate Pyramid, whether you are new to Python +web frameworks, or a pro in a hurry. For more detailed treatment of +each topic, give the :ref:`quick_tutorial` a try. - -Conventions -=========== -This guide uses conventions to keep the introduction focused and concise. -Details, references, and deeper discussions are mentioned in "See Also" -notes. - -.. seealso:: This is an example "See Also" note. - -Pyramid encourages standard Python development practices with packaging tools, -virtual environments, logging, and so on. There are many variations, -implementations, and opinions across the Python community, each of which may -have its proper usage. For the sake of consistency, ease of documentation -maintenance, and to minimize confusion, the Pyramid documentation has adopted -specific conventions: - -* Pyramid fully supports Python 3.2 or greater as well as Python 2.6 and 2.7. - This guide uses Python 3. -* We use ``pyvenv`` for isolating Python environments. -* We use ``setuptools`` for package management. -* We organize our file system where our home directory contains all of our - projects, which contains our workspaces, which contain both Python virtual - environments and projects. -* Commands in this guide use UNIX syntax and paths. Windows users should - adjust commands accordingly. - -.. note:: - - Pyramid was one of the first web frameworks to fully support Python 3 in - October 2011. - -Requirements +Installation ============ -* :ref:`install-python-3.3-or-greater` -* :ref:`create-a-project-directory-structure` -* :ref:`set-an-environment-variable` -* :ref:`create-a-virtual-environment` -* :ref:`install-setuptools-(python-packaging-tools)` -* :ref:`install-pyramid` - -.. warning:: The current state of isolated Python environments using - ``pyvenv`` on Windows is suboptimal in comparison to Mac and Linux. See - http://stackoverflow.com/q/15981111/95735 for a discussion of the issue - and `PEP 453 `_ for a proposed - resolution. When it is resolved, or if any Windows user would like to step - forward, we would gratefully accept a pull request to update our - documentation. - - Until then, we recommend that Windows users follow the procedure - :ref:`Installing Pyramid on a Windows System ` - -.. _install-python-3.3-or-greater: - -Install Python 3.3 or greater ------------------------------ - -Download the latest standard Python 3 release (not development release) from -`python.org `_. On that page, you -must click the latest version, then scroll down to the "Downloads" section -for your operating system. - -Windows and Mac OS X users can download and run an installer. - -Windows users should also install the `Python for Windows extensions -`_. Carefully read the -``README.txt`` file at the end of the list of builds, and follow its -directions. Make sure you get the proper 32- or 64-bit build and Python -version. - -Linux users can either use their package manager to install Python 3 or may -`build Python 3 from source -`_. - - -.. _create-a-project-directory-structure: - -Create a project directory structure ------------------------------------- - -From your user home directory, create the following initial directory structure -as indicated in the figure below. - -.. figure:: _static/directory_structure_initial.png - :alt: initial directory structure - - An initial directory structure. - -The commands to do so are as follows: - -.. code-block:: bash - - # Mac and Linux - $ cd ~ - $ mkdir projects - $ cd projects - $ mkdir pyramid - - # Windows - c:\> cd \ - c:\> mkdir projects - c:\> cd projects - c:\> mkdir pyramid - -In the above figure, your user home directory is represented by ``~``. In -your home directory, all of your projects are in the ``projects`` directory. -This is a general convention not specific to Pyramid that many developers use. -Windows users will do well to use ``c:\`` as the location for ``projects`` in -order to avoid spaces in any of the path names. - -Next within ``projects`` is your workspace directory, here named ``pyramid``. -A workspace is a common term used by integrated development environments (IDE) -like PyCharm and PyDev that stores isolated Python environments (virtualenvs) -and specific project files and repositories. - - -.. _set-an-environment-variable: - -Set an Environment Variable ---------------------------- - -We set an environment variable to save typing later. - -.. code-block:: bash - - # Mac and Linux - $ export VENV=~/projects/pyramid/env33/bin/ - - # Windows - # TODO: This command does not work - c:\> set VENV=c:\projects\pyramid\env33 - - -.. _create-a-virtual-environment: - -Create a Virtual Environment ----------------------------- -``pyvenv`` is a tool to create isolated Python environments. Create one. - -.. code-block:: bash - - # Mac and Linux - $ pyvenv $VENV - - # Windows - # TODO: This command does work, but we should improve it with %VENV% - c:\> .\Python33\python -m venv c:\projects\pyramid\env33 - -.. note:: ``pyvenv`` is a tool to create isolated Python environments. The - venv module provides support for creating lightweight "virtual - environments" with their own site directories, optionally isolated from - system site directories. Each virtual environment has its own Python binary - (allowing creation of environments with various Python versions) and can - have its own independent set of installed Python packages in its site - directories. - -.. seealso:: See also Python 3's :mod:`venv module ` and Python - 2's `virtualenv `_ package. - - -.. _install-setuptools-(python-packaging-tools): - -Install ``setuptools`` (Python packaging tools) ------------------------------------------------ +Once you have a standard Python environment setup, getting started with +Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. +For this Quick Tour, it means: +`Python `_, a +`virtual environment `_ +(or `virtualenv for Python 2.7 `_, +and `setuptools `_. -The following command will download a script to install ``setuptools``, then -pipe it to your environment's version of Python. +As an example, for Python 3.3+ on Linux: .. code-block:: bash - # Mac and Linux - $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/python - - # Windows - # TODO Something goes here + $ pyvenv env33 + $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | env33/bin/python + $ env33/bin/easy_install pyramid -If ``wget`` complains with a certificate error, then run this command instead: +For Windows: -.. code-block:: bash - - # Mac and Linux - $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/python - - # Windows - # TODO Something goes here - - -.. _install-pyramid: - -Install Pyramid ---------------- - -.. code-block:: bash - - # Mac and Linux - $ easy_install pyramid - - # Windows - # TODO Something goes here - -Our Python environment now has the Pyramid software available. Your directory structure should now look like the following image. +.. code-block:: posh -.. figure:: _static/directory_structure_pyramid.png - :alt: Pyramid directory structure - - A Pyramid directory structure. + # Use your browser to download: + # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py + c:\> c:\Python33\python -m venv env33 + c:\> env33\Scripts\python ez_setup.py + c:\> env33\Scripts\easy_install pyramid +Of course Pyramid runs fine on Python 2.6+, as do the examples in this +*Quick Tour*. We're just showing Python 3 a little love (Pyramid had +production support in October 2011.) .. note:: @@ -223,25 +49,11 @@ Our Python environment now has the Pyramid software available. Your directory s some optional C extensions for performance. With ``easy_install``, Windows users can get these extensions without needing a C compiler. -.. seealso:: See Also: :ref:`installing_unix`. For instructions to set up your - Python environment for development using Windows or Python 2, see Pyramid's - :ref:`Before You Install `. - - See also Python 3's :mod:`venv module `, the `setuptools` `installation instructions - `_, - and `easy_install help `_. - -.. note:: A generic representation of project directory structure is shown in - the following figure. We could create multiple isolated Python - environments for multiple versions of Python. We could also add more - projects within our workspace directory, which is a common practice in the - Pyramid tutorials. - -.. figure:: _static/directory_structure_generic.png - :alt: generic directory structure - - A generic directory structure. - +.. seealso:: See Also: + :ref:`Quick Tutorial section on Requirements `, + :ref:`installing_unix`, + :ref:`Before You Install `, and + :ref:`Installing Pyramid on a Windows System ` Hello World =========== @@ -280,7 +92,9 @@ in Pyramid development. Building an application from loosely-coupled parts via :doc:`../narr/configuration` is a central idea in Pyramid, one that we will revisit regurlarly in this *Quick Tour*. -.. seealso:: See Also: :ref:`firstapp_chapter` and +.. seealso:: See Also: + :ref:`Quick Tutorial Hello World `, + :ref:`firstapp_chapter`, and :ref:`Single File Tasks tutorial ` Handling Web Requests and Responses @@ -311,7 +125,10 @@ the name is included in the body of the response:: Finally, we set the response's content type and return the Response. -.. seealso:: See Also: :ref:`webob_chapter` +.. seealso:: See Also: + :ref:`Quick Tutorial Request and Response ` + and + :ref:`webob_chapter` Views ===== @@ -361,7 +178,9 @@ configuration`, in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually, it is simply a matter of taste. -.. seealso:: See Also: :doc:`../narr/views`, +.. seealso:: See Also: + :ref:`Quick Tutorial Views `, + :doc:`../narr/views`, :doc:`../narr/viewconfig`, and :ref:`debugging_view_configuration` @@ -407,7 +226,9 @@ view: "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view. -.. seealso:: See Also: :doc:`../narr/urldispatch`, +.. seealso:: See Also: + :ref:`Quick Tutorial Routing `, + :doc:`../narr/urldispatch`, :ref:`debug_routematch_section`, and :doc:`../narr/router` @@ -441,9 +262,11 @@ Since our view returned ``dict(name=request.matchdict['name'])``, we can use ``name`` as a variable in our template via ``${name}``. -.. seealso:: See Also: :doc:`../narr/templates`, - :ref:`debugging_templates`, and - :ref:`available_template_system_bindings` +.. seealso:: See Also: + :ref:`Quick Tutorial Templating `, + :doc:`../narr/templates`, + :ref:`debugging_templates`, and + :ref:`available_template_system_bindings` Templating With ``jinja2`` ========================== @@ -482,9 +305,10 @@ filename extensions. In this case, changing the extension from ``.pt`` to ``.jinja2`` passed the view response through the ``pyramid_jinja2`` renderer. -.. seealso:: See Also: `Jinja2 homepage `_, - and - :ref:`pyramid_jinja2 Overview ` +.. seealso:: See Also: + :ref:`Quick Tutorial Jinja2 `, + `Jinja2 homepage `_, and + :ref:`pyramid_jinja2 Overview ` Static Assets ============= @@ -529,9 +353,11 @@ By using ``request.static_url`` to generate the full URL to the static assets, you both ensure you stay in sync with the configuration and gain refactoring flexibility later. -.. seealso:: See Also: :doc:`../narr/assets`, - :ref:`preventing_http_caching`, and - :ref:`influencing_http_caching` +.. seealso:: See Also: + :ref:`Quick Tutorial Static Assets `, + :doc:`../narr/assets`, + :ref:`preventing_http_caching`, and + :ref:`influencing_http_caching` Returning JSON ============== @@ -548,9 +374,11 @@ This wires up a view that returns some data through the JSON :term:`renderer`, which calls Python's JSON support to serialize the data into JSON and set the appropriate HTTP headers. -.. seealso:: See Also: :ref:`views_which_use_a_renderer`, - :ref:`json_renderer`, and - :ref:`adding_and_overriding_renderers` +.. seealso:: See Also: + :ref:`Quick Tutorial JSON `, + :ref:`views_which_use_a_renderer`, + :ref:`json_renderer`, and + :ref:`adding_and_overriding_renderers` View Classes ============ @@ -593,7 +421,20 @@ Only one route needed, stated in one place atop the view class. Also, the assignment of the ``name`` is done in the ``__init__``. Our templates can then use ``{{ view.name }}``. -.. seealso:: See Also: :ref:`class_as_view` +Pyramid view classes, combined with built-in and custom predicates, +have much more to offer: + +- All the same view configuration parameters as function views + +- One route leading to multiple views, based on information in the + request or data such as ``request_param``, ``request_method``, + ``accept``, ``header``, ``xhr``, ``containment``, and + ``custom_predicates`` + +.. seealso:: See Also: + :ref:`Quick Tutorial View Classes `, + :ref:`Quick Tutorial More View Classes `, and + :ref:`class_as_view` Quick Project Startup with Scaffolds ==================================== @@ -641,8 +482,10 @@ configuration. This includes a new way of running your application: Let's look at ``pserve`` and configuration in more depth. -.. seealso:: See Also: :ref:`project_narr` and - :doc:`../narr/scaffolding` +.. seealso:: See Also: + :ref:`Quick Tutorial Scaffolds `, + :ref:`project_narr`, and + :doc:`../narr/scaffolding` Application Running with ``pserve`` =================================== @@ -670,7 +513,8 @@ Most of the work, though, comes from your project's wiring, as expressed in the configuration file you supply to ``pserve``. Let's take a look at this configuration file. -.. seealso:: See Also: :ref:`what_is_this_pserve_thing` +.. seealso:: See Also: + :ref:`what_is_this_pserve_thing` Configuration with ``.ini`` Files ================================= @@ -717,8 +561,10 @@ Additionally, the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well traceback information. -.. seealso:: See Also: :ref:`environment_chapter` and - :doc:`../narr/paste` +.. seealso:: See Also: + :ref:`Quick Tutorial Application Configuration `, + :ref:`environment_chapter` and + :doc:`../narr/paste` Easier Development with ``debugtoolbar`` @@ -770,7 +616,10 @@ you want to disable this toolbar, no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. -.. seealso:: See Also: :ref:`pyramid_debugtoolbar ` +.. seealso:: See Also: + :ref:`Quick Tutorial + pyramid_debugtoolbar ` and + :ref:`pyramid_debugtoolbar ` Unit Tests and ``nose`` ======================= @@ -821,7 +670,11 @@ Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. -.. seealso:: See Also: :ref:`testing_chapter` +.. seealso:: See Also: + :ref:`Quick Tutorial Unit Testing `, + :ref:`Quick Tutorial Functional Testing `, + and + :ref:`testing_chapter` Logging ======= @@ -864,7 +717,9 @@ visit ``http://localhost:6543`` your console will now show:: 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message -.. seealso:: See Also: :ref:`logging_chapter` +.. seealso:: See Also: + :ref:`Quick Tutorial Logging ` and + :ref:`logging_chapter` Sessions ======== @@ -911,9 +766,10 @@ Jinja2 template: :end-before: End Sphinx Include 1 .. seealso:: See Also: - :ref:`sessions_chapter`, :ref:`flash_messages`, - :ref:`session_module`, and - :ref:`Beaker sessioning middleware ` + :ref:`Quick Tutorial Sessions `, + :ref:`sessions_chapter`, :ref:`flash_messages`, + :ref:`session_module`, and + :ref:`Beaker sessioning middleware ` Databases ========= @@ -958,10 +814,12 @@ of the system, can then easily get at the data thanks to SQLAlchemy: :start-after: Start Sphinx Include :end-before: End Sphinx Include -.. seealso:: See Also: `SQLAlchemy `_, - :ref:`making_a_console_script`, - :ref:`bfg_sql_wiki_tutorial`, and - :ref:`Application Transactions With pyramid_tm ` +.. seealso:: See Also: + :ref:`Quick Tutorial Databases `, + `SQLAlchemy `_, + :ref:`making_a_console_script`, + :ref:`bfg_sql_wiki_tutorial`, and + :ref:`Application Transactions With pyramid_tm ` Forms ===== @@ -1020,9 +878,10 @@ widgets using attractive CSS from Bootstrap and more powerful widgets from Chosen. .. seealso:: See Also: - :ref:`Deform `, - :ref:`Colander `, and - `deform_bootstrap `_ + :ref:`Quick Tutorial Forms `, + :ref:`Deform `, + :ref:`Colander `, and + `deform_bootstrap `_ Conclusion ========== -- cgit v1.2.3 From a8cb0406c3096486dd66204aa144cb117dab0890 Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Sat, 28 Sep 2013 09:59:09 +0300 Subject: OCD: add back missing ) --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 434dbdad5..1ac5181f3 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -17,7 +17,7 @@ Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. For this Quick Tour, it means: `Python `_, a `virtual environment `_ -(or `virtualenv for Python 2.7 `_, +(or `virtualenv for Python 2.7 `_), and `setuptools `_. As an example, for Python 3.3+ on Linux: -- cgit v1.2.3 From ebca905c2a2e1e796f3840baaf154a6d9d695cc4 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Sat, 28 Sep 2013 12:14:13 -0400 Subject: Used a parsed-literal to pin the version number on easy_install. --- docs/quick_tour.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 1ac5181f3..98584e608 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -22,21 +22,21 @@ and `setuptools `_. As an example, for Python 3.3+ on Linux: -.. code-block:: bash +.. parsed-literal:: $ pyvenv env33 $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | env33/bin/python - $ env33/bin/easy_install pyramid + $ env33/bin/easy_install "pyramid==\ |release|\ " For Windows: -.. code-block:: posh +.. parsed-literal:: # Use your browser to download: # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py - c:\> c:\Python33\python -m venv env33 - c:\> env33\Scripts\python ez_setup.py - c:\> env33\Scripts\easy_install pyramid + c:\\> c:\\Python33\\python -m venv env33 + c:\\> env33\\Scripts\\python ez_setup.py + c:\\> env33\\Scripts\\easy_install "pyramid==\ |release|\ " Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had @@ -297,7 +297,7 @@ The only change in our view...point the renderer at the ``.jinja2`` file: Our Jinja2 template is very similar to our previous template: .. literalinclude:: quick_tour/jinja2/hello_world.jinja2 - :language: jinja + :language: html Pyramid's templating add-ons register a new kind of renderer into your application. The renderer registration maps to different kinds of -- cgit v1.2.3 From ab2fedf7adaec0a56a69beed35312c88d7961c6c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 2 Oct 2013 17:47:17 -0400 Subject: fix the docs build and get rid of stray references to Beaker --- docs/quick_tour.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 98584e608..2db18c8a7 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -729,8 +729,8 @@ that requires semi-permanent data to be saved. For example, a shopping cart. This is called a :term:`session`. Pyramid has basic built-in support for sessions, with add-ons such as -*Beaker* (or your own custom sessioning engine) that provide richer -session support. Let's take a look at the +``pyramid_redis_sessions`` (or your own custom sessioning engine) that provide +richer session support. Let's take a look at the :doc:`built-in sessioning support <../narr/sessions>`. In our ``__init__.py`` we first import the kind of sessioning we want: @@ -768,8 +768,7 @@ Jinja2 template: .. seealso:: See Also: :ref:`Quick Tutorial Sessions `, :ref:`sessions_chapter`, :ref:`flash_messages`, - :ref:`session_module`, and - :ref:`Beaker sessioning middleware ` + :ref:`session_module`, and :term:`pyramid_redis_sessions`. Databases ========= -- cgit v1.2.3 From 561a7edd3f3a2b25ca4a8f1393abf01be99fbbe3 Mon Sep 17 00:00:00 2001 From: Hari haran Date: Mon, 14 Oct 2013 01:50:13 +0530 Subject: Specified installation instructions for pyramid_chameleon --- docs/quick_tour.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 2db18c8a7..cdc70681c 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -246,6 +246,23 @@ languages. That said, the Pylons Project officially supports bindings for Chameleon, Jinja2 and Mako, so in this step, let's use Chameleon as an example: +Let's add ``pyramid_chameleon``, +a Pyramid :term:`add-on` which enables Chameleon as a :term:`renderer` in +our Pyramid applications: + +.. code-block:: bash + + $ easy_install pyramid_chameleon + +With the package installed, we can include the template bindings into +our configuration: + +.. code-block:: python + + config.include('pyramid_chameleon') + +Now lets change our views.py file: + .. literalinclude:: quick_tour/templating/views.py :start-after: Start View 1 :end-before: End View 1 -- cgit v1.2.3 From 039d12ad4f736548ff05e0626f16f314ec10ba21 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 9 Feb 2014 23:10:03 -0600 Subject: - Clean up PR #1163 --- docs/quick_tour.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index cdc70681c..0a8f58fd0 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -243,12 +243,10 @@ Pyramid doesn't mandate a particular database system, form library, etc. It encourages replaceability. This applies equally to templating, which is fortunate: developers have strong views about template languages. That said, the Pylons Project officially supports bindings for -Chameleon, Jinja2 and Mako, so in this step, let's use Chameleon as an -example: +Chameleon, Jinja2, and Mako, so in this step, let's use Chameleon. -Let's add ``pyramid_chameleon``, -a Pyramid :term:`add-on` which enables Chameleon as a :term:`renderer` in -our Pyramid applications: +Let's add ``pyramid_chameleon``, a Pyramid :term:`add-on` which enables +Chameleon as a :term:`renderer` in our Pyramid applications: .. code-block:: bash -- cgit v1.2.3 From 5ac519452613b7bd5df22293c2ccb3b9c3597ef4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 10 Feb 2014 01:10:05 -0600 Subject: - Update list of session packages - Update Quick Tour section on sessions - Closes PR #1150 --- docs/quick_tour.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 0a8f58fd0..65fd002d5 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -743,9 +743,9 @@ When people use your web application, they frequently perform a task that requires semi-permanent data to be saved. For example, a shopping cart. This is called a :term:`session`. -Pyramid has basic built-in support for sessions, with add-ons such as -``pyramid_redis_sessions`` (or your own custom sessioning engine) that provide -richer session support. Let's take a look at the +Pyramid has basic built-in support for sessions. Third party packages such as +``pyramid_redis_sessions`` provide richer session support. Or you can create +your own custom sessioning engine. Let's take a look at the :doc:`built-in sessioning support <../narr/sessions>`. In our ``__init__.py`` we first import the kind of sessioning we want: -- cgit v1.2.3 From 2033eeb3602f330930585678aac926749b9c22f7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 10 Feb 2014 03:22:33 -0600 Subject: - Garden PR #1121 --- docs/quick_tour.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 65fd002d5..2d4e679f8 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -49,7 +49,7 @@ production support in October 2011.) some optional C extensions for performance. With ``easy_install``, Windows users can get these extensions without needing a C compiler. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, :ref:`installing_unix`, :ref:`Before You Install `, and @@ -92,7 +92,7 @@ in Pyramid development. Building an application from loosely-coupled parts via :doc:`../narr/configuration` is a central idea in Pyramid, one that we will revisit regurlarly in this *Quick Tour*. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Hello World `, :ref:`firstapp_chapter`, and :ref:`Single File Tasks tutorial ` @@ -125,7 +125,7 @@ the name is included in the body of the response:: Finally, we set the response's content type and return the Response. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Request and Response ` and :ref:`webob_chapter` @@ -178,7 +178,7 @@ configuration`, in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually, it is simply a matter of taste. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Views `, :doc:`../narr/views`, :doc:`../narr/viewconfig`, and @@ -226,7 +226,7 @@ view: "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Routing `, :doc:`../narr/urldispatch`, :ref:`debug_routematch_section`, and @@ -277,7 +277,7 @@ Since our view returned ``dict(name=request.matchdict['name'])``, we can use ``name`` as a variable in our template via ``${name}``. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Templating `, :doc:`../narr/templates`, :ref:`debugging_templates`, and @@ -320,7 +320,7 @@ filename extensions. In this case, changing the extension from ``.pt`` to ``.jinja2`` passed the view response through the ``pyramid_jinja2`` renderer. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Jinja2 `, `Jinja2 homepage `_, and :ref:`pyramid_jinja2 Overview ` @@ -368,7 +368,7 @@ By using ``request.static_url`` to generate the full URL to the static assets, you both ensure you stay in sync with the configuration and gain refactoring flexibility later. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Static Assets `, :doc:`../narr/assets`, :ref:`preventing_http_caching`, and @@ -389,7 +389,7 @@ This wires up a view that returns some data through the JSON :term:`renderer`, which calls Python's JSON support to serialize the data into JSON and set the appropriate HTTP headers. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial JSON `, :ref:`views_which_use_a_renderer`, :ref:`json_renderer`, and @@ -446,7 +446,7 @@ have much more to offer: ``accept``, ``header``, ``xhr``, ``containment``, and ``custom_predicates`` -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial View Classes `, :ref:`Quick Tutorial More View Classes `, and :ref:`class_as_view` @@ -497,7 +497,7 @@ configuration. This includes a new way of running your application: Let's look at ``pserve`` and configuration in more depth. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Scaffolds `, :ref:`project_narr`, and :doc:`../narr/scaffolding` @@ -528,7 +528,7 @@ Most of the work, though, comes from your project's wiring, as expressed in the configuration file you supply to ``pserve``. Let's take a look at this configuration file. -.. seealso:: See Also: +.. seealso:: See also: :ref:`what_is_this_pserve_thing` Configuration with ``.ini`` Files @@ -576,7 +576,7 @@ Additionally, the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well traceback information. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Application Configuration `, :ref:`environment_chapter` and :doc:`../narr/paste` @@ -631,7 +631,7 @@ you want to disable this toolbar, no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial pyramid_debugtoolbar ` and :ref:`pyramid_debugtoolbar ` @@ -685,7 +685,7 @@ Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Unit Testing `, :ref:`Quick Tutorial Functional Testing `, and @@ -732,7 +732,7 @@ visit ``http://localhost:6543`` your console will now show:: 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Logging ` and :ref:`logging_chapter` @@ -780,7 +780,7 @@ Jinja2 template: :start-after: Start Sphinx Include 1 :end-before: End Sphinx Include 1 -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Sessions `, :ref:`sessions_chapter`, :ref:`flash_messages`, :ref:`session_module`, and :term:`pyramid_redis_sessions`. @@ -828,7 +828,7 @@ of the system, can then easily get at the data thanks to SQLAlchemy: :start-after: Start Sphinx Include :end-before: End Sphinx Include -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Databases `, `SQLAlchemy `_, :ref:`making_a_console_script`, @@ -891,7 +891,7 @@ Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets using attractive CSS from Bootstrap and more powerful widgets from Chosen. -.. seealso:: See Also: +.. seealso:: See also: :ref:`Quick Tutorial Forms `, :ref:`Deform `, :ref:`Colander `, and -- cgit v1.2.3 From 58febc5917a82ef1ae25af92b62843ad3c6d5e0e Mon Sep 17 00:00:00 2001 From: Paul Winkler Date: Fri, 7 Mar 2014 11:19:29 -0500 Subject: Minor punctuation and grammar changes to Quick Intro --- docs/quick_tour.rst | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 2d4e679f8..4ab39bb11 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -73,14 +73,14 @@ This simple example is easy to run. Save this as ``app.py`` and run it: Next, open `http://localhost:6543/ `_ in a browser and you will see the ``Hello World!`` message. -New to Python web programming? If so, some lines in module merit +New to Python web programming? If so, some lines in the module merit explanation: #. *Line 10*. The ``if __name__ == '__main__':`` is Python's way of saying "Start here when running from the command line". #. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect - :term:`view` code to particular URL :term:`route`. + :term:`view` code to a particular URL :term:`route`. #. *Lines 6-7*. Implement the view code that generates the :term:`response`. @@ -148,15 +148,15 @@ So far our examples place everything in one file: - the WSGI application launcher 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 ``app.py`` to scan that module, looking for decorators that set up the views. First, our revised ``app.py``: .. literalinclude:: quick_tour/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 ``config.scan('views')``. +Our views and their registrations (via decorators) are now in a module +``views.py``, which is scanned via ``config.scan('views')``. We now have a ``views.py`` module that is focused on handling requests and responses: @@ -167,7 +167,7 @@ and responses: We have 4 views, each leading to the other. If you start at ``http://localhost:6543/``, you get a response with a link to the next view. The ``hello_view`` (available at the URL ``/howdy``) has a link -to the ``redirect_view``, which shows issuing a redirect to the final +to the ``redirect_view``, which issues a redirect to the final view. Earlier we saw ``config.add_view`` as one way to configure a view. This @@ -267,7 +267,7 @@ Now lets change our views.py file: Ahh, that looks better. We have a view that is focused on Python code. Our ``@view_config`` decorator specifies a :term:`renderer` that points -our template file. Our view then simply returns data which is then +to our template file. Our view then simply returns data which is then supplied to our template: .. literalinclude:: quick_tour/templating/hello_world.pt @@ -303,7 +303,7 @@ our configuration: config.include('pyramid_jinja2') -The only change in our view...point the renderer at the ``.jinja2`` file: +The only change in our view is to point the renderer at the ``.jinja2`` file: .. literalinclude:: quick_tour/jinja2/views.py :start-after: Start View 1 @@ -356,8 +356,8 @@ template: This link presumes that our CSS is at a URL starting with ``/static/``. What if the site is later moved under ``/somesite/static/``? Or perhaps -web developer changes the arrangement on disk? Pyramid gives a helper -that provides flexibility on URL generation: +a web developer changes the arrangement on disk? Pyramid provides a helper +to allow flexibility on URL generation: .. literalinclude:: quick_tour/static_assets/hello_world.pt :language: html @@ -454,7 +454,7 @@ have much more to offer: Quick Project Startup with Scaffolds ==================================== -So far we have done all of our *Quick Glance* as a single Python file. +So far we have done all of our *Quick Tour* as a single Python file. No Python packages, no structure. Most Pyramid projects, though, aren't developed this way. @@ -479,7 +479,7 @@ let's use that scaffold to make our project: $ pcreate --scaffold pyramid_jinja2_starter hello_world -We next use the normal Python development to setup our package for +We next use the normal Python command to set up our package for development: .. code-block:: bash @@ -534,7 +534,7 @@ take a look at this configuration file. Configuration with ``.ini`` Files ================================= -Earlier in *Quick Glance* we first met Pyramid's configuration system. +Earlier in *Quick Tour* we first met Pyramid's configuration system. At that point we did all configuration in Python code. For example, the port number chosen for our HTTP server was right there in Python code. Our scaffold has moved this decision, and more, into the @@ -556,8 +556,8 @@ into sections: We have a few decisions made for us in this configuration: -#. *Choice of web server*. The ``use = egg:pyramid#wsgiref`` tell - ``pserve`` to the ``wsgiref`` server that is wrapped in the Pyramid +#. *Choice of web server*. The ``use = egg:pyramid#wsgiref`` tells + ``pserve`` to use the ``wsgiref`` server that is wrapped in the Pyramid package. #. *Port number*. ``port = 6543`` tells ``wsgiref`` to listen on port @@ -574,7 +574,7 @@ We have a few decisions made for us in this configuration: Additionally, the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, -a log on every request that comes in, as well traceback information. +a log on every request that comes in, as well as traceback information. .. seealso:: See also: :ref:`Quick Tutorial Application Configuration `, @@ -585,7 +585,7 @@ a log on every request that comes in, as well traceback information. Easier Development with ``debugtoolbar`` ======================================== -As we introduce the basics we also want to show how to be productive in +As we introduce the basics, we also want to show how to be productive in development and debugging. For example, we just discussed template reloading and earlier we showed ``--reload`` for application reloading. @@ -700,12 +700,12 @@ we might need to detect situations when other people use the site. We need *logging*. Fortunately Pyramid uses the normal Python approach to logging. The -scaffold generated, in your ``development.ini``, a number of lines that +scaffold generated in your ``development.ini`` a number of lines that configure the logging for you to some reasonable defaults. You then see -messages sent by Pyramid (for example, when a new request comes in.) +messages sent by Pyramid (for example, when a new request comes in). Maybe you would like to log messages in your code? In your Python -module, import and setup the logging: +module, import and set up the logging: .. literalinclude:: quick_tour/package/hello_world/views.py :start-after: Start Logging 1 @@ -726,7 +726,7 @@ controls that? These sections in the configuration file: :start-after: Start Sphinx Include :end-before: End Sphinx Include -Our application, a package named ``hello_world``, is setup as a logger +Our application, a package named ``hello_world``, is set up as a logger and configured to log messages at a ``DEBUG`` or higher level. When you visit ``http://localhost:6543`` your console will now show:: @@ -789,7 +789,7 @@ Databases ========= Web applications mean data. Data means databases. Frequently SQL -databases. SQL Databases frequently mean an "ORM" +databases. SQL databases frequently mean an "ORM" (object-relational mapper.) In Python, ORM usually leads to the mega-quality *SQLAlchemy*, a Python package that greatly eases working with databases. -- cgit v1.2.3 From ba59b7b87796003138e7ebb01f5bc8a4a7b542a0 Mon Sep 17 00:00:00 2001 From: Omid Raha Date: Mon, 14 Apr 2014 12:38:24 +0430 Subject: Correct missing word. --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 4ab39bb11..41a0dc8c0 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -700,7 +700,7 @@ we might need to detect situations when other people use the site. We need *logging*. Fortunately Pyramid uses the normal Python approach to logging. The -scaffold generated in your ``development.ini`` a number of lines that +scaffold generated in your ``development.ini`` has a number of lines that configure the logging for you to some reasonable defaults. You then see messages sent by Pyramid (for example, when a new request comes in). -- cgit v1.2.3 From e560e5d365d559551385888d823a6068c6e093d3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 16 May 2015 15:02:49 -0700 Subject: grammar fix --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 41a0dc8c0..b94ae27ca 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -505,7 +505,7 @@ Let's look at ``pserve`` and configuration in more depth. Application Running with ``pserve`` =================================== -Prior to scaffolds, our project mixed a number of operations details +Prior to scaffolds, our project mixed a number of operational details into our code. Why should my main code care which HTTP server I want and what port number to run on? -- cgit v1.2.3 From 6268f5d65bc0e41d6213d4e4bf27e36c9334f684 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 16 May 2015 15:50:06 -0700 Subject: grammar fix --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index b94ae27ca..e71725406 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -627,7 +627,7 @@ You'll now see an attractive (and collapsible) menu in the right of your browser, providing introspective access to debugging information. Even better, if your web application generates an error, you will see a nice traceback on the screen. When -you want to disable this toolbar, no need to change code: you can +you want to disable this toolbar, there's no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. -- cgit v1.2.3 From 109792709bf90eddf85eaaed1743b5cbb1faa34e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 16 May 2015 16:12:35 -0700 Subject: cherrypick from 1.5 --- docs/quick_tour.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index e71725406..1b8c82b0a 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -14,11 +14,10 @@ Installation Once you have a standard Python environment setup, getting started with Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. -For this Quick Tour, it means: -`Python `_, a -`virtual environment `_ -(or `virtualenv for Python 2.7 `_), -and `setuptools `_. +For this Quick Tour, it means: `Python `_, +a `virtual environment `_ (or +`virtualenv for Python 2.7 `_), and +`setuptools `_. As an example, for Python 3.3+ on Linux: -- cgit v1.2.3 From c1677348ad92a7998ae1163c3e2f7b38942849c2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 28 May 2015 02:23:56 -0700 Subject: grammar, punctuation --- docs/quick_tour.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 1b8c82b0a..a0f530830 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -39,12 +39,12 @@ For Windows: Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had -production support in October 2011.) +production support for Python 3 in October 2011). .. note:: Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace - packages which, until recently, ``pip`` didn't permit. Also, Pyramid has + packages which, until recently, ``pip`` didn't permit. Also Pyramid has some optional C extensions for performance. With ``easy_install``, Windows users can get these extensions without needing a C compiler. -- cgit v1.2.3 From 1273d0bfc4717d2eb115710fbc4483b70fa858ac Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 28 May 2015 10:55:20 -0700 Subject: grammar, punctuation, caps, rewrap 79-columns --- docs/quick_tour.rst | 126 ++++++++++++++++++++++++++-------------------------- 1 file changed, 62 insertions(+), 64 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index a0f530830..0fc3a7ab8 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -69,8 +69,8 @@ This simple example is easy to run. Save this as ``app.py`` and run it: $ python ./app.py -Next, open `http://localhost:6543/ `_ in a -browser and you will see the ``Hello World!`` message. +Next open http://localhost:6543/ in a browser, and you will see the ``Hello +World!`` message. New to Python web programming? If so, some lines in the module merit explanation: @@ -96,7 +96,7 @@ one that we will revisit regurlarly in this *Quick Tour*. :ref:`firstapp_chapter`, and :ref:`Single File Tasks tutorial ` -Handling Web Requests and Responses +Handling web requests and responses =================================== Developing for the web means processing web requests. As this is a @@ -104,21 +104,20 @@ 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 `. +development (virtual environments, packaging, scaffolding, one of the first to +embrace Python 3, etc.). 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_tour/requests/app.py :pyobject: hello_world -In this Pyramid view, we get the URL being visited from ``request.url``. -Also, if you visited ``http://localhost:6543/?name=alice``, -the name is included in the body of the response:: +In this Pyramid view, we get the URL being visited from ``request.url``. Also, +if you visited http://localhost:6543/?name=alice in a browser, the name is +included in the body of the response:: URL http://localhost:6543/?name=alice with name: alice @@ -142,13 +141,15 @@ So far our examples place everything in one file: - its registration with the configurator -- the route to map it to a URL +- the route to map it to an URL - the WSGI application launcher 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 set up -the views. First, our revised ``app.py``: +the views. + +First, our revised ``app.py``: .. literalinclude:: quick_tour/views/app.py :linenos: @@ -163,8 +164,8 @@ and responses: .. literalinclude:: quick_tour/views/views.py :linenos: -We have 4 views, each leading to the other. If you start at -``http://localhost:6543/``, you get a response with a link to the next +We have four views, each leading to the other. If you start at +http://localhost:6543/, you get a response with a link to the next view. The ``hello_view`` (available at the URL ``/howdy``) has a link to the ``redirect_view``, which issues a redirect to the final view. @@ -175,7 +176,7 @@ section introduces ``@view_config``. Pyramid's configuration supports the previous example. You can also use :term:`declarative configuration`, in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final -configuration, thus usually, it is simply a matter of taste. +configuration, thus usually it is simply a matter of taste. .. seealso:: See also: :ref:`Quick Tutorial Views `, @@ -195,7 +196,7 @@ Above we saw the basics of routing URLs to views in Pyramid: - Your project's "setup" code registers a route name to be used when matching part of the URL -- Elsewhere, a view is configured to be called for that route name +- Elsewhere a view is configured to be called for that route name .. note:: @@ -282,12 +283,12 @@ we can use ``name`` as a variable in our template via :ref:`debugging_templates`, and :ref:`available_template_system_bindings` -Templating With ``jinja2`` +Templating with ``jinja2`` ========================== We just said Pyramid doesn't prefer one templating language over another. Time to prove it. Jinja2 is a popular templating system, -modelled after Django's templates. Let's add ``pyramid_jinja2``, +modeled after Django's templates. Let's add ``pyramid_jinja2``, a Pyramid :term:`add-on` which enables Jinja2 as a :term:`renderer` in our Pyramid applications: @@ -324,12 +325,12 @@ renderer. `Jinja2 homepage `_, and :ref:`pyramid_jinja2 Overview ` -Static Assets +Static assets ============= Of course the Web is more than just markup. You need static assets: CSS, JS, and images. Let's point our web app at a directory where -Pyramid will serve some static assets. First, another call to the +Pyramid will serve some static assets. First another call to the :term:`configurator`: .. literalinclude:: quick_tour/static_assets/app.py @@ -337,10 +338,10 @@ Pyramid will serve some static assets. First, another call to the :end-before: End Static 1 This tells our WSGI application to map requests under -``http://localhost:6543/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: +Next make a directory named ``static``, and place ``app.css`` inside: .. literalinclude:: quick_tour/static_assets/static/app.css :language: css @@ -394,14 +395,13 @@ into JSON and set the appropriate HTTP headers. :ref:`json_renderer`, and :ref:`adding_and_overriding_renderers` -View Classes +View classes ============ So far our views have been simple, free-standing functions. Many times your views are related: different ways to look at or work on the same -data or a REST API that handles multiple operations. Grouping these -together as a -:ref:`view class ` makes sense: +data, or a REST API that handles multiple operations. Grouping these +together as a :ref:`view class ` makes sense. - Group views @@ -425,14 +425,14 @@ Specifically: - The second view is returned when the form data contains a field with ``form.edit``, such as clicking on - ````. This rule + ````. This rule is specified in the ``@view_config`` for that view. - The third view is returned when clicking on a button such - as ````. + as ````. -Only one route needed, stated in one place atop the view class. Also, -the assignment of the ``name`` is done in the ``__init__``. Our +Only one route is needed, stated in one place atop the view class. Also, +the assignment of ``name`` is done in the ``__init__`` function. Our templates can then use ``{{ view.name }}``. Pyramid view classes, combined with built-in and custom predicates, @@ -450,7 +450,7 @@ have much more to offer: :ref:`Quick Tutorial More View Classes `, and :ref:`class_as_view` -Quick Project Startup with Scaffolds +Quick project startup with scaffolds ==================================== So far we have done all of our *Quick Tour* as a single Python file. @@ -501,7 +501,7 @@ Let's look at ``pserve`` and configuration in more depth. :ref:`project_narr`, and :doc:`../narr/scaffolding` -Application Running with ``pserve`` +Application running with ``pserve`` =================================== Prior to scaffolds, our project mixed a number of operational details @@ -530,19 +530,19 @@ take a look at this configuration file. .. seealso:: See also: :ref:`what_is_this_pserve_thing` -Configuration with ``.ini`` Files +Configuration with ``.ini`` files ================================= Earlier in *Quick Tour* we first met Pyramid's configuration system. At that point we did all configuration in Python code. For example, the port number chosen for our HTTP server was right there in Python -code. Our scaffold has moved this decision, and more, into the +code. Our scaffold has moved this decision and more into the ``development.ini`` file: .. literalinclude:: quick_tour/package/development.ini :language: ini -Let's take a quick high-level look. First, the ``.ini`` file is divided +Let's take a quick high-level look. First the ``.ini`` file is divided into sections: - ``[app:hello_world]`` configures our WSGI app @@ -555,23 +555,21 @@ into sections: We have a few decisions made for us in this configuration: -#. *Choice of web server*. The ``use = egg:pyramid#wsgiref`` tells - ``pserve`` to use the ``wsgiref`` server that is wrapped in the Pyramid - package. +#. *Choice of web server:* ``use = egg:pyramid#wsgiref`` tells ``pserve`` to + use the ``wsgiref`` server that is wrapped in the Pyramid package. -#. *Port number*. ``port = 6543`` tells ``wsgiref`` to listen on port - 6543. +#. *Port number:* ``port = 6543`` tells ``wsgiref`` to listen on port 6543. -#. *WSGI app*. What package has our WSGI application in it? +#. *WSGI app:* What package has our WSGI application in it? ``use = egg:hello_world`` in the app section tells the configuration what application to load. -#. *Easier development by automatic template reloading*. In development - mode, you shouldn't have to restart the server when editing a Jinja2 - template. ``reload_templates = true`` sets this policy, - which might be different in production. +#. *Easier development by automatic template reloading:* In development mode, + you shouldn't have to restart the server when editing a Jinja2 template. + ``reload_templates = true`` sets this policy, which might be different in + production. -Additionally, the ``development.ini`` generated by this scaffold wired +Additionally the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well as traceback information. @@ -581,7 +579,7 @@ a log on every request that comes in, as well as traceback information. :doc:`../narr/paste` -Easier Development with ``debugtoolbar`` +Easier development with ``debugtoolbar`` ======================================== As we introduce the basics, we also want to show how to be productive in @@ -592,21 +590,21 @@ reloading and earlier we showed ``--reload`` for application reloading. several tools available in your browser. Adding it to your project illustrates several points about configuration. -First, change your ``setup.py`` to say: +First change your ``setup.py`` to say: .. literalinclude:: quick_tour/package/setup.py :start-after: Start Requires :end-before: End Requires -...and re-run your setup: +...and rerun your setup: .. code-block:: bash $ python ./setup.py develop -The Python package was now installed into our environment. The package -is a Pyramid add-on, which means we need to include its configuration -into our web application. We could do this with imperative +The Python package ``pyramid_debugtoolbar`` is now installed into our +environment. The package is a Pyramid add-on, which means we need to include +its configuration into our web application. We could do this with imperative configuration, as we did above for the ``pyramid_jinja2`` add-on: .. literalinclude:: quick_tour/package/hello_world/__init__.py @@ -635,12 +633,12 @@ configuration file. pyramid_debugtoolbar ` and :ref:`pyramid_debugtoolbar ` -Unit Tests and ``nose`` +Unit tests and ``nose`` ======================= -Yikes! We got this far and we haven't yet discussed tests. Particularly -egregious, as Pyramid has had a deep commitment to full test coverage -since before it was released. +Yikes! We got this far and we haven't yet discussed tests. This is +particularly egregious, as Pyramid has had a deep commitment to full test +coverage since before its release. Our ``pyramid_jinja2_starter`` scaffold generated a ``tests.py`` module with one unit test in it. To run it, let's install the handy ``nose`` @@ -656,7 +654,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 +We changed ``setup.py`` which means we need to rerun ``python ./setup.py develop``. We can now run all our tests: .. code-block:: bash @@ -694,7 +692,7 @@ Logging ======= It's important to know what is going on inside our web application. -In development we might need to collect some output. In production, +In development we might need to collect some output. In production we might need to detect situations when other people use the site. We need *logging*. @@ -716,7 +714,7 @@ You can now, in your code, log messages: :start-after: Start Logging 2 :end-before: End Logging 2 -This will log ``Some Message`` at a ``debug`` log level, +This will log ``Some Message`` at a ``debug`` log level to the application-configured logger in your ``development.ini``. What controls that? These sections in the configuration file: @@ -727,7 +725,7 @@ controls that? These sections in the configuration file: Our application, a package named ``hello_world``, is set up as a logger and configured to log messages at a ``DEBUG`` or higher level. When you -visit ``http://localhost:6543`` your console will now show:: +visit http://localhost:6543, your console will now show:: 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message @@ -886,8 +884,8 @@ widgets, schemas, and validation. Recent versions of Deform also include a :ref:`retail mode ` for gaining Deform features on custom forms. -Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform -widgets using attractive CSS from Bootstrap and more powerful widgets +Also the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform +widgets using attractive CSS from Twitter Bootstrap and more powerful widgets from Chosen. .. seealso:: See also: -- cgit v1.2.3 From 2ad426fdb01b445a52aebcbc879dced9ef7ba6bc Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 29 Jul 2015 11:03:49 -0400 Subject: Add a bandaid; provide correct rationale of using easy_install over pip, for now --- docs/quick_tour.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 0fc3a7ab8..be5be2e36 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -43,10 +43,14 @@ production support for Python 3 in October 2011). .. note:: - Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace - packages which, until recently, ``pip`` didn't permit. Also Pyramid has - some optional C extensions for performance. With ``easy_install``, Windows - users can get these extensions without needing a C compiler. + Why ``easy_install`` and not ``pip``? Some distributions on which Pyramid + depends upon have optional C extensions for performance. ``pip`` cannot + install some binary Python distributions. With ``easy_install``, Windows + users are able to obtain binary Python distributions, so they get the + benefit of the C extensions without needing a C compiler. Also, there can + be issues when ``pip`` and ``easy_install`` are used side-by-side in the + same environment, so we chose to recommend ``easy_install`` for the sake of + reducing the complexity of these instructions. .. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, -- cgit v1.2.3 From 91ccc4540800708e7d312fe4a988edb0a9543624 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 11 Nov 2015 18:23:54 -0800 Subject: sqla_demo/sqla_demo - update references in literalincludes --- docs/quick_tour.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index be5be2e36..87c6f1e1c 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -818,14 +818,14 @@ The ORM eases the mapping of database structures into a programming language. SQLAlchemy uses "models" for this mapping. The scaffold generated a sample model: -.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models.py +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py :start-after: Start Sphinx Include :end-before: End Sphinx Include View code, which mediates the logic between web requests and the rest of the system, can then easily get at the data thanks to SQLAlchemy: -.. literalinclude:: quick_tour/sqla_demo/sqla_demo/views.py +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/views/default.py :start-after: Start Sphinx Include :end-before: End Sphinx Include -- cgit v1.2.3 From 049e670aef9ea5611561546fd5c0e2dd6152b9b7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 11 Nov 2015 21:09:15 -0800 Subject: Revert "update wiki2/src/basiclayout/tutorial" --- docs/quick_tour.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 87c6f1e1c..be5be2e36 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -818,14 +818,14 @@ The ORM eases the mapping of database structures into a programming language. SQLAlchemy uses "models" for this mapping. The scaffold generated a sample model: -.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models.py :start-after: Start Sphinx Include :end-before: End Sphinx Include View code, which mediates the logic between web requests and the rest of the system, can then easily get at the data thanks to SQLAlchemy: -.. literalinclude:: quick_tour/sqla_demo/sqla_demo/views/default.py +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/views.py :start-after: Start Sphinx Include :end-before: End Sphinx Include -- cgit v1.2.3 From 414b67b45bab156b9738105e180908c4eee8600a Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 12 Nov 2015 12:56:27 -0600 Subject: Restore progress after backing changes out of master. This reverts commit 049e670aef9ea5611561546fd5c0e2dd6152b9b7. --- docs/quick_tour.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index be5be2e36..87c6f1e1c 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -818,14 +818,14 @@ The ORM eases the mapping of database structures into a programming language. SQLAlchemy uses "models" for this mapping. The scaffold generated a sample model: -.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models.py +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py :start-after: Start Sphinx Include :end-before: End Sphinx Include View code, which mediates the logic between web requests and the rest of the system, can then easily get at the data thanks to SQLAlchemy: -.. literalinclude:: quick_tour/sqla_demo/sqla_demo/views.py +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/views/default.py :start-after: Start Sphinx Include :end-before: End Sphinx Include -- cgit v1.2.3 From 8a80b1094cf0ba762b30a9bae56831d4daf69e3c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 5 Jan 2016 04:33:29 -0800 Subject: update links to tutorials in cookbook --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index be5be2e36..56ca53a69 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -98,7 +98,7 @@ one that we will revisit regurlarly in this *Quick Tour*. .. seealso:: See also: :ref:`Quick Tutorial Hello World `, :ref:`firstapp_chapter`, and - :ref:`Single File Tasks tutorial ` + :ref:`Todo List Application in One File ` Handling web requests and responses =================================== -- cgit v1.2.3 From 5cf8c3677454303bf4e1acecf4c16809edde2a75 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 18 Jan 2016 14:53:05 -0800 Subject: overhaul quick_tour from Quick project startup with scaffolds to Sessions with updated pyramid_jinja2 scaffold --- docs/quick_tour.rst | 319 +++++++++++++++++++++++++++------------------------- 1 file changed, 165 insertions(+), 154 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 56ca53a69..82209f623 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -457,42 +457,41 @@ have much more to offer: Quick project startup with scaffolds ==================================== -So far we have done all of our *Quick Tour* as a single Python file. -No Python packages, no structure. Most Pyramid projects, though, -aren't developed this way. +So far we have done all of our *Quick Tour* as a single Python file. No Python +packages, no structure. Most Pyramid projects, though, aren't developed this +way. -To ease the process of getting started, Pyramid provides *scaffolds* -that generate sample projects from templates in Pyramid and Pyramid -add-ons. Pyramid's ``pcreate`` command can list the available scaffolds: +To ease the process of getting started, Pyramid provides *scaffolds* that +generate sample projects from templates in Pyramid and Pyramid add-ons. +Pyramid's ``pcreate`` command can list the available scaffolds: .. code-block:: bash $ pcreate --list Available scaffolds: alchemy: Pyramid SQLAlchemy project using url dispatch - pyramid_jinja2_starter: pyramid jinja2 starter project + pyramid_jinja2_starter: Pyramid Jinja2 starter project starter: Pyramid starter project zodb: Pyramid ZODB project using traversal -The ``pyramid_jinja2`` add-on gave us a scaffold that we can use. From -the parent directory of where we want our Python package to be generated, -let's use that scaffold to make our project: +The ``pyramid_jinja2`` add-on gave us a scaffold that we can use. From the +parent directory of where we want our Python package to be generated, let's use +that scaffold to make our project: .. code-block:: bash $ pcreate --scaffold pyramid_jinja2_starter hello_world -We next use the normal Python command to set up our package for -development: +We next use the normal Python command to set up our package for development: .. code-block:: bash $ cd hello_world $ python ./setup.py develop -We are moving in the direction of a full-featured Pyramid project, -with a proper setup for Python standards (packaging) and Pyramid -configuration. This includes a new way of running your application: +We are moving in the direction of a full-featured Pyramid project, with a +proper setup for Python standards (packaging) and Pyramid configuration. This +includes a new way of running your application: .. code-block:: bash @@ -508,28 +507,27 @@ Let's look at ``pserve`` and configuration in more depth. Application running with ``pserve`` =================================== -Prior to scaffolds, our project mixed a number of operational details -into our code. Why should my main code care which HTTP server I want and -what port number to run on? +Prior to scaffolds, our project mixed a number of operational details into our +code. Why should my main code care which HTTP server I want and what port +number to run on? -``pserve`` is Pyramid's application runner, separating operational -details from your code. When you install Pyramid, a small command -program called ``pserve`` is written to your ``bin`` directory. This -program is an executable Python module. It's very small, getting most -of its brains via import. +``pserve`` is Pyramid's application runner, separating operational details from +your code. When you install Pyramid, a small command program called ``pserve`` +is written to your ``bin`` directory. This program is an executable Python +module. It's very small, getting most of its brains via import. -You can run ``pserve`` with ``--help`` to see some of its options. -Doing so reveals that you can ask ``pserve`` to watch your development -files and reload the server when they change: +You can run ``pserve`` with ``--help`` to see some of its options. Doing so +reveals that you can ask ``pserve`` to watch your development files and reload +the server when they change: .. code-block:: bash $ pserve development.ini --reload -The ``pserve`` command has a number of other options and operations. -Most of the work, though, comes from your project's wiring, as -expressed in the configuration file you supply to ``pserve``. Let's -take a look at this configuration file. +The ``pserve`` command has a number of other options and operations. Most of +the work, though, comes from your project's wiring, as expressed in the +configuration file you supply to ``pserve``. Let's take a look at this +configuration file. .. seealso:: See also: :ref:`what_is_this_pserve_thing` @@ -537,21 +535,18 @@ take a look at this configuration file. Configuration with ``.ini`` files ================================= -Earlier in *Quick Tour* we first met Pyramid's configuration system. -At that point we did all configuration in Python code. For example, -the port number chosen for our HTTP server was right there in Python -code. Our scaffold has moved this decision and more into the -``development.ini`` file: +Earlier in *Quick Tour* we first met Pyramid's configuration system. At that +point we did all configuration in Python code. For example, the port number +chosen for our HTTP server was right there in Python code. Our scaffold has +moved this decision and more into the ``development.ini`` file: .. literalinclude:: quick_tour/package/development.ini :language: ini -Let's take a quick high-level look. First the ``.ini`` file is divided -into sections: - -- ``[app:hello_world]`` configures our WSGI app +Let's take a quick high-level look. First the ``.ini`` file is divided into +sections: -- ``[pipeline:main]`` sets up our WSGI "pipeline" +- ``[app:main]`` configures our WSGI app - ``[server:main]`` holds our WSGI server settings @@ -559,23 +554,23 @@ into sections: We have a few decisions made for us in this configuration: -#. *Choice of web server:* ``use = egg:pyramid#wsgiref`` tells ``pserve`` to - use the ``wsgiref`` server that is wrapped in the Pyramid package. +#. *Choice of web server:* ``use = egg:hello_world`` tells ``pserve`` to + use the ``waitress`` server. -#. *Port number:* ``port = 6543`` tells ``wsgiref`` to listen on port 6543. +#. *Port number:* ``port = 6543`` tells ``waitress`` to listen on port 6543. #. *WSGI app:* What package has our WSGI application in it? - ``use = egg:hello_world`` in the app section tells the - configuration what application to load. + ``use = egg:hello_world`` in the app section tells the configuration what + application to load. #. *Easier development by automatic template reloading:* In development mode, you shouldn't have to restart the server when editing a Jinja2 template. - ``reload_templates = true`` sets this policy, which might be different in - production. + ``pyramid.reload_templates = true`` sets this policy, which might be + different in production. -Additionally the ``development.ini`` generated by this scaffold wired -up Python's standard logging. We'll now see in the console, for example, -a log on every request that comes in, as well as traceback information. +Additionally the ``development.ini`` generated by this scaffold wired up +Python's standard logging. We'll now see in the console, for example, a log on +every request that comes in, as well as traceback information. .. seealso:: See also: :ref:`Quick Tutorial Application Configuration `, @@ -587,76 +582,77 @@ Easier development with ``debugtoolbar`` ======================================== As we introduce the basics, we also want to show how to be productive in -development and debugging. For example, we just discussed template -reloading and earlier we showed ``--reload`` for application reloading. +development and debugging. For example, we just discussed template reloading +and earlier we showed ``--reload`` for application reloading. -``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes -several tools available in your browser. Adding it to your project -illustrates several points about configuration. +``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes several tools +available in your browser. Adding it to your project illustrates several points +about configuration. -First change your ``setup.py`` to say: +The scaffold ``pyramid_jinja2_starter`` is already configured to include the +add-on ``pyramid_debugtoolbar`` in its ``setup.py``: .. literalinclude:: quick_tour/package/setup.py - :start-after: Start Requires - :end-before: End Requires + :language: python + :linenos: + :lineno-start: 11 + :lines: 11-16 -...and rerun your setup: +It was installed when you previously ran: .. code-block:: bash $ python ./setup.py develop -The Python package ``pyramid_debugtoolbar`` is now installed into our -environment. The package is a Pyramid add-on, which means we need to include -its configuration into our web application. We could do this with imperative -configuration, as we did above for the ``pyramid_jinja2`` add-on: +The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need +to include its configuration into our web application. The ``pyramid_jinja2`` +add-on already took care of this for us in its ``__init__.py``: .. literalinclude:: quick_tour/package/hello_world/__init__.py - :start-after: Start Include - :end-before: End Include + :language: python + :linenos: + :lineno-start: 16 + :lines: 19 -Now that we have a configuration file, we can use the -``pyramid.includes`` facility and place this in our -``development.ini`` instead: +And it uses the ``pyramid.includes`` facility in our ``development.ini``: .. literalinclude:: quick_tour/package/development.ini :language: ini - :start-after: Start Includes - :end-before: End Includes - -You'll now see an attractive (and -collapsible) menu in the right of your browser, providing introspective -access to debugging information. Even better, if your web application -generates an error, you will see a nice traceback on the screen. When -you want to disable this toolbar, there's no need to change code: you can -remove it from ``pyramid.includes`` in the relevant ``.ini`` -configuration file. + :linenos: + :lineno-start: 15 + :lines: 15-16 + +You'll now see a Pyramid logo on the right side of your browser window, which +when clicked opens a new window that provides introspective access to debugging +information. Even better, if your web application generates an error, you will +see a nice traceback on the screen. When you want to disable this toolbar, +there's no need to change code: you can remove it from ``pyramid.includes`` in +the relevant ``.ini`` configuration file. .. seealso:: See also: - :ref:`Quick Tutorial - pyramid_debugtoolbar ` and + :ref:`Quick Tutorial pyramid_debugtoolbar ` and :ref:`pyramid_debugtoolbar ` Unit tests and ``nose`` ======================= -Yikes! We got this far and we haven't yet discussed tests. This is -particularly egregious, as Pyramid has had a deep commitment to full test -coverage since before its release. +Yikes! We got this far and we haven't yet discussed tests. This is particularly +egregious, as Pyramid has had a deep commitment to full test coverage since +before its release. -Our ``pyramid_jinja2_starter`` scaffold generated a ``tests.py`` module -with one unit test in it. To run it, let's install the handy ``nose`` -test runner by editing ``setup.py``. While we're at it, we'll throw in -the ``coverage`` tool which yells at us for code that isn't tested: +Our ``pyramid_jinja2_starter`` scaffold generated a ``tests.py`` module with +one unit test in it. To run it, let's install the handy ``nose`` test runner by +editing ``setup.py``. While we're at it, we'll throw in the ``coverage`` tool +which yells at us for code that isn't tested. Edit line 36 so it becomes the +following: .. code-block:: python + :linenos: + :lineno-start: 36 - setup(name='hello_world', - # Some lines removed... - extras_require={ + tests_require={ 'testing': ['nose', 'coverage'], - } - ) + }, We changed ``setup.py`` which means we need to rerun ``python ./setup.py develop``. We can now run all our tests: @@ -667,124 +663,139 @@ We changed ``setup.py`` which means we need to rerun . Name Stmts Miss Cover Missing --------------------------------------------------- - hello_world 12 8 33% 11-23 - hello_world.models 5 1 80% 8 - hello_world.tests 14 0 100% - hello_world.views 4 0 100% + hello_world 11 8 27% 11-23 + hello_world.models 5 1 80% 8 + hello_world.tests 14 0 100% + hello_world.views 4 0 100% --------------------------------------------------- - TOTAL 35 9 74% + TOTAL 34 9 74% ---------------------------------------------------------------------- - Ran 1 test in 0.931s + Ran 1 test in 0.009s OK Our unit test passed. What did our test look like? .. literalinclude:: quick_tour/package/hello_world/tests.py + :linenos: -Pyramid supplies helpers for test writing, which we use in the -test setup and teardown. Our one test imports the view, -makes a dummy request, and sees if the view returns what we expected. +Pyramid supplies helpers for test writing, which we use in the test setup and +teardown. Our one test imports the view, makes a dummy request, and sees if the +view returns what we expected. .. seealso:: See also: - :ref:`Quick Tutorial Unit Testing `, - :ref:`Quick Tutorial Functional Testing `, - and + :ref:`Quick Tutorial Unit Testing `, :ref:`Quick + Tutorial Functional Testing `, and :ref:`testing_chapter` Logging ======= -It's important to know what is going on inside our web application. -In development we might need to collect some output. In production -we might need to detect situations when other people use the site. We -need *logging*. +It's important to know what is going on inside our web application. In +development we might need to collect some output. In production we might need +to detect situations when other people use the site. We need *logging*. -Fortunately Pyramid uses the normal Python approach to logging. The -scaffold generated in your ``development.ini`` has a number of lines that -configure the logging for you to some reasonable defaults. You then see -messages sent by Pyramid (for example, when a new request comes in). +Fortunately Pyramid uses the normal Python approach to logging. The scaffold +generated in your ``development.ini`` has a number of lines that configure the +logging for you to some reasonable defaults. You then see messages sent by +Pyramid (for example, when a new request comes in). -Maybe you would like to log messages in your code? In your Python -module, import and set up the logging: +Maybe you would like to log messages in your code? In your Python module, +import and set up the logging: .. literalinclude:: quick_tour/package/hello_world/views.py - :start-after: Start Logging 1 - :end-before: End Logging 1 + :language: python + :linenos: + :lineno-start: 3 + :lines: 3-4 You can now, in your code, log messages: .. literalinclude:: quick_tour/package/hello_world/views.py - :start-after: Start Logging 2 - :end-before: End Logging 2 + :language: python + :linenos: + :lineno-start: 9 + :lines: 9-10 + :emphasize-lines: 2 -This will log ``Some Message`` at a ``debug`` log level -to the application-configured logger in your ``development.ini``. What -controls that? These sections in the configuration file: +This will log ``Some Message`` at a ``debug`` log level to the +application-configured logger in your ``development.ini``. What controls that? +These emphasized sections in the configuration file: .. literalinclude:: quick_tour/package/development.ini :language: ini - :start-after: Start Sphinx Include - :end-before: End Sphinx Include + :linenos: + :lineno-start: 36 + :lines: 36-52 + :emphasize-lines: 1-2,14-17 -Our application, a package named ``hello_world``, is set up as a logger -and configured to log messages at a ``DEBUG`` or higher level. When you -visit http://localhost:6543, your console will now show:: +Our application, a package named ``hello_world``, is set up as a logger and +configured to log messages at a ``DEBUG`` or higher level. When you visit +http://localhost:6543, your console will now show:: - 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message + 2016-01-18 13:55:55,040 DEBUG [hello_world.views:10][waitress] Some Message .. seealso:: See also: - :ref:`Quick Tutorial Logging ` and - :ref:`logging_chapter` + :ref:`Quick Tutorial Logging ` and :ref:`logging_chapter`. Sessions ======== -When people use your web application, they frequently perform a task -that requires semi-permanent data to be saved. For example, a shopping -cart. This is called a :term:`session`. +When people use your web application, they frequently perform a task that +requires semi-permanent data to be saved. For example, a shopping cart. This is +called a :term:`session`. -Pyramid has basic built-in support for sessions. Third party packages such as -``pyramid_redis_sessions`` provide richer session support. Or you can create -your own custom sessioning engine. Let's take a look at the -:doc:`built-in sessioning support <../narr/sessions>`. In our -``__init__.py`` we first import the kind of sessioning we want: +Pyramid has basic built-in support for sessions. Third party packages such as +``pyramid_redis_sessions`` provide richer session support. Or you can create +your own custom sessioning engine. Let's take a look at the :doc:`built-in +sessioning support <../narr/sessions>`. In our ``__init__.py`` we first import +the kind of sessioning we want: .. literalinclude:: quick_tour/package/hello_world/__init__.py - :start-after: Start Sphinx Include 1 - :end-before: End Sphinx Include 1 + :language: python + :linenos: + :lineno-start: 2 + :lines: 2-3 + :emphasize-lines: 2 .. warning:: - As noted in the session docs, this example implementation is - not intended for use in settings with security implications. + As noted in the session docs, this example implementation is not intended + for use in settings with security implications. Now make a "factory" and pass it to the :term:`configurator`'s ``session_factory`` argument: .. literalinclude:: quick_tour/package/hello_world/__init__.py - :start-after: Start Sphinx Include 2 - :end-before: End Sphinx Include 2 + :language: python + :linenos: + :lineno-start: 13 + :lines: 13-17 + :emphasize-lines: 3-5 -Pyramid's :term:`request` object now has a ``session`` attribute -that we can use in our view code: +Pyramid's :term:`request` object now has a ``session`` attribute that we can +use in our view code in ``views.py``: .. literalinclude:: quick_tour/package/hello_world/views.py - :start-after: Start Sphinx Include 1 - :end-before: End Sphinx Include 1 + :language: python + :linenos: + :lineno-start: 9 + :lines: 9-15 + :emphasize-lines: 3-7 -With this, each reload will increase the counter displayed in our -Jinja2 template: +We need to update our Jinja2 template to show counter increment in the session: .. literalinclude:: quick_tour/package/hello_world/templates/mytemplate.jinja2 :language: jinja - :start-after: Start Sphinx Include 1 - :end-before: End Sphinx Include 1 + :linenos: + :lineno-start: 40 + :lines: 40-42 + :emphasize-lines: 3 .. seealso:: See also: - :ref:`Quick Tutorial Sessions `, - :ref:`sessions_chapter`, :ref:`flash_messages`, - :ref:`session_module`, and :term:`pyramid_redis_sessions`. + :ref:`Quick Tutorial Sessions `, :ref:`sessions_chapter`, + :ref:`flash_messages`, :ref:`session_module`, and + :term:`pyramid_redis_sessions`. Databases ========= -- cgit v1.2.3 From 8f364675b6cd9527a482462191c18f8b3fc22d83 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 21 Jan 2016 05:09:10 -0800 Subject: minor grammar fixes. --- docs/quick_tour.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 82209f623..f5f28f86a 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -43,11 +43,11 @@ production support for Python 3 in October 2011). .. note:: - Why ``easy_install`` and not ``pip``? Some distributions on which Pyramid - depends upon have optional C extensions for performance. ``pip`` cannot + Why ``easy_install`` and not ``pip``? Some distributions upon which + Pyramid depends have optional C extensions for performance. ``pip`` cannot install some binary Python distributions. With ``easy_install``, Windows users are able to obtain binary Python distributions, so they get the - benefit of the C extensions without needing a C compiler. Also, there can + benefit of the C extensions without needing a C compiler. Also there can be issues when ``pip`` and ``easy_install`` are used side-by-side in the same environment, so we chose to recommend ``easy_install`` for the sake of reducing the complexity of these instructions. -- cgit v1.2.3 From 257ac062342d5b2cd18b47737cf9fb94aa528b8a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 22 Jan 2016 00:29:38 -0800 Subject: Overhaul Quick Tour: start to "Quick project startup with scaffolds" --- docs/quick_tour.rst | 439 +++++++++++++++++++++++++++------------------------- 1 file changed, 227 insertions(+), 212 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index f5f28f86a..220fd4bca 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -5,19 +5,20 @@ Quick Tour of Pyramid ===================== Pyramid lets you start small and finish big. This *Quick Tour* of Pyramid is -for those who want to evaluate Pyramid, whether you are new to Python -web frameworks, or a pro in a hurry. For more detailed treatment of -each topic, give the :ref:`quick_tutorial` a try. +for those who want to evaluate Pyramid, whether you are new to Python web +frameworks, or a pro in a hurry. For more detailed treatment of each topic, +give the :ref:`quick_tutorial` a try. + Installation ============ -Once you have a standard Python environment setup, getting started with -Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. -For this Quick Tour, it means: `Python `_, -a `virtual environment `_ (or -`virtualenv for Python 2.7 `_), and -`setuptools `_. +Once you have a standard Python environment setup, getting started with Pyramid +is a breeze. Unfortunately "standard" is not so simple in Python. For this +Quick Tour, it means `Python `_, a `virtual +environment `_ (or `virtualenv +for Python 2.7 `_), and `setuptools +`_. As an example, for Python 3.3+ on Linux: @@ -37,9 +38,9 @@ For Windows: c:\\> env33\\Scripts\\python ez_setup.py c:\\> env33\\Scripts\\easy_install "pyramid==\ |release|\ " -Of course Pyramid runs fine on Python 2.6+, as do the examples in this -*Quick Tour*. We're just showing Python 3 a little love (Pyramid had -production support for Python 3 in October 2011). +Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick +Tour*. We're just showing Python 3 a little love (Pyramid had production +support for Python 3 in October 2011). .. note:: @@ -54,15 +55,15 @@ production support for Python 3 in October 2011). .. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, - :ref:`installing_unix`, - :ref:`Before You Install `, and - :ref:`Installing Pyramid on a Windows System ` + :ref:`installing_unix`, :ref:`Before You Install `, and + :ref:`Installing Pyramid on a Windows System `. + Hello World =========== -Microframeworks have shown that learning starts best from a very small -first step. Here's a tiny application in Pyramid: +Microframeworks have shown that learning starts best from a very small first +step. Here's a tiny application in Pyramid: .. literalinclude:: quick_tour/hello_world/app.py :linenos: @@ -79,65 +80,63 @@ World!`` message. New to Python web programming? If so, some lines in the module merit explanation: -#. *Line 10*. The ``if __name__ == '__main__':`` is Python's way of - saying "Start here when running from the command line". +#. *Line 10*. ``if __name__ == '__main__':`` is Python's way of saying "Start + here when running from the command line". -#. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect - :term:`view` code to a particular URL :term:`route`. +#. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect :term:`view` + code to a particular URL :term:`route`. -#. *Lines 6-7*. Implement the view code that generates the - :term:`response`. +#. *Lines 6-7*. Implement the view code that generates the :term:`response`. #. *Lines 14-16*. Publish a :term:`WSGI` app using an HTTP server. -As shown in this example, the :term:`configurator` plays a central role -in Pyramid development. Building an application from loosely-coupled -parts via :doc:`../narr/configuration` is a central idea in Pyramid, -one that we will revisit regurlarly in this *Quick Tour*. +As shown in this example, the :term:`configurator` plays a central role in +Pyramid development. Building an application from loosely-coupled parts via +:doc:`../narr/configuration` is a central idea in Pyramid, one that we will +revisit regurlarly in this *Quick Tour*. .. seealso:: See also: :ref:`Quick Tutorial Hello World `, - :ref:`firstapp_chapter`, and - :ref:`Todo List Application in One File ` + :ref:`firstapp_chapter`, and :ref:`Todo List Application in One File + `. + Handling web requests and responses =================================== -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. +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, one of the first to -embrace Python 3, etc.). 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 -`. +Pyramid has always fit nicely into the existing world of Python web development +(virtual environments, packaging, scaffolding, one of the first to embrace +Python 3, etc.). 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_tour/requests/app.py :pyobject: hello_world -In this Pyramid view, we get the URL being visited from ``request.url``. Also, +In this Pyramid view, we get the URL being visited from ``request.url``. Also if you visited http://localhost:6543/?name=alice in a browser, the name is included in the body of the response:: URL http://localhost:6543/?name=alice with name: alice -Finally, we set the response's content type and return the Response. +Finally we set the response's content type, and return the Response. .. seealso:: See also: - :ref:`Quick Tutorial Request and Response ` - and - :ref:`webob_chapter` + :ref:`Quick Tutorial Request and Response ` and + :ref:`webob_chapter`. + Views ===== -For the examples above, the ``hello_world`` function is a "view". In -Pyramid, views are the primary way to accept web requests and return -responses. +For the examples above, the ``hello_world`` function is a "view". In Pyramid +views are the primary way to accept web requests and return responses. So far our examples place everything in one file: @@ -149,169 +148,169 @@ So far our examples place everything in one file: - the WSGI application launcher -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 set up -the views. +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 set up the views. -First, our revised ``app.py``: +First our revised ``app.py``: .. literalinclude:: quick_tour/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 ``config.scan('views')``. +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 ``config.scan('views')``. -We now have a ``views.py`` module that is focused on handling requests -and responses: +We now have a ``views.py`` module that is focused on handling requests and +responses: .. literalinclude:: quick_tour/views/views.py :linenos: We have four views, each leading to the other. If you start at -http://localhost:6543/, you get a response with a link to the next -view. The ``hello_view`` (available at the URL ``/howdy``) has a link -to the ``redirect_view``, which issues a redirect to the final -view. - -Earlier we saw ``config.add_view`` as one way to configure a view. This -section introduces ``@view_config``. 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. Both approaches result in the same final -configuration, thus usually it is simply a matter of taste. +http://localhost:6543/, you get a response with a link to the next view. The +``hello_view`` (available at the URL ``/howdy``) has a link to the +``redirect_view``, which issues a redirect to the final view. + +Earlier we saw ``config.add_view`` as one way to configure a view. This section +introduces ``@view_config``. 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. Both approaches result +in the same final configuration, thus usually it is simply a matter of taste. .. seealso:: See also: - :ref:`Quick Tutorial Views `, - :doc:`../narr/views`, - :doc:`../narr/viewconfig`, and - :ref:`debugging_view_configuration` + :ref:`Quick Tutorial Views `, :doc:`../narr/views`, + :doc:`../narr/viewconfig`, and :ref:`debugging_view_configuration`. + Routing ======= -Writing web applications usually means sophisticated URL design. We -just saw some Pyramid machinery for requests and views. Let's look at -features that help in routing. +Writing web applications usually means sophisticated URL design. We just saw +some Pyramid machinery for requests and views. Let's look at features that help +with routing. Above we saw the basics of routing URLs to views in Pyramid: -- Your project's "setup" code registers a route name to be used when - matching part of the URL +- Your project's "setup" code registers a route name to be used when matching + part of the URL. -- Elsewhere a view is configured to be called for that route name +- Elsewhere a view is configured to be called for that route name. .. note:: - Why do this twice? Other Python web frameworks let you create a - route and associate it with a view in one step. As - illustrated in :ref:`routes_need_ordering`, multiple routes might - match the same URL pattern. Rather than provide ways to help guess, - Pyramid lets you be explicit in ordering. Pyramid also gives - facilities to avoid the problem. + Why do this twice? Other Python web frameworks let you create a route and + associate it with a view in one step. As illustrated in + :ref:`routes_need_ordering`, multiple routes might match the same URL + pattern. Rather than provide ways to help guess, Pyramid lets you be + explicit in ordering. Pyramid also gives facilities to avoid the problem. -What if we want part of the URL to be available as data in my view? This -route declaration: +What if we want part of the URL to be available as data in my view? We can use +this route declaration, for example: .. literalinclude:: quick_tour/routing/app.py - :start-after: Start Route 1 - :end-before: End Route 1 + :linenos: + :lines: 6 + :lineno-start: 6 -With this, URLs such as ``/howdy/amy/smith`` will assign ``amy`` to -``first`` and ``smith`` to ``last``. We can then use this data in our -view: +With this, URLs such as ``/howdy/amy/smith`` will assign ``amy`` to ``first`` +and ``smith`` to ``last``. We can then use this data in our view: .. literalinclude:: quick_tour/routing/views.py - :start-after: Start Route 1 - :end-before: End Route 1 + :linenos: + :lines: 5-8 + :lineno-start: 5 + :emphasize-lines: 3 -``request.matchdict`` contains values from the URL that match the -"replacement patterns" (the curly braces) in the route declaration. -This information can then be used in your view. +``request.matchdict`` contains values from the URL that match the "replacement +patterns" (the curly braces) in the route declaration. This information can +then be used in your view. .. seealso:: See also: - :ref:`Quick Tutorial Routing `, - :doc:`../narr/urldispatch`, - :ref:`debug_routematch_section`, and - :doc:`../narr/router` + :ref:`Quick Tutorial Routing `, :doc:`../narr/urldispatch`, + :ref:`debug_routematch_section`, and :doc:`../narr/router`. + Templating ========== -Ouch. We have been making our own ``Response`` and filling the response -body with HTML. You usually won't embed an HTML string directly in -Python, but instead, will use a templating language. +Ouch. We have been making our own ``Response`` and filling the response body +with HTML. You usually won't embed an HTML string directly in Python, but +instead you will use a templating language. -Pyramid doesn't mandate a particular database system, form library, -etc. It encourages replaceability. This applies equally to templating, -which is fortunate: developers have strong views about template -languages. That said, the Pylons Project officially supports bindings for -Chameleon, Jinja2, and Mako, so in this step, let's use Chameleon. +Pyramid doesn't mandate a particular database system, form library, and so on. +It encourages replaceability. This applies equally to templating, which is +fortunate: developers have strong views about template languages. That said, +the Pylons Project officially supports bindings for Chameleon, Jinja2, and +Mako. In this step let's use Chameleon. Let's add ``pyramid_chameleon``, a Pyramid :term:`add-on` which enables -Chameleon as a :term:`renderer` in our Pyramid applications: +Chameleon as a :term:`renderer` in our Pyramid application: .. code-block:: bash $ easy_install pyramid_chameleon -With the package installed, we can include the template bindings into -our configuration: +With the package installed, we can include the template bindings into our +configuration in ``app.py``: -.. code-block:: python +.. literalinclude:: quick_tour/templating/app.py + :linenos: + :lines: 6-8 + :lineno-start: 6 + :emphasize-lines: 2 - config.include('pyramid_chameleon') - -Now lets change our views.py file: +Now lets change our ``views.py`` file: .. literalinclude:: quick_tour/templating/views.py - :start-after: Start View 1 - :end-before: End View 1 + :linenos: + :emphasize-lines: 4,6 -Ahh, that looks better. We have a view that is focused on Python code. -Our ``@view_config`` decorator specifies a :term:`renderer` that points -to our template file. Our view then simply returns data which is then -supplied to our template: +Ahh, that looks better. We have a view that is focused on Python code. Our +``@view_config`` decorator specifies a :term:`renderer` that points to our +template file. Our view then simply returns data which is then supplied to our +template ``hello_world.pt``: .. literalinclude:: quick_tour/templating/hello_world.pt :language: html -Since our view returned ``dict(name=request.matchdict['name'])``, -we can use ``name`` as a variable in our template via -``${name}``. +Since our view returned ``dict(name=request.matchdict['name'])``, we can use +``name`` as a variable in our template via ``${name}``. .. seealso:: See also: :ref:`Quick Tutorial Templating `, - :doc:`../narr/templates`, - :ref:`debugging_templates`, and - :ref:`available_template_system_bindings` + :doc:`../narr/templates`, :ref:`debugging_templates`, and + :ref:`available_template_system_bindings`. -Templating with ``jinja2`` -========================== -We just said Pyramid doesn't prefer one templating language over -another. Time to prove it. Jinja2 is a popular templating system, -modeled after Django's templates. Let's add ``pyramid_jinja2``, -a Pyramid :term:`add-on` which enables Jinja2 as a :term:`renderer` in -our Pyramid applications: +Templating with Jinja2 +====================== + +We just said Pyramid doesn't prefer one templating language over another. Time +to prove it. Jinja2 is a popular templating system, modeled after Django's +templates. Let's add ``pyramid_jinja2``, a Pyramid :term:`add-on` which enables +Jinja2 as a :term:`renderer` in our Pyramid applications: .. code-block:: bash $ easy_install pyramid_jinja2 -With the package installed, we can include the template bindings into -our configuration: - -.. code-block:: python +With the package installed, we can include the template bindings into our +configuration: - config.include('pyramid_jinja2') +.. literalinclude:: quick_tour/jinja2/app.py + :linenos: + :lines: 6-8 + :lineno-start: 6 + :emphasize-lines: 2 The only change in our view is to point the renderer at the ``.jinja2`` file: .. literalinclude:: quick_tour/jinja2/views.py - :start-after: Start View 1 - :end-before: End View 1 + :linenos: + :lines: 4-6 + :lineno-start: 4 + :emphasize-lines: 1 Our Jinja2 template is very similar to our previous template: @@ -319,54 +318,60 @@ Our Jinja2 template is very similar to our previous template: :language: html Pyramid's templating add-ons register a new kind of renderer into your -application. The renderer registration maps to different kinds of -filename extensions. In this case, changing the extension from ``.pt`` -to ``.jinja2`` passed the view response through the ``pyramid_jinja2`` -renderer. +application. The renderer registration maps to different kinds of filename +extensions. In this case, changing the extension from ``.pt`` to ``.jinja2`` +passed the view response through the ``pyramid_jinja2`` renderer. .. seealso:: See also: - :ref:`Quick Tutorial Jinja2 `, - `Jinja2 homepage `_, and - :ref:`pyramid_jinja2 Overview ` + :ref:`Quick Tutorial Jinja2 `, `Jinja2 homepage + `_, and :ref:`pyramid_jinja2 Overview + `. + Static assets ============= -Of course the Web is more than just markup. You need static assets: -CSS, JS, and images. Let's point our web app at a directory where -Pyramid will serve some static assets. First another call to the +Of course the Web is more than just markup. You need static assets: CSS, JS, +and images. Let's point our web app at a directory from which Pyramid will +serve some static assets. First let's make another call to the :term:`configurator`: .. literalinclude:: quick_tour/static_assets/app.py - :start-after: Start Static 1 - :end-before: End Static 1 + :linenos: + :lines: 6-8 + :lineno-start: 6 + :emphasize-lines: 2 This tells our WSGI application to map requests under -http://localhost:6543/static/ to files and directories inside a -``static`` directory alongside our Python module. +http://localhost:6543/static/ to files and directories inside a ``static`` +directory alongside our Python module. Next make a directory named ``static``, and place ``app.css`` inside: .. literalinclude:: quick_tour/static_assets/static/app.css :language: css -All we need to do now is point to it in the ```` of our Jinja2 -template: +All we need to do now is point to it in the ```` of our Jinja2 template, +``hello_world.jinja2``: -.. literalinclude:: quick_tour/static_assets/hello_world.pt - :language: html - :start-after: Start Link 1 - :end-before: End Link 1 +.. literalinclude:: quick_tour/static_assets/hello_world.jinja2 + :language: jinja + :linenos: + :lines: 4-6 + :lineno-start: 4 + :emphasize-lines: 2 -This link presumes that our CSS is at a URL starting with ``/static/``. -What if the site is later moved under ``/somesite/static/``? Or perhaps -a web developer changes the arrangement on disk? Pyramid provides a helper -to allow flexibility on URL generation: +This link presumes that our CSS is at a URL starting with ``/static/``. What if +the site is later moved under ``/somesite/static/``? Or perhaps a web developer +changes the arrangement on disk? Pyramid provides a helper to allow flexibility +on URL generation: -.. literalinclude:: quick_tour/static_assets/hello_world.pt - :language: html - :start-after: Start Link 2 - :end-before: End Link 2 +.. literalinclude:: quick_tour/static_assets/hello_world_static.jinja2 + :language: jinja + :linenos: + :lines: 4-6 + :lineno-start: 4 + :emphasize-lines: 2 By using ``request.static_url`` to generate the full URL to the static assets, you both ensure you stay in sync with the configuration and @@ -374,38 +379,48 @@ gain refactoring flexibility later. .. seealso:: See also: :ref:`Quick Tutorial Static Assets `, - :doc:`../narr/assets`, - :ref:`preventing_http_caching`, and - :ref:`influencing_http_caching` + :doc:`../narr/assets`, :ref:`preventing_http_caching`, and + :ref:`influencing_http_caching`. + Returning JSON ============== -Modern web apps are more than rendered HTML. Dynamic pages now use -JavaScript to update the UI in the browser by requesting server data as -JSON. Pyramid supports this with a JSON renderer: +Modern web apps are more than rendered HTML. Dynamic pages now use JavaScript +to update the UI in the browser by requesting server data as JSON. Pyramid +supports this with a JSON renderer: .. literalinclude:: quick_tour/json/views.py - :start-after: Start View 1 - :end-before: End View 2 + :linenos: + :lines: 9- + :lineno-start: 9 + +This wires up a view that returns some data through the JSON :term:`renderer`, +which calls Python's JSON support to serialize the data into JSON, and sets the +appropriate HTTP headers. + +We also need to add a route to ``app.py`` so that our app will know how to +respond to a request for ``hello.json``. -This wires up a view that returns some data through the JSON -:term:`renderer`, which calls Python's JSON support to serialize the data -into JSON and set the appropriate HTTP headers. +.. literalinclude:: quick_tour/json/app.py + :linenos: + :lines: 6-8 + :lineno-start: 6 + :emphasize-lines: 2 .. seealso:: See also: - :ref:`Quick Tutorial JSON `, - :ref:`views_which_use_a_renderer`, - :ref:`json_renderer`, and - :ref:`adding_and_overriding_renderers` + :ref:`Quick Tutorial JSON `, :ref:`views_which_use_a_renderer`, + :ref:`json_renderer`, and :ref:`adding_and_overriding_renderers`. + View classes ============ -So far our views have been simple, free-standing functions. Many times -your views are related: different ways to look at or work on the same -data, or a REST API that handles multiple operations. Grouping these -together as a :ref:`view class ` makes sense. +So far our views have been simple, free-standing functions. Many times your +views are related. They may have different ways to look at or work on the same +data, or they may be a REST API that handles multiple operations. Grouping +these together as a :ref:`view class ` makes sense and achieves +the following goals. - Group views @@ -413,46 +428,46 @@ together as a :ref:`view class ` makes sense. - Share some state and helpers -The following shows a "Hello World" example with three operations: view -a form, save a change, or press the delete button: +The following shows a "Hello World" example with three operations: view a form, +save a change, or press the delete button in our ``views.py``: .. literalinclude:: quick_tour/view_classes/views.py - :start-after: Start View 1 - :end-before: End View 1 + :linenos: + :lines: 7- + :lineno-start: 7 -As you can see, the three views are logically grouped together. -Specifically: +As you can see, the three views are logically grouped together. Specifically: -- The first view is returned when you go to ``/howdy/amy``. This URL is - mapped to the ``hello`` route that we centrally set using the optional +- The first view is returned when you go to ``/howdy/amy``. This URL is mapped + to the ``hello`` route that we centrally set using the optional ``@view_defaults``. - The second view is returned when the form data contains a field with - ``form.edit``, such as clicking on - ````. This rule - is specified in the ``@view_config`` for that view. + ``form.edit``, such as clicking on ````. This rule is specified in the ``@view_config`` for that + view. -- The third view is returned when clicking on a button such - as ````. +- The third view is returned when clicking on a button such as ````. -Only one route is needed, stated in one place atop the view class. Also, -the assignment of ``name`` is done in the ``__init__`` function. Our -templates can then use ``{{ view.name }}``. +Only one route is needed, stated in one place atop the view class. Also, the +assignment of ``name`` is done in the ``__init__`` function. Our templates can +then use ``{{ view.name }}``. -Pyramid view classes, combined with built-in and custom predicates, -have much more to offer: +Pyramid view classes, combined with built-in and custom predicates, have much +more to offer: - All the same view configuration parameters as function views -- One route leading to multiple views, based on information in the - request or data such as ``request_param``, ``request_method``, - ``accept``, ``header``, ``xhr``, ``containment``, and - ``custom_predicates`` +- One route leading to multiple views, based on information in the request or + data such as ``request_param``, ``request_method``, ``accept``, ``header``, + ``xhr``, ``containment``, and ``custom_predicates`` .. seealso:: See also: - :ref:`Quick Tutorial View Classes `, - :ref:`Quick Tutorial More View Classes `, and - :ref:`class_as_view` + :ref:`Quick Tutorial View Classes `, :ref:`Quick + Tutorial More View Classes `, and + :ref:`class_as_view`. + Quick project startup with scaffolds ==================================== -- cgit v1.2.3 From 6a936654276b83ccd379c739e3c39d5a25457ab3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 23 Jan 2016 05:04:45 -0800 Subject: Complete overhaul of Quick Tour - Databases and Forms --- docs/quick_tour.rst | 92 ++++++++++++++++++++++++++--------------------------- 1 file changed, 46 insertions(+), 46 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 220fd4bca..a7c184776 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -812,17 +812,16 @@ We need to update our Jinja2 template to show counter increment in the session: :ref:`flash_messages`, :ref:`session_module`, and :term:`pyramid_redis_sessions`. + Databases ========= -Web applications mean data. Data means databases. Frequently SQL -databases. SQL databases frequently mean an "ORM" -(object-relational mapper.) In Python, ORM usually leads to the -mega-quality *SQLAlchemy*, a Python package that greatly eases working -with databases. +Web applications mean data. Data means databases. Frequently SQL databases. SQL +databases frequently mean an "ORM" (object-relational mapper.) In Python, ORM +usually leads to the mega-quality *SQLAlchemy*, a Python package that greatly +eases working with databases. -Pyramid and SQLAlchemy are great friends. That friendship includes a -scaffold! +Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold! .. code-block:: bash @@ -830,50 +829,53 @@ scaffold! $ cd sqla_demo $ python setup.py develop -We now have a working sample SQLAlchemy application with all -dependencies installed. The sample project provides a console script to -initialize a SQLite database with tables. Let's run it and then start -the application: +We now have a working sample SQLAlchemy application with all dependencies +installed. The sample project provides a console script to initialize a SQLite +database with tables. Let's run it, then start the application: .. code-block:: bash $ initialize_sqla_demo_db development.ini $ pserve development.ini -The ORM eases the mapping of database structures into a programming -language. SQLAlchemy uses "models" for this mapping. The scaffold -generated a sample model: +The ORM eases the mapping of database structures into a programming language. +SQLAlchemy uses "models" for this mapping. The scaffold generated a sample +model: .. literalinclude:: quick_tour/sqla_demo/sqla_demo/models.py - :start-after: Start Sphinx Include - :end-before: End Sphinx Include + :language: python + :linenos: + :lineno-start: 21 + :lines: 21- -View code, which mediates the logic between web requests and the rest -of the system, can then easily get at the data thanks to SQLAlchemy: +View code, which mediates the logic between web requests and the rest of the +system, can then easily get at the data thanks to SQLAlchemy: .. literalinclude:: quick_tour/sqla_demo/sqla_demo/views.py - :start-after: Start Sphinx Include - :end-before: End Sphinx Include + :language: python + :linenos: + :lineno-start: 12 + :lines: 12-18 + :emphasize-lines: 4 .. seealso:: See also: - :ref:`Quick Tutorial Databases `, - `SQLAlchemy `_, - :ref:`making_a_console_script`, - :ref:`bfg_sql_wiki_tutorial`, and - :ref:`Application Transactions With pyramid_tm ` + :ref:`Quick Tutorial Databases `, `SQLAlchemy + `_, :ref:`making_a_console_script`, + :ref:`bfg_sql_wiki_tutorial`, and :ref:`Application Transactions with + pyramid_tm `. + Forms ===== -Developers have lots of opinions about web forms, and thus there are many -form libraries for Python. Pyramid doesn't directly bundle a form -library, but *Deform* is a popular choice for forms, -along with its related *Colander* schema system. +Developers have lots of opinions about web forms, thus there are many form +libraries for Python. Pyramid doesn't directly bundle a form library, but +*Deform* is a popular choice for forms, along with its related *Colander* +schema system. -As an example, imagine we want a form that edits a wiki page. The form -should have two fields on it, one of them a required title and the -other a rich text editor for the body. With Deform we can express this -as a Colander schema: +As an example, imagine we want a form that edits a wiki page. The form should +have two fields on it, one of them a required title and the other a rich text +editor for the body. With Deform we can express this as a Colander schema: .. code-block:: python @@ -884,8 +886,8 @@ as a Colander schema: widget=deform.widget.RichTextWidget() ) -With this in place, we can render the HTML for a form, -perhaps with form data from an existing page: +With this in place, we can render the HTML for a form, perhaps with form data +from an existing page: .. code-block:: python @@ -909,20 +911,18 @@ We'd like to handle form submission, validation, and saving: page['title'] = appstruct['title'] page['body'] = appstruct['body'] -Deform and Colander provide a very flexible combination for forms, -widgets, schemas, and validation. Recent versions of Deform also -include a :ref:`retail mode ` for gaining Deform -features on custom forms. +Deform and Colander provide a very flexible combination for forms, widgets, +schemas, and validation. Recent versions of Deform also include a :ref:`retail +mode ` for gaining Deform features on custom forms. -Also the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform -widgets using attractive CSS from Twitter Bootstrap and more powerful widgets -from Chosen. +Also the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets +using attractive CSS from Twitter Bootstrap and more powerful widgets from +Chosen. .. seealso:: See also: - :ref:`Quick Tutorial Forms `, - :ref:`Deform `, - :ref:`Colander `, and - `deform_bootstrap `_ + :ref:`Quick Tutorial Forms `, :ref:`Deform `, + :ref:`Colander `, and `deform_bootstrap + `_. Conclusion ========== -- cgit v1.2.3 From 5562586cd45b994325fce4893dc0f74580eccdea Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 31 Mar 2016 02:24:43 -0700 Subject: - update links to PyPA site as practical - update various easy_install/setup.py commands to use pip - update to use py35 - other small improvements --- docs/quick_tour.rst | 53 +++++++++++++++++++++++++---------------------------- 1 file changed, 25 insertions(+), 28 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 65310bf4d..3554fc724 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -15,28 +15,29 @@ Installation Once you have a standard Python environment setup, getting started with Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. For this -Quick Tour, it means `Python `_, a `virtual -environment `_ (or `virtualenv -for Python 2.7 `_), and `setuptools -`_. +Quick Tour, it means `Python `_, `venv +`_ (or `virtualenv for +Python 2.7 `_), +`pip `_, and `setuptools +`_. -As an example, for Python 3.3+ on Linux: +As an example, for Python 3.5+ on Linux: .. parsed-literal:: - $ pyvenv env33 - $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | env33/bin/python - $ env33/bin/easy_install "pyramid==\ |release|\ " + $ pyvenv env35 + $ env35/bin/pip install pyramid + # or for a specific released version + $ env35/bin/pip install "pyramid==\ |release|\ " For Windows: .. parsed-literal:: - # Use your browser to download: - # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py - c:\\> c:\\Python33\\python -m venv env33 - c:\\> env33\\Scripts\\python ez_setup.py - c:\\> env33\\Scripts\\easy_install "pyramid==\ |release|\ " + c:\\> c:\\Python35\\python -m venv env35 + c:\\> env35\\Scripts\\pip install pyramid + # or for a specific released version + c:\\> env35\\Scripts\\pip install "pyramid==\ |release|\ " Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had production @@ -44,14 +45,8 @@ support for Python 3 in October 2011). .. note:: - Why ``easy_install`` and not ``pip``? Some distributions upon which - Pyramid depends have optional C extensions for performance. ``pip`` cannot - install some binary Python distributions. With ``easy_install``, Windows - users are able to obtain binary Python distributions, so they get the - benefit of the C extensions without needing a C compiler. Also there can - be issues when ``pip`` and ``easy_install`` are used side-by-side in the - same environment, so we chose to recommend ``easy_install`` for the sake of - reducing the complexity of these instructions. + If you use Python 2.6 or 2.7, then you might need to install + ``setuptools``. See references below for more information. .. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, @@ -249,7 +244,7 @@ Chameleon as a :term:`renderer` in our Pyramid application: .. code-block:: bash - $ easy_install pyramid_chameleon + $ env35/bin/pip install pyramid_chameleon With the package installed, we can include the template bindings into our configuration in ``app.py``: @@ -293,7 +288,7 @@ Jinja2 as a :term:`renderer` in our Pyramid applications: .. code-block:: bash - $ easy_install pyramid_jinja2 + $ env35/bin/pip install pyramid_jinja2 With the package installed, we can include the template bindings into our configuration: @@ -502,7 +497,7 @@ We next use the normal Python command to set up our package for development: .. code-block:: bash $ cd hello_world - $ python ./setup.py develop + $ $VENV/bin/pip install -e . We are moving in the direction of a full-featured Pyramid project, with a proper setup for Python standards (packaging) and Pyramid configuration. This @@ -617,7 +612,7 @@ It was installed when you previously ran: .. code-block:: bash - $ python ./setup.py develop + $ $VENV/bin/pip install -e . The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need to include its configuration into our web application. The ``pyramid_jinja2`` @@ -670,7 +665,7 @@ following: }, We changed ``setup.py`` which means we need to rerun -``python ./setup.py develop``. We can now run all our tests: +``$VENV/bin/pip install -e .``. We can now run all our tests: .. code-block:: bash @@ -746,7 +741,9 @@ These emphasized sections in the configuration file: Our application, a package named ``hello_world``, is set up as a logger and configured to log messages at a ``DEBUG`` or higher level. When you visit -http://localhost:6543, your console will now show:: +http://localhost:6543, your console will now show: + +.. code-block:: text 2016-01-18 13:55:55,040 DEBUG [hello_world.views:10][waitress] Some Message @@ -827,7 +824,7 @@ Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold! $ pcreate --scaffold alchemy sqla_demo $ cd sqla_demo - $ python setup.py develop + $ $VENV/bin/pip install -e . We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a console script to initialize a SQLite -- cgit v1.2.3 From e4995d86ce6570dcfea440cafc92aecc40c421ad Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 31 Mar 2016 02:28:14 -0700 Subject: - change env35 to just env. --- docs/quick_tour.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 3554fc724..067395218 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -25,19 +25,19 @@ As an example, for Python 3.5+ on Linux: .. parsed-literal:: - $ pyvenv env35 - $ env35/bin/pip install pyramid + $ pyvenv env + $ env/bin/pip install pyramid # or for a specific released version - $ env35/bin/pip install "pyramid==\ |release|\ " + $ env/bin/pip install "pyramid==\ |release|\ " For Windows: .. parsed-literal:: - c:\\> c:\\Python35\\python -m venv env35 - c:\\> env35\\Scripts\\pip install pyramid + c:\\> c:\\Python35\\python -m venv env + c:\\> env\\Scripts\\pip install pyramid # or for a specific released version - c:\\> env35\\Scripts\\pip install "pyramid==\ |release|\ " + c:\\> env\\Scripts\\pip install "pyramid==\ |release|\ " Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had production @@ -244,7 +244,7 @@ Chameleon as a :term:`renderer` in our Pyramid application: .. code-block:: bash - $ env35/bin/pip install pyramid_chameleon + $ env/bin/pip install pyramid_chameleon With the package installed, we can include the template bindings into our configuration in ``app.py``: @@ -288,7 +288,7 @@ Jinja2 as a :term:`renderer` in our Pyramid applications: .. code-block:: bash - $ env35/bin/pip install pyramid_jinja2 + $ env/bin/pip install pyramid_jinja2 With the package installed, we can include the template bindings into our configuration: -- cgit v1.2.3 From 7725b8ca96ae63f0767145aa192e3d5a67da4a1b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 31 Mar 2016 02:29:40 -0700 Subject: - change $VENV to just env. --- docs/quick_tour.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 067395218..32f049d6a 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -497,7 +497,7 @@ We next use the normal Python command to set up our package for development: .. code-block:: bash $ cd hello_world - $ $VENV/bin/pip install -e . + $ env/bin/pip install -e . We are moving in the direction of a full-featured Pyramid project, with a proper setup for Python standards (packaging) and Pyramid configuration. This @@ -612,7 +612,7 @@ It was installed when you previously ran: .. code-block:: bash - $ $VENV/bin/pip install -e . + $ env/bin/pip install -e . The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need to include its configuration into our web application. The ``pyramid_jinja2`` @@ -665,7 +665,7 @@ following: }, We changed ``setup.py`` which means we need to rerun -``$VENV/bin/pip install -e .``. We can now run all our tests: +``env/bin/pip install -e .``. We can now run all our tests: .. code-block:: bash @@ -824,7 +824,7 @@ Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold! $ pcreate --scaffold alchemy sqla_demo $ cd sqla_demo - $ $VENV/bin/pip install -e . + $ env/bin/pip install -e . We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a console script to initialize a SQLite -- cgit v1.2.3 From f1eb47f14aea0e9a1dde39ed08a9bf6728614cbf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Apr 2016 02:05:22 -0700 Subject: remove note to install setuptools --- docs/quick_tour.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 32f049d6a..f1cec97e9 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -43,11 +43,6 @@ Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had production support for Python 3 in October 2011). -.. note:: - - If you use Python 2.6 or 2.7, then you might need to install - ``setuptools``. See references below for more information. - .. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, :ref:`installing_unix`, :ref:`Before You Install `, and -- cgit v1.2.3 From d603697517d56a1e2f2a5707ebba922db24f5c71 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 02:47:57 -0700 Subject: - replace `pyvenv` with `python3 -m venv` --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index f1cec97e9..04b70bcd1 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -25,7 +25,7 @@ As an example, for Python 3.5+ on Linux: .. parsed-literal:: - $ pyvenv env + $ python3 -m venv env $ env/bin/pip install pyramid # or for a specific released version $ env/bin/pip install "pyramid==\ |release|\ " -- cgit v1.2.3 From b485166239091c620c96ca71369c69f6fa7a8be7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 02:51:20 -0700 Subject: - replace `python -m` with `python3 -m` --- docs/quick_tour.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 04b70bcd1..e381a9232 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -34,7 +34,7 @@ For Windows: .. parsed-literal:: - c:\\> c:\\Python35\\python -m venv env + c:\\> c:\\Python35\\python3 -m venv env c:\\> env\\Scripts\\pip install pyramid # or for a specific released version c:\\> env\\Scripts\\pip install "pyramid==\ |release|\ " -- cgit v1.2.3 From ebbe68144ad6a6022863aa4a29f5611fde02258f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 04:52:20 -0700 Subject: - use an environment variable and venv. See https://github.com/Pylons/pyramid/pull/2468#discussion_r59311019 - rename stanza from `testing_extras` to `tests_require` - switch from nose to pytest --- docs/quick_tour.rst | 138 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 92 insertions(+), 46 deletions(-) (limited to 'docs/quick_tour.rst') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index e381a9232..78af6fd40 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -21,27 +21,40 @@ Python 2.7 `_), `pip `_, and `setuptools `_. +To save a little bit of typing and to be certain that we use the modules, +scripts, and packages installed in our virtual environment, we'll set an +environment variable, too. + As an example, for Python 3.5+ on Linux: .. parsed-literal:: - $ python3 -m venv env - $ env/bin/pip install pyramid + # set an environment variable to where you want your virtual environment + $ export VENV=~/env + # create the virtual environment + $ python3 -m venv $VENV + # install pyramid + $ $VENV/bin/pip install pyramid # or for a specific released version - $ env/bin/pip install "pyramid==\ |release|\ " + $ $VENV/bin/pip install "pyramid==\ |release|\ " For Windows: .. parsed-literal:: - c:\\> c:\\Python35\\python3 -m venv env - c:\\> env\\Scripts\\pip install pyramid + # set an environment variable to where you want your virtual environment + c:\> set VENV=c:\env + # create the virtual environment + c:\\> c:\\Python35\\python3 -m venv %VENV% + # install pyramid + c:\\> %VENV%\\Scripts\\pip install pyramid # or for a specific released version - c:\\> env\\Scripts\\pip install "pyramid==\ |release|\ " + c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick -Tour*. We're just showing Python 3 a little love (Pyramid had production -support for Python 3 in October 2011). +Tour*. We're showing Python 3 for simplicity. (Pyramid had production support +for Python 3 in October 2011.) Also for simplicity, the remaining examples will +show only UNIX commands. .. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, @@ -62,7 +75,7 @@ This simple example is easy to run. Save this as ``app.py`` and run it: .. code-block:: bash - $ python ./app.py + $ $VENV/bin/python ./app.py Next open http://localhost:6543/ in a browser, and you will see the ``Hello World!`` message. @@ -111,7 +124,9 @@ Let's see some features of requests and responses in action: In this Pyramid view, we get the URL being visited from ``request.url``. Also if you visited http://localhost:6543/?name=alice in a browser, the name is -included in the body of the response:: +included in the body of the response: + +.. code-block:: text URL http://localhost:6543/?name=alice with name: alice @@ -239,7 +254,7 @@ Chameleon as a :term:`renderer` in our Pyramid application: .. code-block:: bash - $ env/bin/pip install pyramid_chameleon + $ $VENV/bin/pip install pyramid_chameleon With the package installed, we can include the template bindings into our configuration in ``app.py``: @@ -283,7 +298,7 @@ Jinja2 as a :term:`renderer` in our Pyramid applications: .. code-block:: bash - $ env/bin/pip install pyramid_jinja2 + $ $VENV/bin/pip install pyramid_jinja2 With the package installed, we can include the template bindings into our configuration: @@ -492,7 +507,7 @@ We next use the normal Python command to set up our package for development: .. code-block:: bash $ cd hello_world - $ env/bin/pip install -e . + $ $VENV/bin/pip install -e . We are moving in the direction of a full-featured Pyramid project, with a proper setup for Python standards (packaging) and Pyramid configuration. This @@ -500,7 +515,7 @@ includes a new way of running your application: .. code-block:: bash - $ pserve development.ini + $ $VENV/bin/pserve development.ini Let's look at ``pserve`` and configuration in more depth. @@ -527,7 +542,7 @@ the server when they change: .. code-block:: bash - $ pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload The ``pserve`` command has a number of other options and operations. Most of the work, though, comes from your project's wiring, as expressed in the @@ -607,7 +622,7 @@ It was installed when you previously ran: .. code-block:: bash - $ env/bin/pip install -e . + $ $VENV/bin/pip install -e . The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need to include its configuration into our web application. The ``pyramid_jinja2`` @@ -638,48 +653,79 @@ the relevant ``.ini`` configuration file. :ref:`Quick Tutorial pyramid_debugtoolbar ` and :ref:`pyramid_debugtoolbar ` -Unit tests and ``nose`` -======================= +Unit tests and ``py.test`` +========================== Yikes! We got this far and we haven't yet discussed tests. This is particularly egregious, as Pyramid has had a deep commitment to full test coverage since before its release. Our ``pyramid_jinja2_starter`` scaffold generated a ``tests.py`` module with -one unit test in it. To run it, let's install the handy ``nose`` test runner by -editing ``setup.py``. While we're at it, we'll throw in the ``coverage`` tool -which yells at us for code that isn't tested. Edit line 36 so it becomes the -following: +one unit test in it. To run it, let's install the handy ``pytest`` test runner +by editing ``setup.py``. While we're at it, we'll throw in the ``pytest-cov`` +tool which yells at us for code that isn't tested. Insert and edit the +following lines as shown: .. code-block:: python :linenos: - :lineno-start: 36 + :lineno-start: 11 + :emphasize-lines: 8-12 + + requires = [ + 'pyramid', + 'pyramid_jinja2', + 'pyramid_debugtoolbar', + 'waitress', + ] - tests_require={ - 'testing': ['nose', 'coverage'], - }, + tests_require = [ + 'WebTest >= 1.3.1', # py3 compat + 'pytest', # includes virtualenv + 'pytest-cov', + ] -We changed ``setup.py`` which means we need to rerun -``env/bin/pip install -e .``. We can now run all our tests: +.. code-block:: python + :linenos: + :lineno-start: 34 + :emphasize-lines: 2-4 + + zip_safe=False, + extras_require={ + 'testing': tests_require, + }, + +We changed ``setup.py`` which means we need to rerun ``$VENV/bin/pip install -e +".[testing]"``. We can now run all our tests: .. code-block:: bash - $ nosetests hello_world/tests.py - . - Name Stmts Miss Cover Missing - --------------------------------------------------- - hello_world 11 8 27% 11-23 - hello_world.models 5 1 80% 8 - hello_world.tests 14 0 100% - hello_world.views 4 0 100% - --------------------------------------------------- - TOTAL 34 9 74% - ---------------------------------------------------------------------- - Ran 1 test in 0.009s + $ $VENV/bin/py.test --cov=hello_world --cov-report=term-missing hello_world/tests.py + +This yields the following output. + +.. code-block:: text + + =========================== test session starts =========================== + platform darwin -- Python 3.5.0, pytest-2.9.1, py-1.4.31, pluggy-0.3.1 + rootdir: /Users/stevepiercy/projects/hack-on-pyramid/hello_world, inifile: + plugins: cov-2.2.1 + collected 1 items + + hello_world/tests.py . + ------------- coverage: platform darwin, python 3.5.0-final-0 ------------- + Name Stmts Miss Cover Missing + -------------------------------------------------------- + hello_world/__init__.py 11 8 27% 11-23 + hello_world/resources.py 5 1 80% 8 + hello_world/tests.py 14 0 100% + hello_world/views.py 4 0 100% + -------------------------------------------------------- + TOTAL 34 9 74% - OK + ========================= 1 passed in 0.22 seconds ========================= -Our unit test passed. What did our test look like? +Our unit test passed, although its coverage is incomplete. What did our test +look like? .. literalinclude:: quick_tour/package/hello_world/tests.py :linenos: @@ -817,9 +863,9 @@ Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold! .. code-block:: bash - $ pcreate --scaffold alchemy sqla_demo + $ $VENV/bin/pcreate --scaffold alchemy sqla_demo $ cd sqla_demo - $ env/bin/pip install -e . + $ $VENV/bin/pip install -e . We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a console script to initialize a SQLite @@ -827,8 +873,8 @@ database with tables. Let's run it, then start the application: .. code-block:: bash - $ initialize_sqla_demo_db development.ini - $ pserve development.ini + $ $VENV/bin/initialize_sqla_demo_db development.ini + $ $VENV/bin/pserve development.ini The ORM eases the mapping of database structures into a programming language. SQLAlchemy uses "models" for this mapping. The scaffold generated a sample -- cgit v1.2.3