auth: decorators: Make validate_request public

The `_validate_request` function in `milla.auth.decorators` is a helper
used by the `auth_required` and `require_perms` decorators. It can also
be used by custom decorators, so it is now a first-class, documented,
public function.

src/milla/auth/decorators.py

@@ -20,13 +20,18 @@
 from functools import wraps
 from milla.auth import permissions
 import milla.auth
+import warnings
 try:
     import pkg_resources
 except ImportError:
     pkg_resources = None
 
 
-__all__ = ['auth_required', 'require_perms']
+__all__ = [
+    'auth_required',
+    'require_perms',
+    'validate_request',
+]
 
 
 VALIDATOR_EP_GROUP = 'milla.request_validator'
@@ -42,6 +47,33 @@ def _find_request(*args, **kwargs):
 
 
 def _validate_request(func, requirement, *args, **kwargs):
+    warnings.warn(
+        '_validate_request is deprecated; use validate_request instead',
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    validate_request(func, requirement, *args, **kwargs)
+
+
+def validate_request(func, requirement, *args, **kwargs):
+    '''Validate a request meets a given requirement
+
+    :param func: Decorated callable
+    :param requirement: A requirement that the request must meet in
+       order to be considered valid, as specified by the request
+       validator used by the application. This is usally a sub-class of
+       :py:class:`~milla.auth.permissions.PermissionRequirement`, or
+       some other class that has a ``check`` method that accepts a
+       :py:class:`~milla.Request` object as its only argument.
+    :param args: Positional arguments to pass through to the decorated
+       callable
+    :param kwargs: Keyword arguments to pass through to the decorated
+       callable
+
+    This is a helper function used by :py:func:`auth_required` and
+    :py:func:`require_perms` that can be used by other request
+    decorators as well.
+    '''
     request = _find_request(*args, **kwargs)
 
     rv = request.config.get('request_validator', 'default')
@@ -103,7 +135,7 @@ def auth_required(func):
 
     @wraps(func)
     def wrapper(*args, **kwargs):
-        return _validate_request(func, None, *args, **kwargs)
+        return validate_request(func, None, *args, **kwargs)
     return wrapper
 
 
@@ -154,5 +186,5 @@ class require_perms(object):
     def __call__(self, func):
         @wraps(func)
         def wrapper(*args, **kwargs):
-            return _validate_request(func, self.requirement, *args, **kwargs)
+            return validate_request(func, self.requirement, *args, **kwargs)
         return wrapper