Add support for ``requirements`` to mapper.resource

This adds support for ``requirements`` option to mapper.resource,
which makes it possible to restrict matching in urls (most often
useful for capturing variables with path_prefix).

In OpenStack Nova we've used the prefix_path on Mapper.resource to
specify additional variables we want to capture (specifically
{project_id}). Project_id is a uuid. When trying to restrict
project_id to only valid uuid format a couple of issues were exposed.

 - #1 '/{project_id:[a-f0-9]{32}}/...' builds an incorrect regex
    because of the nested {}

 - #2 the preferred method that works on connect() to pass
    requirements doesn't work here (requirements are reset to only an
    id match)

That leaves us with having to build a custom project_id match with 32
[a-f0-9] strings appended for every resource added to get the support
we need without effectively vendoring our own version of Mapper.resource.

This small change to allow requirements to pass through would make it
possible to get this tighter validation with much smaller regexes.

1 files changed, 18 insertions, 0 deletions

diff --git a/routes/mapper.py b/routes/mapper.py
index 7ca9ee9..382c01d 100644
--- a/routes/mapper.py
+++ b/routes/mapper.py
@@ -982,6 +982,22 @@ class Mapper(SubMapperParent):
                 # GET /category/7/message/1
                 # has named route "category_message"
 
+        ``requirements``
+
+           A dictionary that restricts the matching of a
+           variable. Can be used when matching variables with path_prefix.
+
+           Example::
+
+                map.resource('message', 'messages',
+                     path_prefix='{project_id}/',
+                     requirements={"project_id": R"\d+"})
+                # POST /01234/message
+                #    success, project_id is set to "01234"
+                # POST /foo/message
+                #    404 not found, won't be matched by this route
+
+
         ``parent_resource``
             A ``dict`` containing information about the parent
             resource, for creating a nested resource. It should contain
@@ -1105,6 +1121,8 @@ class Mapper(SubMapperParent):
             '_parent_resource': parent_resource,
             '_filter': kwargs.get('_filter')
         }
+        if 'requirements' in kwargs:
+            options['requirements'] = kwargs['requirements']
 
         def requirements_for(meth):
             """Returns a new dict to be used for all route creation as the