From: Ben Darnell <ben@bendarnell.com>
Date: Sun, 14 Feb 2016 00:09:07 +0000 (-0500)
Subject: Improve docs of URLSpec capturing groups
X-Git-Tag: v4.4.0b1~54
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=759ac2df1eb6eba50578460484eb09a053ec66de;p=thirdparty%2Ftornado.git

Improve docs of URLSpec capturing groups

Inspired by https://groups.google.com/d/msg/python-tornado/eQ3wyusHCio/4eVVANYxAAAJ
---

diff --git a/docs/web.rst b/docs/web.rst
index a204e9d0e..dbbc13ce8 100644
--- a/docs/web.rst
+++ b/docs/web.rst
@@ -25,6 +25,11 @@
    These methods can be made asynchronous with one of the following
    decorators: `.gen.coroutine`, `.return_future`, or `asynchronous`.
 
+   The arguments to these methods come from the `.URLSpec`: Any
+   capturing groups in the regular expression become arguments to the
+   HTTP verb methods (keyword arguments if the group is named,
+   positional arguments if its unnamed).
+
    To support a method not on this list, override the class variable
    ``SUPPORTED_METHODS``::
 
diff --git a/tornado/web.py b/tornado/web.py
index fd971a8ca..4979813c0 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -2967,9 +2967,11 @@ class URLSpec(object):
     def __init__(self, pattern, handler, kwargs=None, name=None):
         """Parameters:
 
-        * ``pattern``: Regular expression to be matched.  Any groups
-          in the regex will be passed in to the handler's get/post/etc
-          methods as arguments.
+        * ``pattern``: Regular expression to be matched. Any capturing
+          groups in the regex will be passed in to the handler's
+          get/post/etc methods as arguments (by keyword if named, by
+          position if unnamed. Named and unnamed capturing groups may
+          may not be mixed in the same rule).
 
         * ``handler``: `RequestHandler` subclass to be invoked.
 
@@ -2978,6 +2980,7 @@ class URLSpec(object):
 
         * ``name`` (optional): A name for this handler.  Used by
           `Application.reverse_url`.
+
         """
         if not pattern.endswith('$'):
             pattern += '$'