new: Graceful deprecation rename of marshal_schema to response_body_schema (plangrid#101)

* chg: Refactor utilities into a separate utils package

Author: RookieRick

README.rst

@@ -65,7 +65,7 @@ Example
        rule='/todos',
        method='GET',
        query_string_schema=GetTodosQueryStringSchema(),
-       marshal_schema=GetTodosResponseSchema(),
+       response_body_schema=GetTodosResponseSchema(), # for versions <= 1.7.0, use marshal_schema
    )
    def get_todos():
        """

docs/index.rst

@@ -56,7 +56,7 @@ Here's what a basic Flask-Rebar application looks like:
        rule='/todos',
        method='GET',
        query_string_schema=GetTodosQueryStringSchema(),
-       marshal_schema=GetTodosResponseSchema(),
+       response_body_schema=GetTodosResponseSchema(), # For version <= 1.7.0 use marshal_schema
    )
    def get_todos():
        """

docs/quickstart/basics.rst

@@ -25,7 +25,7 @@ Let's take a look at a very basic API using Flask-Rebar:
    @registry.handles(
       rule='/todos/<id>',
       method='GET',
-      marshal_schema=TodoSchema()
+      response_body_schema=TodoSchema()  # for versions <= 1.7.0, use marshal_schema
    )
    def get_todo(id):
        ...
@@ -47,7 +47,7 @@ We then create a handler registry that we will use to declare handlers for the s
 
 ``method`` is the HTTP method that the handler will accept. To register multiple methods for a single handler function, decorate the function multiple times.
 
-``marshal_schema`` is a Marshmallow schema that will be used marshal the return value of the function. `marshmallow.Schema.dump <http://marshmallow.readthedocs.io/en/latest/api_reference.html#marshmallow.Schema.dump>`_ will be called on the return value. ``marshal_schema`` can also be a dictionary mapping status codes to Marshmallow schemas - see :ref:`Marshaling`.
+``response_body_schema`` is a Marshmallow schema that will be used marshal the return value of the function. `marshmallow.Schema.dump <http://marshmallow.readthedocs.io/en/latest/api_reference.html#marshmallow.Schema.dump>`_ will be called on the return value. ``response_body_schema`` can also be a dictionary mapping status codes to Marshmallow schemas - see :ref:`Marshaling`.  *NOTE: In Flask-Rebar 1.0-1.7.0, this was referred to as ``marshal_schema``. It is being renamed and both names will function until version 2.0*
 
 The handler function should accept any arguments specified in ``rule``, just like a Flask view function.
 
@@ -155,7 +155,7 @@ This default can be overriden in any particular handler by setting ``headers_sch
 Marshaling
 ==========
 
-The ``marshal_schema`` argument of ``HandlerRegistry.handles`` can be one of three types: a ``marshmallow.Schema``, a dictionary mapping integers to ``marshmallow.Schema``, or ``None``.
+The ``response_body_schema`` (previously ``marshal_schema``) argument of ``HandlerRegistry.handles`` can be one of three types: a ``marshmallow.Schema``, a dictionary mapping integers to ``marshmallow.Schema``, or ``None``.
 
 In the case of a ``marshmallow.Schema``, that schema is used to ``dump`` the return value of the handler function.
 
@@ -166,7 +166,7 @@ In the case of a dictionary mapping integers to ``marshmallow.Schemas``, the int
    @registry.handles(
       rule='/todos',
       method='POST',
-      marshal_schema={
+      response_body_schema={
           201: TodoSchema()
       }
    )
@@ -176,15 +176,15 @@ In the case of a dictionary mapping integers to ``marshmallow.Schemas``, the int
 
 The schema to use for marshaling will be retrieved based on the status code the handler function returns. This isn't the prettiest part of Flask-Rebar, but it's done this way to help with the automatic Swagger generation.
 
-In the case of ``None`` (which is also the default), no marshaling takes place, and the return value is passed directly through to Flask. This means the if ``marshal_schema`` is ``None``, the return value must be a return value that Flask supports, e.g. a string or a ``Flask.Response`` object.
+In the case of ``None`` (which is also the default), no marshaling takes place, and the return value is passed directly through to Flask. This means the if ``response_body_schema`` is ``None``, the return value must be a return value that Flask supports, e.g. a string or a ``Flask.Response`` object.
 
 .. code-block:: python
 
 
    @registry.handles(
       rule='/todos',
       method='GET',
-      marshal_schema=None
+      response_body_schema=None
    )
    def get_todos():
        ...

docs/recipes.rst

@@ -53,7 +53,7 @@ Here is a simple recipe for using Flask-Rebar with these pluggable views:
        registry.add_handler(
            func=Todo.as_view(method + "_todo", database=database),
            rule="/todos/<id>",
-           marshal_schema=TodoSchema(),
+           response_body_schema=TodoSchema(),  # for versions <= 1.7.0, use marshal_schema
            method=method,
            request_body_schema=request_body_schema,
        )

examples/todo/todo.py

@@ -77,7 +77,9 @@ def envelope_in_data(self, data):
     tags=["todo"],
     # This dictionary tells framer which schema to use for which response code.
     # This is a little ugly, but tremendously helpful for generating swagger.
-    marshal_schema={201: TodoResourceSchema()},
+    response_body_schema={
+        201: TodoResourceSchema()
+    },  # for versions <= 1.7.0, use marshal_schema
 )
 def create_todo():
     global todo_id_sequence, todo_database
@@ -105,7 +107,7 @@ def create_todo():
     tags=["todo"],
     # If the value for this is not a dictionary, the response code is assumed
     # to be 200
-    marshal_schema=TodoListSchema(),
+    response_body_schema=TodoListSchema(),  # for versions <= 1.7.0, use marshal_schema
 )
 def get_todos():
     global todo_database
@@ -127,7 +129,7 @@ def get_todos():
 @registry.handles(
     rule="/todos/<int:todo_id>",
     method="PATCH",
-    marshal_schema=TodoResourceSchema(),
+    response_body_schema=TodoResourceSchema(),  # for versions <= 1.7.0, use marshal_schema
     request_body_schema=UpdateTodoSchema(),
     tags=["todo"],
 )

flask_rebar/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import unicode_literals
 
-from flask_rebar.request_utils import marshal, response
+from flask_rebar.utils.request_utils import marshal, response
 
 from flask_rebar.rebar import (
     Rebar,

flask_rebar/rebar.py

@@ -26,36 +26,19 @@
 from flask_rebar import messages
 from flask_rebar.authenticators import USE_DEFAULT
 from flask_rebar import errors
-from flask_rebar.request_utils import marshal
-from flask_rebar.request_utils import response
-from flask_rebar.request_utils import get_header_params_or_400
-from flask_rebar.request_utils import get_json_body_params_or_400
-from flask_rebar.request_utils import get_query_string_params_or_400
+from flask_rebar.utils.request_utils import marshal
+from flask_rebar.utils.request_utils import response
+from flask_rebar.utils.request_utils import get_header_params_or_400
+from flask_rebar.utils.request_utils import get_json_body_params_or_400
+from flask_rebar.utils.request_utils import get_query_string_params_or_400
+from flask_rebar.utils.deprecation import deprecated, deprecated_parameters
 from flask_rebar.swagger_generation import SwaggerV2Generator
 from flask_rebar.swagger_ui import create_swagger_ui_blueprint
 
-# Metadata about a declared handler function. This can be used to both
-# declare the flask routing and to autogenerate swagger.
-PathDefinition = namedtuple(
-    "PathDefinition",
-    [
-        "func",
-        "path",
-        "method",
-        "endpoint",
-        "marshal_schema",
-        "query_string_schema",
-        "request_body_schema",
-        "headers_schema",
-        "authenticator",
-        "tags",
-        "mimetype",
-    ],
-)
-
 
 # To catch redirection exceptions, app.errorhandler expects 301 in versions
 # below 0.11.0 but the exception itself in versions greater than 0.11.0.
+# NOTE: as of Flask 1.0.3, redirects are no longer bubbled up as exceptions
 if LooseVersion(flask_version) < LooseVersion("0.11.0"):
     MOVED_PERMANENTLY_ERROR = 301
     PERMANENT_REDIRECT_ERROR = 308
@@ -96,13 +79,14 @@ def _unpack_view_func_return_value(rv):
     return data, int(status), headers
 
 
+@deprecated_parameters(marshal_schema=("response_body_schema", "2.0"))
 def _wrap_handler(
     f,
     authenticator=None,
     query_string_schema=None,
     request_body_schema=None,
     headers_schema=None,
-    marshal_schema=None,
+    response_body_schema=None,
     mimetype=None,
 ):
     """
@@ -130,12 +114,12 @@ def wrapped(*args, **kwargs):
 
         rv = f(*args, **kwargs)
 
-        if not marshal_schema:
+        if not response_body_schema:
             return rv
 
         data, status_code, headers = _unpack_view_func_return_value(rv)
 
-        schema = marshal_schema[status_code]  # May raise KeyError.
+        schema = response_body_schema[status_code]  # May raise KeyError.
 
         # The schema may be declared as None to bypass marshaling (e.g. for 204 responses).
         if schema is None:
@@ -209,6 +193,38 @@ def prefix_url(prefix, url):
     return "/{}/{}".format(prefix, url)
 
 
+# Metadata about a declared handler function. This can be used to both
+# declare the flask routing and to autogenerate swagger.
+class PathDefinition(
+    namedtuple(
+        "_PathDefinition",
+        [
+            "func",
+            "path",
+            "method",
+            "endpoint",
+            "response_body_schema",
+            "query_string_schema",
+            "request_body_schema",
+            "headers_schema",
+            "authenticator",
+            "tags",
+            "mimetype",
+        ],
+    )
+):
+    __slots__ = ()
+
+    @deprecated_parameters(marshal_schema=("response_body_schema", "2.0"))
+    def __new__(cls, *args, **kwargs):
+        return super(PathDefinition, cls).__new__(cls, *args, **kwargs)
+
+    @property
+    @deprecated("response_body_schema", "2.0")
+    def marshal_schema(self):
+        return self.response_body_schema
+
+
 class HandlerRegistry(object):
     """
     Registry for request handlers.
@@ -318,7 +334,7 @@ def paths(self):
                     path=path,
                     method=definition_.method,
                     endpoint=definition_.endpoint,
-                    marshal_schema=definition_.marshal_schema,
+                    response_body_schema=definition_.response_body_schema,
                     query_string_schema=definition_.query_string_schema,
                     request_body_schema=definition_.request_body_schema,
                     headers_schema=definition_.headers_schema,
@@ -329,13 +345,14 @@ def paths(self):
 
         return paths
 
+    @deprecated_parameters(marshal_schema=("response_body_schema", "2.0"))
     def add_handler(
         self,
         func,
         rule,
         method="GET",
         endpoint=None,
-        marshal_schema=None,
+        response_body_schema=None,
         query_string_schema=None,
         request_body_schema=None,
         headers_schema=USE_DEFAULT,
@@ -353,7 +370,7 @@ def add_handler(
         :param str method:
             The HTTP method this handler accepts
         :param str endpoint:
-        :param dict[int, marshmallow.Schema] marshal_schema:
+        :param dict[int, marshmallow.Schema] response_body_schema:
             Dictionary mapping response codes to schemas to use to marshal
             the response. For now this assumes everything is JSON.
         :param marshmallow.Schema query_string_schema:
@@ -372,15 +389,15 @@ def add_handler(
         :param Type[USE_DEFAULT]|None|str mimetype:
             Content-Type header to add to the response schema
         """
-        if isinstance(marshal_schema, marshmallow.Schema):
-            marshal_schema = {200: marshal_schema}
+        if isinstance(response_body_schema, marshmallow.Schema):
+            response_body_schema = {200: response_body_schema}
 
         self._paths[rule][method] = PathDefinition(
             func=func,
             path=rule,
             method=method,
             endpoint=endpoint,
-            marshal_schema=marshal_schema,
+            response_body_schema=response_body_schema,
             query_string_schema=query_string_schema,
             request_body_schema=request_body_schema,
             headers_schema=headers_schema,
@@ -389,12 +406,13 @@ def add_handler(
             mimetype=mimetype,
         )
 
+    @deprecated_parameters(marshal_schema=("response_body_schema", "2.0"))
     def handles(
         self,
         rule,
         method="GET",
         endpoint=None,
-        marshal_schema=None,
+        response_body_schema=None,
         query_string_schema=None,
         request_body_schema=None,
         headers_schema=USE_DEFAULT,
@@ -413,7 +431,7 @@ def wrapper(f):
                 rule=rule,
                 method=method,
                 endpoint=endpoint,
-                marshal_schema=marshal_schema,
+                response_body_schema=response_body_schema,
                 query_string_schema=query_string_schema,
                 request_body_schema=request_body_schema,
                 headers_schema=headers_schema,
@@ -457,7 +475,7 @@ def _register_routes(self, app):
                             if definition_.headers_schema is USE_DEFAULT
                             else definition_.headers_schema
                         ),
-                        marshal_schema=definition_.marshal_schema,
+                        response_body_schema=definition_.response_body_schema,
                         mimetype=(
                             self.default_mimetype
                             if definition_.mimetype is USE_DEFAULT