Commits

Anthon van der Neut committed 986898f

examguid_00: readability, references to patterns

  • Participants
  • Parent commits 3e432fb

Comments (0)

Files changed (2)

File doc/examples.rst

 ========
 
 We start with a simple `helloworld`_ example, than add a bit more
-modularity in `server time`_. Before we proceed with examples below
-let setup `virtualenv`_ environment::
+modularity in the example `server time`_. Before we proceed with examples below
+let's setup a `virtualenv`_ environment::
 
     $ virtualenv env
     $ env/bin/easy_install wheezy.routing
 Hello World
 -----------
 
-`helloworld.py`_ shows you how to use :ref:`wheezy.routing` in pretty a
+`helloworld.py`_ shows you how to use :ref:`wheezy.routing` in a pretty
 simple `WSGI`_ application:
 
 .. literalinclude:: ../demos/hello/helloworld.py
    :lines: 5-
 
-Let have a look through each line in this application. First of all we
+Let's have a look through each line in this application. First of all we
 import :py:class:`~wheezy.routing.PathRouter` that is actually just an
 exporting name for :py:class:`~wheezy.routing.router.PathRouter`:
 
 .. literalinclude:: ../demos/hello/helloworld.py
    :lines: 15-19
 
-In addition let add a handler for not found response.
+In addition let's add a handler for the 'not found' response.
 
 .. literalinclude:: ../demos/hello/helloworld.py
    :lines: 22-26
 
-The declaration and mapping of pattern to handler following. We create an
-instance of ``PathRouter`` class and pass mapping that in this partucular case
+The declaration and mapping of patterns to handlers follows. We create an
+instance of ``PathRouter`` class and pass it a mapping, that in this particular case
 is a tuple of two values: ``pattern`` and ``handler``.
 
 .. literalinclude:: ../demos/hello/helloworld.py
    :lines: 29-33
 
-The first pattern ``'/'`` will match only root path of the request (it is
-finishing route in match chain). The second pattern ``'/{any}'`` is a curly
-expression that is translated to regular expression that ultimately match
-any path and is finishing route as well.
+The first pattern ``'/'`` will match only the root path of the request (it is
+finishing route in the match chain). The second pattern ``'/{any}'`` is a curly
+expression, that is translated to regular expression, that ultimately matches
+any path and is a finishing route as well.
 
 ``main`` function serves as `WSGI`_ application entry point. The only thing
 we do here is to get a value of `WSGI`_ environment variable ``PATH_INFO``
-(the remainder of the request URL's path) and pass to router
-:py:meth:`~wheezy.routing.router.PathRouter.match` method, in return we
+(the remainder of the request URL's path) and pass it to the router
+:py:meth:`~wheezy.routing.router.PathRouter.match` method. In return we
 get ``handler`` and ``kwargs`` (parameters discovered from matching rule,
 that we ignore for now).
 
 .. literalinclude:: ../demos/hello/helloworld.py
    :lines: 36-38
 
-The rest in the ``helloworld`` application launch a simple wsgi server.
+The rest in the ``helloworld`` application launches a simple wsgi server.
 Try it by running::
 
     $ python helloworld.py
 Server Time
 -----------
 
-Server `time`_ application consists of two screens. The first one has a link
-to the second that shows the time on server. The second page will be mapped
+The server `time`_ application consists of two screens. The first one has a link
+to the second that shows the time on the server. The second page will be mapped
 as a separate application with its own routing. The design used in this
 sample is modular. Let's start with ``config`` module. The only thing we
 need here is an instance of ``PathRouter``.
 .. literalinclude:: ../demos/time/config.py
    :lines: 5-8
 
-``view`` module is pretty straight: a ``welcome`` view with a link to
-``server_time`` view. The server time page returns server time. And finally
-catch all ``not_found`` handler to display http 404 error, page not found.
+The ``view`` module is pretty straight: a ``welcome`` view with a link to
+``server_time`` view. The server time page returns the server time. And finally
+a catch all ``not_found`` handler to display http 404 error, page not found.
 
 .. literalinclude:: ../demos/time/views.py
    :lines: 5-
 
-So what is interesting in ``welcome`` view is a way how we get an url for
+So what is interesting in the ``welcome`` view is a way how we get a url for
 ``server_time`` view.
 
 .. literalinclude:: ../demos/time/views.py
    :lines: 14-15
 
-The name ``now`` was used during url mapping that you can see below (module
+The name ``now`` was used during url mapping as you can see below (module
 ``urls``):
 
 .. literalinclude:: ../demos/time/urls.py
    :lines: 5-
 
-``server_urls`` than included under the parent path ``server/``, so
-anything that starts from ``server/`` path will be directed to
+``server_urls`` are then included under the parent path ``server/``, so
+anything that starts with the path ``server/`` will be directed to the
 ``server_urls`` url mapping. Lastly we add a curly expression that maps
 any url match to our ``not_found`` handler.
 

File doc/userguide.rst

 .. literalinclude:: ../demos/hello/helloworld.py
    :lines: 36-38
 
-or more precisely::
+or more specifically::
 
     environ['PATH_INFO']
 
-This operation takes WSGI environment varible ``PATH_INFO`` and pass to
-router for matching against available mapping. ``handler`` in this case is a
+This operation takes the WSGI environment variable ``PATH_INFO`` and passes it to
+router for matching against available mappings. ``handler`` in this case is a
 simple callable that represents WSGI call handler.
 
 .. literalinclude:: ../demos/hello/helloworld.py
 ``server_urls`` included into ``server/`` subpath. So effective path for
 ``server_time`` handler is ``server/time``.
 
-Note that route selected for ``'server/'`` pattern is intermediate (it is not
-finishing since there is included another after it). ``'time'`` pattern is
-finishing since it is the last in the match chain.
+Note that the route selected for ``'server/'`` pattern is *intermediate* (it is not
+*finishing* since there is another pattern included after it). The ``'time'`` pattern is
+*finishing* since it is the last in the match chain.
 
 Named Groups
 ------------
 
-Named groups is something that you can get out from url mapping::
+Named groups are something that you can retrieve from the url mapping::
 
     urls = [
         ('posts/{year}', posts_by_year),
         ('posts/(?P<year>\d+)/(?P<month>\d+)', posts_by_month)
     ]
 
-``kwargs`` is assigned with ``dict`` that represends a key-value pair
-from match::
+``kwargs`` is assigned a ``dict`` that represends key-value pairs
+from the match::
 
    >>> handler, kwargs = r.match('posts/2011/09')
    >>> kwargs
 Extra Parameters
 ----------------
 
-While ``named groups`` get some information from matched ``path``, you
-can also merge with some extra values during initialization of mapping
-(this is third parameter in tupple)::
+While ``named groups`` get some information from the matched ``path``, you
+can also merge these with some extra values during initialization of the mapping
+(this is third parameter in tuple)::
 
     urls = [
         ('posts', latest_posts, {'blog_id': 100})
     ]
 
-Note, that any non-empty values from path match override extra parameters
+Note, that any non-empty values from the path match override extra parameters
 passed during initialization.
 
 ``url`` helper
 --------------
 
 There is :py:func:`wheezy.routing.router.url` function that let you
-make your url mapping more readable::
+make your url mappings more readable::
 
     from wheezy.routing import url
 
         url('posts', latest_posts, kwargs={'blog_id': 100})
     ]
 
-All it does just convers arguments to a tupple of four.
+All it does just convers arguments to a tuple of four.
 
 .. _named:
 
 
 Each path mapping you create is automatically named after the handler name.
 The convention as to the name is: translate handler name from camel case
-to underscope name and remove anything ended by handler, controller, etc.
+to underscore name and remove any ending like 'handler', 'controller', etc.
 So ``LatestPostsHandler`` is named as ``latest_posts``.
 
-You can specify other name during mapping, it is convenient to use
+You can also specify an explicit name during mapping, it is convenient to use
 :py:func:`~wheezy.routing.router.url`) function for this::
 
     urls = [
         url('posts', latest_posts, name='posts')
     ]
 
-When you know name for url mapping you can reconstruct it path.
+When you know the name for a url mapping, you can reconstruct its path.
 
 Adding Routes
 -------------
 
 You have an instance of :py:class:`~wheezy.routing.router.PathRouter`.
-Call it method :py:meth:`~wheezy.routing.router.PathRouter.add_routes`
+Call its method :py:meth:`~wheezy.routing.router.PathRouter.add_routes`
 to add any pattern mapping you have. Here is how we do it in
-:ref:`helloworld` example:
+the :ref:`helloworld` example:
 
 .. literalinclude:: ../demos/hello/helloworld.py
    :lines: 30-33
 Route Builders
 --------------
 
-Every pattern mapping you add to router is translated to appropriate route
+Every pattern mapping you add to router is translated to an appropriate route
 match strategy. The available routing match strategies are definded in
 :py:mod:`~wheezy.routing.config` module by ``route_builders`` list and
 include:
 The plain route is selected in case the path satisfy the following regular
 expression (at least one ``word``, ``'/'`` or ``'-'`` character):
 
-.. literalinclude:: ../src/wheezy/routing/builders.py
-   :lines: 14-14
+.. literalinclude:: ../src/wheezy/routing/plain.py
+   :lines: 8-8
 
 The matching paths include: ``account/login``, ``blog/list``, etc. The
-strategy performs string marching.
+strategy performs string matching.
 
 Finishing routes are matched by exact string ``equals`` operation, intermediate
 routes are matched with ``startswith`` string operation.
 Regex Route
 ~~~~~~~~~~~
 
-Any valid regular expression will match this strategy. However there few
-limitation that applies if you would like to build paths by name (reverse
+Any valid regular expression will match this strategy. However there are a few
+limitations that apply if you would like to build paths by name (reverse
 function to path matching). Use regex syntax only inside named groups,
-create them as much as necessary. The path build strategy simply replaces
+create as many as necessary. The path build strategy simply replaces
 named groups with values supplied. Optional named groups are supported.
 
 Curly Route
 ~~~~~~~~~~~
 
 This is just a simplified version of regex routes. Curly route is something
-that match the following regular expression:
+that matches the following regular expression:
 
 .. literalinclude:: ../src/wheezy/routing/curly.py
-   :lines: 9-9
+   :lines: 11-11
 
 You define a named group by using curly brakets. The form of
 curly expression (``pattern`` is optional and corresponds to segment by
 
     {name[:pattern]}
 
-The curly expression ``abc/{id}`` is convered into regex ``abc/(?P<id>[^/]+)``.
+The curly expression ``abc/{id}`` is converted into regex ``abc/(?P<id>[^/]+)``.
 
-The name inside curly expression can be constrained with the following
+The name inside the curly expression can be constrained with the following
 patterns:
 
 - ``i``, ``int``, ``number``, ``digits`` - one or more digits
 - ``s``, ``segment``, ``part`` - everything until ``'/'`` (path segment)
 - ``*``, ``a``, ``any``, ``rest`` - match anything
 
-Note that if pattern constraint doesn't corresponds to anything mentioned
-above than it is interpreted as a regular expression::
+Note that if the pattern constraint doesn't correspond to anything mentioned
+above, then it will be interpreted as a regular expression::
 
     locale:(en|ru)}/home => (?P<locale>(en|ru))/home
 
-Curly route also supports optional values (these should be taken into
+Curly routes also support optional values (these should be taken into
 square brackets)::
 
     [{locale:(en|ru)}/]home => ((?P<locale>(en|ru))/)?home
     posts/{year:i}/{month:i}
     account/{name:w}
 
-You can extend recognized curly patterns::
+You can extend the recognized curly patterns::
 
     from wheezy.routing.curly import patterns
 
 --------------
 
 Once you have defined routes you can build paths from them. See :ref:`named`
-how the name of url mapping is cunstructed. Here is a example from
+how the name of url mapping is constructed. Here is a example from
 :ref:`server time`:
 
 .. literalinclude:: ../demos/time/views.py
     >>> r.path_for()
     'abc/1/1'
 
-Values passed to :py:meth:`~wheezy.routing.router.PathRouter.path_for`
+Values passed to the :py:meth:`~wheezy.routing.router.PathRouter.path_for`
 method override any values used during initialization of url mapping.
 
 :py:class:`KeyError` is raised in case you try to build a path
-that doesn't exist or insufficient arguments for building a path.
+that doesn't exist or provide insufficient arguments for building a path.