From e4e3aa3449d3ae390402a9cead205626816a2938 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 27 Dec 2009 15:32:14 +0000 Subject: Rendering cleanups. --- .../MyProject/myproject/templates/mytemplate.pt | 3 +- docs/narr/configuration.rst | 6 +- docs/narr/install.rst | 4 -- docs/narr/introduction.rst | 25 ++++--- docs/narr/project.rst | 53 ++++++-------- docs/narr/scanning.rst | 1 - docs/narr/startup.rst | 2 +- docs/narr/traversal.rst | 6 +- docs/narr/urldispatch.rst | 82 ++++++++++++++-------- docs/narr/urlmapping.rst | 16 +++-- docs/narr/views.rst | 21 ++++-- docs/narr/webob.rst | 12 ++-- 12 files changed, 122 insertions(+), 109 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt index b94cb7098..72e4fec9d 100644 --- a/docs/narr/MyProject/myproject/templates/mytemplate.pt +++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt @@ -1,4 +1,5 @@ - + diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 73027e4c2..738295842 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -766,9 +766,9 @@ configuration` it creates. Since the relative ordering of calls to :meth:`repoze.bfg.configuration.Configurator.add_view` doesn't matter -(see the sidebar above entitled *View Dispatch and Ordering*), the -relative order of ```` tags in ZCML doesn't matter either. The -following ZCML orderings are completely equivalent: +(see the sidebar entitled *View Dispatch and Ordering*), the relative +order of ```` tags in ZCML doesn't matter either. The following +ZCML orderings are completely equivalent: .. topic:: Hello Before Goodbye diff --git a/docs/narr/install.rst b/docs/narr/install.rst index e4eb284f9..4fa0ef1d8 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -84,7 +84,6 @@ same system, to install a Python 2.5 interpreter from *source*, use the following commands: .. code-block:: text - :linenos: [chrism@vitaminf ~]$ cd ~ [chrism@vitaminf ~]$ mkdir tmp @@ -128,7 +127,6 @@ setuptools`` within the Python interpreter you'd like to run :mod:`repoze.bfg` under: .. code-block:: text - :linenos: [chrism@vitaminf bfg]$ python Python 2.4.5 (#1, Aug 29 2008, 12:27:37) @@ -195,7 +193,6 @@ can actually create a virtual environment. To do so, invoke the following: .. code-block:: text - :linenos: $ virtualenv --no-site-packages bfgenv New python executable in bfgenv/bin/python @@ -225,7 +222,6 @@ After you've got your ``bfgenv`` virtualenv installed, you may install virtualenv (``bfgenv``) directory: .. code-block:: text - :linenos: $ bin/easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 09b690a12..6b5494d76 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -117,19 +117,18 @@ Differences from Other Web Frameworks ------------------------------------- Like :term:`Zope`, the :mod:`repoze.bfg` framework imposes more -`control inversion `_ upon -application developers than other Python frameworks such as -:term:`Pylons`. For example :mod:`repoze.bfg` allows you to -explicitly resolve a URL to a :term:`context` object before invoking a -:term:`view`. Pylons and other Python "MVC" frameworks have no such -intermediate step; they resolve a URL directly to a "controller". -Another example: using the :mod:`repoze.bfg` security subsystem -assumes that you're willing to attach an :term:`ACL` to a -:term:`context` object; the ACL is checked by the framework itself -instead of by user code, and access is permitted or denied by the -framework itself rather than by user code. Such a task would -typically be performed by user-space decorators in other Python web -frameworks. +*control inversion* upon application developers than other Python +frameworks such as :term:`Pylons`. For example :mod:`repoze.bfg` +allows you to explicitly resolve a URL to a :term:`context` object +before invoking a :term:`view`. Pylons and other Python "MVC" +frameworks have no such intermediate step; they resolve a URL directly +to a "controller". Another example: using the :mod:`repoze.bfg` +security subsystem assumes that you're willing to attach an +:term:`ACL` to a :term:`context` object; the ACL is checked by the +framework itself instead of by user code, and access is permitted or +denied by the framework itself rather than by user code. Such a task +would typically be performed by user-space decorators in other Python +web frameworks. Like Zope, but unlike :term:`Pylons` applications or most :term:`Django` applications, when you build a :mod:`repoze.bfg` diff --git a/docs/narr/project.rst b/docs/narr/project.rst index fd0ab27a1..2fe5489e2 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -29,8 +29,7 @@ To start a :mod:`repoze.bfg` :term:`project`, use the ``paster create`` facility using the interpreter from the virtualenv (``bfgenv``) directory you created in :ref:`installing_chapter`. -.. code-block:: bash - :linenos: +.. code-block:: text $ bin/paster create -t bfg_starter @@ -39,8 +38,7 @@ project. You should use a string without spaces and with only letters in it. Here's sample output from a run of ``paster create`` for a project we name ``MyProject``: -.. code-block:: bash - :linenos: +.. code-block:: text $ bin/paster create -t bfg_starter Selected and implied templates: @@ -128,15 +126,13 @@ the project directory. The file named ``setup.py`` will be in the root of the paster-generated project directory. The ``python`` you're invoking should be the one from your virtualenv. -.. code-block:: bash - :linenos: +.. code-block:: text $ ../bin/python setup.py develop Elided output from a run of this command is shown below: -.. code-block:: bash - :linenos: +.. code-block:: text $ ../bin/python setup.py develop ... @@ -152,15 +148,13 @@ Running The Tests For Your Application To run unit tests for your application, you should invoke them like so: -.. code-block:: bash - :linenos: +.. code-block:: text $ ../bin/python setup.py test -q Here's sample output from a test run: -.. code-block:: bash - :linenos: +.. code-block:: text $ python setup.py test -q running test @@ -209,21 +203,18 @@ section within the ``.ini`` file. For example, if your application If so, you can use the following command to invoke a debug shell using the name ``main`` as a section name: -.. code-block:: bash - :linenos: +.. code-block:: text - [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main + [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main - Python 2.4.5 (#1, Aug 29 2008, 12:27:37) - [GCC 4.0.1 (Apple Inc. build 5465)] on darwin - Type "help" for more information. "root" is the BFG app root object. - >>> root - + Python 2.4.5 (#1, Aug 29 2008, 12:27:37) + [GCC 4.0.1 (Apple Inc. build 5465)] on darwin + Type "help" for more information. "root" is the BFG app root object. + >>> root + .. note:: You *might* get away without passing - ``--plugin=repoze.bfg`` to the bfgshell command; the - ``--plugin=repoze.bfg`` option is only required under - conditions that are not yet well-understood. + ``--plugin=repoze.bfg`` to the bfgshell command. If you have `IPython `_ installed in the interpreter you use to invoke the ``paster`` command, @@ -233,10 +224,9 @@ happen, even if you have IPython installed, you can pass the ``--disable-ipython`` flag to the ``bfgshell`` command to use a standard Python interpreter shell unconditionally. -.. code-block:: bash - :linenos: +.. code-block:: text - [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main + [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main Press "Ctrl-D" to exit the interactive shell. @@ -263,10 +253,9 @@ following ``.ini`` file content: The command you use to invoke the interactive shell should be: -.. code-block:: bash - :linenos: +.. code-block:: text - [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini myapp + [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini myapp If you use ``main`` as the section name argument instead of ``myapp`` against the above ``.ini`` file, an error will likely occur. Use the @@ -290,15 +279,13 @@ the generated ``MyProject.ini`` configuration file: webserver, as exception and debugging output will be sent to the console. -.. code-block:: bash - :linenos: +.. code-block:: text $ ../bin/paster serve MyProject.ini Here's sample output from a run: -.. code-block:: bash - :linenos: +.. code-block:: text $ paster serve MyProject.ini Starting server in PID 16601. diff --git a/docs/narr/scanning.rst b/docs/narr/scanning.rst index a7f47efd4..2226b557f 100644 --- a/docs/narr/scanning.rst +++ b/docs/narr/scanning.rst @@ -76,7 +76,6 @@ effectively: .. ignore-next-block .. code-block:: python - :linenos: config.add_view(hello, name='hello', request_method='GET') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index f4904f0bf..4e806ec17 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -6,7 +6,7 @@ Startup When you cause :mod:`repoze.bfg` to start up in a console window, you'll see something much like this show up on the console: -.. code-block:: bash +.. code-block:: text $ paster serve myproject/MyProject.ini Starting server in PID 16601. diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 1683b3cef..3476622d5 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -82,8 +82,7 @@ This inexperienced user's attempt to execute ``cat`` against the file named ``/fiz/buz/myfile`` might be to issue the following set of UNIX commands: -.. code-block:: bash - :linenos: +.. code-block:: text cd / cd fiz @@ -94,8 +93,7 @@ The user now know he has found a *file*, because the ``cd`` command issues an error when he executed ``cd myfile``. Now he knows that he can run the ``cat`` command: -.. code-block:: bash - :linenos: +.. code-block:: text cat myfile diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 443ffbfaa..2d74bfbca 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -62,14 +62,9 @@ registry`. Here's an example: .. ignore-next-block .. code-block:: python - :linenos: config.add_route('myroute', '/prefix/:one/:two') -See the :meth:`repoze.bfg.configuration.Configurator.add_route` API -documentation for more information and options for adding a route -imperatively. - Configuring a Route via ZCML ---------------------------- @@ -109,13 +104,17 @@ The path pattern syntax is simple. The path may start with a slash character. If the path does not start with a slash character, an implicit slash will be prepended to it at -matching time. For example, the following paths are equivalent:: +matching time. For example, the following paths are equivalent: + +.. code-block:: text - :foo/bar/baz + :foo/bar/baz -and:: +and: - /:foo/bar/baz +.. code-block:: text + + /:foo/bar/baz A path segment (an individual item between ``/`` characters in the path) may either be a literal string (e.g. ``foo``) *or* it may @@ -123,17 +122,23 @@ segment replacement marker (e.g. ``:foo``). A segment replacement marker is in the format ``:name``, where this means "accept any characters up to the next slash and use this as the ``name`` matchdict value." For example, the following pattern defines one literal -segment ("foo") and two dynamic segments ("baz", and "bar"):: +segment ("foo") and two dynamic segments ("baz", and "bar"): + +.. code-block:: text - foo/:baz/:bar + foo/:baz/:bar The above pattern will match these URLs, generating the following -matchdicts:: +matchdicts: + +.. code-block:: text foo/1/2 -> {'baz':u'1', 'bar':u'2'} foo/abc/def -> {'baz':u'abc', 'bar':u'2'} -It will not match the following patterns however:: +It will not match the following patterns however: + +.. code-block:: text foo/1/2/ -> No match (trailing slash) bar/abc/def -> First segment literal mismatch @@ -141,28 +146,38 @@ It will not match the following patterns however:: Note that values representing path segments matched with a ``:segment`` match will be url-unquoted and decoded from UTF-8 into Unicode within the matchdict. So for instance, the following -pattern:: +pattern: + +.. code-block:: text + + foo/:bar - foo/:bar +When matching the following URL: -When matching the following URL:: +.. code-block:: text - foo/La%20Pe%C3%B1a + foo/La%20Pe%C3%B1a The matchdict will look like so (the value is URL-decoded / UTF-8 -decoded):: +decoded): - {'bar':u'La Pe\xf1a'} +.. code-block:: text + + {'bar':u'La Pe\xf1a'} If the pattern has a ``*`` in it, the name which follows it is considered a "remainder match". A remainder match *must* come at the end of the path pattern. Unlike segment replacement markers, it does -not need to be preceded by a slash. For example:: +not need to be preceded by a slash. For example: + +.. code-block:: text - foo/:baz/:bar*traverse + foo/:baz/:bar*traverse The above pattern will match these URLs, generating the following -matchdicts:: +matchdicts: + +.. code-block:: text foo/1/2/ -> {'baz':1, 'bar':2, 'traverse':()} foo/abc/def/a/b/c -> {'baz':abc, 'bar':2, 'traverse':('a', 'b', 'c')} @@ -171,17 +186,23 @@ Note that when a ``*stararg`` remainder match is matched, the value put into the matchdict is turned into a tuple of path segments representing the remainder of the path. These path segments are url-unquoted and decoded from UTF-8 into Unicode. For example, for -the following pattern:: +the following pattern: + +.. code-block:: text + + foo/*traverse - foo/*traverse +When matching the following path: -When matching the following path:: +.. code-block:: text - /foo/La%20Pe%C3%B1a/a/b/c + /foo/La%20Pe%C3%B1a/a/b/c -Will generate the following matchdict:: +Will generate the following matchdict: - {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')} +.. code-block:: text + + {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')} ```` Statement Examples ------------------------------ @@ -283,8 +304,7 @@ might add to your ``configure.zcml``: The above configuration will allow :mod:`repoze.bfg` to service URLs in these forms: -.. code-block:: bash - :linenos: +.. code-block:: text /ideas/ /users/ @@ -436,6 +456,7 @@ this. .. ignore-next-block .. code-block:: python + :linenos: from repoze.bfg.url import route_url url = route_url('foo', request, a='1', b='2', c='3') @@ -529,6 +550,7 @@ be removed after each request. Put the following in the .. ignore-next-block .. code-block:: python + :linenos: from mypackage.sql import DBSession diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst index 2eeaa0646..e5933ae1e 100644 --- a/docs/narr/urlmapping.rst +++ b/docs/narr/urlmapping.rst @@ -38,10 +38,12 @@ item "below" ``members`` in the URL represents a member in the system. You just match everything "below" ``members`` to a particular view. For example, you might configure a :term:`route` to match against the -following URL patterns:: +following URL patterns: - archives/:year/:month/:day - members/:membername +.. code-block:: text + + archives/:year/:month/:day + members/:membername In this configuration, there are exactly two types of URLs that will match views in your application: ones that start with ``/archives`` @@ -50,10 +52,12 @@ day. And ones that start with ``/members`` which are followed by a path segment containing a member's name. This is very simple. :term:`URL dispatch` is not very good, however, at inferring the -difference between sets of URLs such as:: +difference between sets of URLs such as: + +.. code-block:: text - http://example.com/members/Chris/document - http://example.com/members/Chris/stuff/page + http://example.com/members/Chris/document + http://example.com/members/Chris/stuff/page ...wherein you'd like the ``document`` in the first URL to represent a PDF document, and ``/stuff/page`` in the second to represent an diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 5f9eb9140..c9929538f 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -125,7 +125,10 @@ request The following types work as views in this style: #. Functions that accept two arguments: ``context``, and ``request``, - e.g.:: + e.g.: + + .. code-block:: python + :linenos: from webob import Response @@ -133,7 +136,10 @@ The following types work as views in this style: return Response('OK') #. New-style and old-style classes that have an ``__init__`` method - that accepts ``context, request``, e.g.:: + that accepts ``context, request``, e.g.: + + .. code-block:: python + :linenos: from webob import Response @@ -142,7 +148,10 @@ The following types work as views in this style: return Response('OK') #. Arbitrary callables that have a ``__call__`` method that accepts - ``context, request``, e.g.:: + ``context, request``, e.g.: + + .. code-block:: python + :linenos: from webob import Response @@ -358,7 +367,6 @@ the following: your application's ``configure.zcml``: .. code-block:: xml - :linenos: @@ -366,7 +374,6 @@ the following: :meth:`repoze.bfg.configuration.Configurator.scan` method: .. code-block:: python - :linenos: config.scan() @@ -436,7 +443,6 @@ Or replaces the need to add this imperative configuration stanza: .. ignore-next-block .. code-block:: python - :linenos: config.add_view(name='my_view', request_method='POST', for_=MyModel, permission='read') @@ -1461,6 +1467,7 @@ a browser client, and its ``action`` points at some :mod:`repoze.bfg` view code: .. code-block:: xml + :linenos: @@ -1483,6 +1490,7 @@ expect that the values returned by ``request.params`` will be of type accept a form post from the above form: .. code-block:: python + :linenos: def myview(request): firstname = request.params['firstname'] @@ -1493,6 +1501,7 @@ decode already-decoded (``unicode``) values obtained from ``request.params``: .. code-block:: python + :linenos: def myview(request): # the .decode('utf-8') will break below if there are any high-order diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index 8dbdef6f2..c4bd568c7 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -53,16 +53,16 @@ object: The request method, e.g., ``'GET'``, ``'POST'`` ``req.GET``: - A `dictionary-like object`_ with all the variables in the query + A :term:`multidict` with all the variables in the query string. ``req.POST``: - A `dictionary-like object`_ with all the variables in the request + A :term:`multidict` with all the variables in the request body. This only has variables if the request was a ``POST`` and it is a form submission. ``req.params``: - A `dictionary-like object`_ with a combination of everything in + A :term:`multidict` with a combination of everything in ``req.GET`` and ``req.POST``. ``req.body``: @@ -85,8 +85,6 @@ object: `_ and `Selector `_. -.. _`dictionary-like object`: #multidict - Also, for standard HTTP request headers there are usually attributes, for instance: ``req.accept_language``, ``req.content_length``, ``req.user_agent``, as an example. These properties expose the @@ -171,8 +169,8 @@ WSGI): ``response.headerlist``: A list of all the headers, like ``[('Content-Type', - 'text/html')]``. There's a case-insensitive `dictionary-like - object`_ in ``response.headers`` that also allows you to access + 'text/html')]``. There's a case-insensitive :term:`multidict` + in ``response.headers`` that also allows you to access these same headers. ``response.app_iter``: -- cgit v1.2.3