Merge branch 'feature/pyramid_and_generic_doc_generation' into feature/flask

.editorconfig

@@ -0,0 +1,20 @@
+# EditorConfig: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.py]
+charset = utf-8
+indent_style = space
+indent_size = 4
+max_line_length = 79
+
+# Matches the exact files either package.json or .travis.yml
+[.travis.yml]
+indent_style = space
+indent_size = 2

.gitignore

@@ -6,3 +6,5 @@ __pycache__
 .cache
 *.egg-info
 .coverage
+/build
+/dist

example.py

@@ -31,3 +31,7 @@ class HelloJsonSchema(marshmallow.Schema):
         required=True,
         validate=marshmallow.validate.Length(min=3),
     )
+
+
+class HelloFileSchema(marshmallow.Schema):
+    myfile = marshmallow.fields.Raw(required=True)

example_a.py

@@ -9,7 +9,7 @@ from beaker.middleware import SessionMiddleware
 
 import hapic
 from example import HelloResponseSchema, HelloPathSchema, HelloJsonSchema, \
-    ErrorResponseSchema, HelloQuerySchema
+    ErrorResponseSchema, HelloQuerySchema, HelloFileSchema
 from hapic.data import HapicData
 
 # hapic.global_exception_handler(UnAuthExc, StandardErrorSchema)
@@ -96,10 +96,17 @@ class Controllers(object):
             'name': name,
         }
 
+    @hapic.with_api_doc()
+    @hapic.input_files(HelloFileSchema())
+    @hapic.output_file(['image/jpeg'])
+    def hellofile(self, hapic_data: HapicData):
+        return hapic_data.files['myfile']
+
     def bind(self, app):
         app.route('/hello/<name>', callback=self.hello)
         app.route('/hello/<name>', callback=self.hello2, method='POST')
         app.route('/hello3/<name>', callback=self.hello3)
+        app.route('/hellofile', callback=self.hellofile)
 
 app = bottle.Bottle()
 

example_a2.py

@@ -0,0 +1,139 @@
+# -*- coding: utf-8 -*-
+import json
+from http import HTTPStatus
+
+from pyramid.view import view_config
+from pyramid.config import Configurator
+from wsgiref.simple_server import make_server
+import time
+import yaml
+from beaker.middleware import SessionMiddleware
+
+import hapic
+from example import HelloResponseSchema, HelloPathSchema, HelloJsonSchema, \
+    ErrorResponseSchema, HelloQuerySchema
+from hapic.data import HapicData
+
+# hapic.global_exception_handler(UnAuthExc, StandardErrorSchema)
+# hapic.global_exception_handler(UnAuthExc2, StandardErrorSchema)
+# hapic.global_exception_handler(UnAuthExc3, StandardErrorSchema)
+# bottle.default_app.push(app)
+
+# session_opts = {
+#     'session.type': 'file',
+#     'session.data_dir': '/tmp',
+#     'session.cookie_expires': 3600,
+#     'session.auto': True
+# }
+# session_middleware = SessionMiddleware(
+#     app,
+#     session_opts,
+#     environ_key='beaker.session',
+#     key='beaker.session.id',
+# )
+# app = session_middleware.wrap_app
+
+
+def bob(f):
+    def boby(*args, **kwargs):
+        return f(*args, **kwargs)
+    return boby
+
+class Controllers(object):
+    
+    @hapic.with_api_doc()
+    # @hapic.ext.bottle.bottle_context()
+    @hapic.handle_exception(ZeroDivisionError, http_code=HTTPStatus.BAD_REQUEST)
+    @hapic.input_path(HelloPathSchema())
+    @hapic.input_query(HelloQuerySchema())
+    @hapic.output_body(HelloResponseSchema())
+    def hello(self,context,request,hapic_data: HapicData):
+        """
+        my endpoint hello
+        ---
+        get:
+            description: my description
+            parameters:
+                - in: "path"
+                  description: "hello"
+                  name: "name"
+                  type: "string"
+            responses:
+                200:
+                    description: A pet to be returned
+                    schema: HelloResponseSchema
+        """
+        name = request.matchdict.get('name', None)
+        if name == 'zero':
+            raise ZeroDivisionError('Don\'t call him zero !')
+
+        return {
+            'sentence': 'Hello !',
+            'name': name,
+       }
+
+    
+    # @hapic.with_api_doc()
+    # # @hapic.ext.bottle.bottle_context()
+    # # @hapic.error_schema(ErrorResponseSchema())
+    # #@hapic.input_path(HelloPathSchema())
+    # #@hapic.input_body(HelloJsonSchema())
+    # #@hapic.output_body(HelloResponseSchema())
+    # @bob
+    # def hello2(self, name: str, hapic_data: HapicData):
+    #     return {
+    #         'sentence': 'Hello !',
+    #         'name': name,
+    #         'color': hapic_data.body.get('color'),
+    #     }
+
+    # kwargs = {'validated_data': {'name': 'bob'}, 'name': 'bob'}
+
+    
+    # @view_config(renderer='json')
+    # @hapic.with_api_doc()
+    # # @hapic.ext.bottle.bottle_context()
+    # # @hapic.error_schema(ErrorResponseSchema())
+    # @hapic.input_path(HelloPathSchema())
+    # @hapic.output_body(HelloResponseSchema())
+    # def hello3(self, name: str):
+    #     return {
+    #         'sentence': 'Hello !',
+    #         'name': name,
+    #     }
+
+    def bind(self, config):
+        config.add_route('hello', '/hello/{name}', request_method='GET')
+        #config.add_route('hello2', '/hello/{name}', request_method='POST')
+        #config.add_route('hello3', '/hello/{name}', request_method='GET')
+        config.add_view(self.hello, route_name='hello', renderer='json')
+        #config.add_view(self.hello2, route_name='hello2')
+        #config.add_view(self.hello3, route_name='hello3')
+
+
+with Configurator() as config:
+    controllers = Controllers()
+    controllers.bind(config)
+    config.include('pyramid_debugtoolbar')
+    app = config
+
+
+
+
+# time.sleep(1)
+# s = hapic.generate_doc(app)
+# ss = json.loads(json.dumps(s))
+# for path in ss['paths']:
+#     for method in ss['paths'][path]:
+#         for response_code in ss['paths'][path][method]['responses']:
+#             ss['paths'][path][method]['responses'][int(response_code)] = ss['paths'][path][method]['responses'][response_code]
+#             del ss['paths'][path][method]['responses'][int(response_code)]
+# print(yaml.dump(ss, default_flow_style=False))
+# time.sleep(1)
+
+hapic.set_context(hapic.ext.pyramid.PyramidContext())
+import pdb; pdb.set_trace()
+#print(json.dumps(hapic.generate_doc(app)))
+# app.run(host='localhost', port=8080, debug=True)
+server = make_server('0.0.0.0', 6543, app.make_wsgi_app())
+server.serve_forever()

example_a_pyramid.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+import json
+from http import HTTPStatus
+
+#import bottle
+from pyramid.config import Configurator
+from wsgiref.simple_server import make_server
+import time
+import yaml
+import uuid
+from beaker.middleware import SessionMiddleware
+
+import hapic
+from example import HelloResponseSchema, HelloPathSchema, HelloJsonSchema, \
+    ErrorResponseSchema, HelloQuerySchema
+from hapic.data import HapicData
+
+# hapic.global_exception_handler(UnAuthExc, StandardErrorSchema)
+# hapic.global_exception_handler(UnAuthExc2, StandardErrorSchema)
+# hapic.global_exception_handler(UnAuthExc3, StandardErrorSchema)
+# bottle.default_app.push(app)
+
+# session_opts = {
+#     'session.type': 'file',
+#     'session.data_dir': '/tmp',
+#     'session.cookie_expires': 3600,
+#     'session.auto': True
+# }
+# session_middleware = SessionMiddleware(
+#     app,
+#     session_opts,
+#     environ_key='beaker.session',
+#     key='beaker.session.id',
+# )
+# app = session_middleware.wrap_app
+
+
+def bob(f):
+    def boby(*args, **kwargs):
+        return f(*args, **kwargs)
+    return boby
+
+
+class Controllers(object):
+    @hapic.with_api_doc()
+    # @hapic.ext.bottle.bottle_context()
+    @hapic.handle_exception(ZeroDivisionError, http_code=HTTPStatus.BAD_REQUEST)
+    @hapic.input_path(HelloPathSchema())
+    @hapic.input_query(HelloQuerySchema())
+    @hapic.output_body(HelloResponseSchema())
+    def hello(self, context, request, hapic_data: HapicData):
+        """
+        my endpoint hello
+        ---
+        get:
+            description: my description
+            parameters:
+                - in: "path"
+                  description: "hello"
+                  name: "name"
+                  type: "string"
+            responses:
+                200:
+                    description: A pet to be returned
+                    schema: HelloResponseSchema
+        """
+        name = request.matchdict.get('name', None)
+        if name == 'zero':
+            raise ZeroDivisionError('Don\'t call him zero !')
+
+        return {
+            'sentence': 'Hello !',
+            'name': name,
+        }
+
+    @hapic.with_api_doc()
+    # @hapic.ext.bottle.bottle_context()
+    # @hapic.error_schema(ErrorResponseSchema())
+    @hapic.input_path(HelloPathSchema())
+    @hapic.input_body(HelloJsonSchema())
+    @hapic.output_body(HelloResponseSchema())
+    @bob
+    def hello2(self, context, request, hapic_data: HapicData):
+        name = request.matchdict.get('name', None)
+        return {
+            'sentence': 'Hello !',
+            'name': name,
+            'color': hapic_data.body.get('color'),
+        }
+
+    kwargs = {'validated_data': {'name': 'bob'}, 'name': 'bob'}
+
+    @hapic.with_api_doc()
+    # @hapic.ext.bottle.bottle_context()
+    # @hapic.error_schema(ErrorResponseSchema())
+    @hapic.input_path(HelloPathSchema())
+    @hapic.output_body(HelloResponseSchema())
+    def hello3(self, context, request, hapic_data: HapicData):
+        name = request.matchdict.get('name', None)
+        return {
+            'sentence': 'Hello !',
+            'name': name,
+        }
+
+    def bind(self, configurator: Configurator):
+        configurator.add_route('hello', '/hello/{name}', request_method='GET')
+        configurator.add_view(self.hello, route_name='hello', renderer='json')
+
+        configurator.add_route('hello2', '/hello/{name}', request_method='POST')  # nopep8
+        configurator.add_view(self.hello2, route_name='hello2', renderer='json')  # nopep8
+
+        configurator.add_route('hello3', '/hello3/{name}', request_method='GET')  # nopep8
+        configurator.add_view(self.hello3, route_name='hello3', renderer='json')  # nopep8
+
+
+configurator = Configurator(autocommit=True)
+controllers = Controllers()
+
+controllers.bind(configurator)
+
+hapic.set_context(hapic.ext.pyramid.PyramidContext(configurator))
+print(json.dumps(hapic.generate_doc()))
+
+server = make_server('0.0.0.0', 8080, configurator.make_wsgi_app())
+server.serve_forever()

hapic/__init__.py

@@ -11,8 +11,10 @@ input_body = _hapic_default.input_body
 input_path = _hapic_default.input_path
 input_query = _hapic_default.input_query
 input_forms = _hapic_default.input_forms
+input_files = _hapic_default.input_files
 output_headers = _hapic_default.output_headers
 output_body = _hapic_default.output_body
+output_file = _hapic_default.output_file
 generate_doc = _hapic_default.generate_doc
 set_context = _hapic_default.set_context
 handle_exception = _hapic_default.handle_exception

hapic/buffer.py

@@ -7,7 +7,9 @@ from hapic.description import InputQueryDescription
 from hapic.description import InputBodyDescription
 from hapic.description import InputHeadersDescription
 from hapic.description import InputFormsDescription
+from hapic.description import InputFilesDescription
 from hapic.description import OutputBodyDescription
+from hapic.description import OutputFileDescription
 from hapic.description import OutputHeadersDescription
 from hapic.description import ErrorDescription
 from hapic.exception import AlreadyDecoratedException
@@ -74,6 +76,16 @@ class DecorationBuffer(object):
         self._description.input_forms = description
 
     @property
+    def input_files(self) -> InputFilesDescription:
+        return self._description.input_files
+
+    @input_files.setter
+    def input_files(self, description: InputFilesDescription) -> None:
+        if self._description.input_files is not None:
+            raise AlreadyDecoratedException()
+        self._description.input_files = description
+
+    @property
     def output_body(self) -> OutputBodyDescription:
         return self._description.output_body
 
@@ -84,6 +96,16 @@ class DecorationBuffer(object):
         self._description.output_body = description
 
     @property
+    def output_file(self) -> OutputFileDescription:
+        return self._description.output_file
+
+    @output_file.setter
+    def output_file(self, description: OutputFileDescription) -> None:
+        if self._description.output_file is not None:
+            raise AlreadyDecoratedException()
+        self._description.output_file = description
+
+    @property
     def output_headers(self) -> OutputHeadersDescription:
         return self._description.output_headers
 

hapic/context.py

@@ -1,13 +1,24 @@
 # -*- coding: utf-8 -*-
-import json
 import typing
 from http import HTTPStatus
 
-import bottle
+from hapic.processor import RequestParameters
+from hapic.processor import ProcessValidationError
 
-from hapic.exception import OutputValidationException
-# from hapic.hapic import _default_global_error_schema
-from hapic.processor import RequestParameters, ProcessValidationError
+if typing.TYPE_CHECKING:
+    from hapic.decorator import DecoratedController
+
+
+class RouteRepresentation(object):
+    def __init__(
+        self,
+        rule: str,
+        method: str,
+        original_route_object: typing.Any=None,
+    ) -> None:
+        self.rule = rule
+        self.method = method
+        self.original_route_object = original_route_object
 
 
 class ContextInterface(object):
@@ -27,3 +38,17 @@ class ContextInterface(object):
         http_code: HTTPStatus=HTTPStatus.BAD_REQUEST,
     ) -> typing.Any:
         raise NotImplementedError()
+
+    def find_route(
+        self,
+        decorated_controller: 'DecoratedController',
+    ) -> RouteRepresentation:
+        raise NotImplementedError()
+
+    def get_swagger_path(self, contextualised_rule: str) -> str:
+        """
+        Return OpenAPI path with context path
+        :param contextualised_rule: path of original context
+        :return: OpenAPI path
+        """
+        raise NotImplementedError()

hapic/data.py

@@ -8,3 +8,4 @@ class HapicData(object):
         self.query = {}
         self.headers = {}
         self.forms = {}
+        self.files = {}

hapic/decorator.py

@@ -6,6 +6,7 @@ from http import HTTPStatus
 # TODO BS 20171010: bottle specific !  # see #5
 import marshmallow
 from bottle import HTTPResponse
+from multidict import MultiDict
 
 from hapic.data import HapicData
 from hapic.description import ControllerDescription
@@ -44,6 +45,15 @@ class ControllerReference(object):
         self.wrapped = wrapped
         self.token = token
 
+    def get_doc_string(self) -> str:
+        if self.wrapper.__doc__:
+            return self.wrapper.__doc__.strip()
+
+        if self.wrapped.__doc__:
+            return self.wrapper.__doc__.strip()
+
+        return ''
+
 
 class ControllerWrapper(object):
     def before_wrapped_func(
@@ -150,6 +160,11 @@ class InputControllerWrapper(InputOutputControllerWrapper):
         self,
         request_parameters: RequestParameters,
     ) -> typing.Any:
+        parameters_data = self.get_parameters_data(request_parameters)
+        processed_data = self.processor.process(parameters_data)
+        return processed_data
+
+    def get_parameters_data(self, request_parameters: RequestParameters) -> dict:
         raise NotImplementedError()
 
     def update_hapic_data(
@@ -163,9 +178,8 @@ class InputControllerWrapper(InputOutputControllerWrapper):
         self,
         request_parameters: RequestParameters,
     ) -> typing.Any:
-        error = self.processor.get_validation_error(
-            request_parameters.body_parameters,
-        )
+        parameters_data = self.get_parameters_data(request_parameters)
+        error = self.processor.get_validation_error(parameters_data)
         error_response = self.context.get_validation_error_response(
             error,
             http_code=self.error_http_code,
@@ -249,6 +263,16 @@ class OutputHeadersControllerWrapper(OutputControllerWrapper):
     pass
 
 
+class OutputFileControllerWrapper(ControllerWrapper):
+    def __init__(
+        self,
+        output_types: typing.List[str],
+        default_http_code: HTTPStatus=HTTPStatus.OK,
+    ) -> None:
+        self.output_types = output_types
+        self.default_http_code = default_http_code
+
+
 class InputPathControllerWrapper(InputControllerWrapper):
     def update_hapic_data(
         self, hapic_data: HapicData,
@@ -256,31 +280,54 @@ class InputPathControllerWrapper(InputControllerWrapper):
     ) -> None:
         hapic_data.path = processed_data
 
-    def get_processed_data(
-        self,
-        request_parameters: RequestParameters,
-    ) -> typing.Any:
-        processed_data = self.processor.process(
-            request_parameters.path_parameters,
-        )
-        return processed_data
+    def get_parameters_data(self, request_parameters: RequestParameters) -> dict:  # nopep8
+        return request_parameters.path_parameters
 
 
 class InputQueryControllerWrapper(InputControllerWrapper):
+    def __init__(
+        self,
+        context: typing.Union[ContextInterface, typing.Callable[[], ContextInterface]],  # nopep8
+        processor: ProcessorInterface,
+        error_http_code: HTTPStatus=HTTPStatus.BAD_REQUEST,
+        default_http_code: HTTPStatus=HTTPStatus.OK,
+        as_list: typing.List[str]=None
+    ) -> None:
+        super().__init__(
+            context,
+            processor,
+            error_http_code,
+            default_http_code,
+        )
+        self.as_list = as_list or []  # FDV
+
     def update_hapic_data(
         self, hapic_data: HapicData,
         processed_data: typing.Any,
     ) -> None:
         hapic_data.query = processed_data
 
-    def get_processed_data(
-        self,
-        request_parameters: RequestParameters,
-    ) -> typing.Any:
-        processed_data = self.processor.process(
-            request_parameters.query_parameters,
-        )
-        return processed_data
+    def get_parameters_data(self, request_parameters: RequestParameters) -> MultiDict:  # nopep8
+        # Parameters are updated considering eventual as_list parameters
+        if self.as_list:
+            query_parameters = MultiDict()
+            for parameter_name in request_parameters.query_parameters.keys():
+                if parameter_name in query_parameters:
+                    continue
+
+                if parameter_name in self.as_list:
+                    query_parameters[parameter_name] = \
+                        request_parameters.query_parameters.getall(
+                            parameter_name,
+                        )
+                else:
+                    query_parameters[parameter_name] = \
+                        request_parameters.query_parameters.get(
+                            parameter_name,
+                        )
+            return query_parameters
+
+        return request_parameters.query_parameters
 
 
 class InputBodyControllerWrapper(InputControllerWrapper):
@@ -290,14 +337,8 @@ class InputBodyControllerWrapper(InputControllerWrapper):
     ) -> None:
         hapic_data.body = processed_data
 
-    def get_processed_data(
-        self,
-        request_parameters: RequestParameters,
-    ) -> typing.Any:
-        processed_data = self.processor.process(
-            request_parameters.body_parameters,
-        )
-        return processed_data
+    def get_parameters_data(self, request_parameters: RequestParameters) -> dict:  # nopep8
+        return request_parameters.body_parameters
 
 
 class InputHeadersControllerWrapper(InputControllerWrapper):
@@ -307,14 +348,8 @@ class InputHeadersControllerWrapper(InputControllerWrapper):
     ) -> None:
         hapic_data.headers = processed_data
 
-    def get_processed_data(
-        self,
-        request_parameters: RequestParameters,
-    ) -> typing.Any:
-        processed_data = self.processor.process(
-            request_parameters.header_parameters,
-        )
-        return processed_data
+    def get_parameters_data(self, request_parameters: RequestParameters) -> dict:  # nopep8
+        return request_parameters.header_parameters
 
 
 class InputFormsControllerWrapper(InputControllerWrapper):
@@ -324,14 +359,19 @@ class InputFormsControllerWrapper(InputControllerWrapper):
     ) -> None:
         hapic_data.forms = processed_data
 
-    def get_processed_data(
-        self,
-        request_parameters: RequestParameters,
-    ) -> typing.Any:
-        processed_data = self.processor.process(
-            request_parameters.form_parameters,
-        )
-        return processed_data
+    def get_parameters_data(self, request_parameters: RequestParameters) -> dict:  # nopep8
+        return request_parameters.form_parameters
+
+
+class InputFilesControllerWrapper(InputControllerWrapper):
+    def update_hapic_data(
+        self, hapic_data: HapicData,
+        processed_data: typing.Any,
+    ) -> None:
+        hapic_data.files = processed_data
+
+    def get_parameters_data(self, request_parameters: RequestParameters) -> dict:  # nopep8
+        return request_parameters.files_parameters
 
 
 class ExceptionHandlerControllerWrapper(ControllerWrapper):

hapic/description.py

@@ -27,14 +27,21 @@ class InputHeadersDescription(Description):
 
 
 class InputFormsDescription(Description):
-    def __init__(self, wrapper: 'ControllerWrapper') -> None:
-        self.wrapper = wrapper
+    pass
+
+
+class InputFilesDescription(Description):
+    pass
 
 
 class OutputBodyDescription(Description):
     pass
 
 
+class OutputFileDescription(Description):
+    pass
+
+
 class OutputHeadersDescription(Description):
     pass
 
@@ -51,7 +58,9 @@ class ControllerDescription(object):
         input_body: InputBodyDescription=None,
         input_headers: InputHeadersDescription=None,
         input_forms: InputFormsDescription=None,
+        input_files: InputFilesDescription=None,
         output_body: OutputBodyDescription=None,
+        output_file: OutputFileDescription=None,
         output_headers: OutputHeadersDescription=None,
         errors: typing.List[ErrorDescription]=None,
     ):
@@ -60,6 +69,8 @@ class ControllerDescription(object):
         self.input_body = input_body
         self.input_headers = input_headers
         self.input_forms = input_forms
+        self.input_files = input_files
         self.output_body = output_body
+        self.output_file = output_file
         self.output_headers = output_headers
         self.errors = errors or []

hapic/doc.py

@@ -1,54 +1,19 @@
 # -*- coding: utf-8 -*-
-import re
 import typing
 
-import bottle
 from apispec import APISpec
 from apispec import Path
 from apispec.ext.marshmallow.swagger import schema2jsonschema
 
+from hapic.context import ContextInterface
+from hapic.context import RouteRepresentation
 from hapic.decorator import DecoratedController
-from hapic.decorator import DECORATION_ATTRIBUTE_NAME
 from hapic.description import ControllerDescription
-from hapic.exception import NoRoutesException
-from hapic.exception import RouteNotFound
-
-# Bottle regular expression to locate url parameters
-BOTTLE_RE_PATH_URL = re.compile(r'<(?:[^:<>]+:)?([^<>]+)>')
-
-
-def find_bottle_route(
-    decorated_controller: DecoratedController,
-    app: bottle.Bottle,
-):
-    if not app.routes:
-        raise NoRoutesException('There is no routes in yout bottle app')
-
-    reference = decorated_controller.reference
-    for route in app.routes:
-        route_token = getattr(
-            route.callback,
-            DECORATION_ATTRIBUTE_NAME,
-            None,
-        )
-
-        match_with_wrapper = route.callback == reference.wrapper
-        match_with_wrapped = route.callback == reference.wrapped
-        match_with_token = route_token == reference.token
-
-        if match_with_wrapper or match_with_wrapped or match_with_token:
-            return route
-    # TODO BS 20171010: Raise exception or print error ? see #10
-    raise RouteNotFound(
-        'Decorated route "{}" was not found in bottle routes'.format(
-            decorated_controller.name,
-        )
-    )
 
 
 def bottle_generate_operations(
     spec,
-    bottle_route: bottle.Route,
+    route: RouteRepresentation,
     description: ControllerDescription,
 ):
     method_operations = dict()
@@ -74,6 +39,15 @@ def bottle_generate_operations(
                 }
             }
 
+    if description.output_file:
+        method_operations.setdefault('produces', []).extend(
+            description.output_file.wrapper.output_types
+        )
+        method_operations.setdefault('responses', {})\
+            [int(description.output_file.wrapper.default_http_code)] = {
+            'description': str(description.output_file.wrapper.default_http_code),  # nopep8
+        }
+
     if description.errors:
         for error in description.errors:
             schema_class = type(error.wrapper.schema)
@@ -109,8 +83,18 @@ def bottle_generate_operations(
                 'type': schema['type']
             })
 
+    if description.input_files:
+        method_operations.setdefault('consumes', []).append('multipart/form-data')
+        for field_name, field in description.input_files.wrapper.processor.schema.fields.items():
+            method_operations.setdefault('parameters', []).append({
+                'in': 'formData',
+                'name': field_name,
+                'required': field.required,
+                'type': 'file',
+            })
+
     operations = {
-        bottle_route.method.lower(): method_operations,
+        route.method.lower(): method_operations,
     }
 
     return operations
@@ -120,23 +104,16 @@ class DocGenerator(object):
     def get_doc(
         self,
         controllers: typing.List[DecoratedController],
-        app,
+        context: ContextInterface,
     ) -> dict:
-        # TODO: Découper, see #11
-        # TODO: bottle specific code !, see #11
-        if not app:
-            app = bottle.default_app()
-        else:
-            bottle.default_app.push(app)
-        flatten = lambda l: [item for sublist in l for item in sublist]
-
         spec = APISpec(
             title='Swagger Petstore',
             version='1.0.0',
             plugins=[
-                'apispec.ext.bottle',
+                # 'apispec.ext.bottle',
                 'apispec.ext.marshmallow',
             ],
+            schema_name_resolver_callable=generate_schema_name,
         )
 
         schemas = []
@@ -170,15 +147,21 @@ class DocGenerator(object):
         # with app.test_request_context():
         paths = {}
         for controller in controllers:
-            bottle_route = find_bottle_route(controller, app)
-            swagger_path = BOTTLE_RE_PATH_URL.sub(r'{\1}', bottle_route.rule)
+            route = context.find_route(controller)
+            swagger_path = context.get_swagger_path(route.rule)
 
             operations = bottle_generate_operations(
                 spec,
-                bottle_route,
+                route,
                 controller.description,
             )
 
+            # TODO BS 20171114: TMP code waiting refact of doc
+            doc_string = controller.reference.get_doc_string()
+            if doc_string:
+                for method in operations.keys():
+                    operations[method]['description'] = doc_string
+
             path = Path(path=swagger_path, operations=operations)
 
             if swagger_path in paths:
@@ -190,14 +173,7 @@ class DocGenerator(object):
 
         return spec.to_dict()
 
-        # route_by_callbacks = []
-        # routes = flatten(app.router.dyna_routes.values())
-        # for path, path_regex, route, func_ in routes:
-        #     route_by_callbacks.append(route.callback)
-        #
-        # for description in self._controllers:
-        #     for path, path_regex, route, func_ in routes:
-        #         if route.callback == description.reference:
-        #             # TODO: use description to feed apispec
-        #             print(route.method, path, description)
-        #             continue
+
+# TODO BS 20171109: Must take care of already existing definition names
+def generate_schema_name(schema):
+    return schema.__name__

hapic/exception.py

@@ -5,6 +5,10 @@ class HapicException(Exception):
     pass
 
 
+class ConfigurationException(HapicException):
+    pass
+
+
 class WorkflowException(HapicException):
     pass
 

hapic/ext/__init__.py

@@ -1,2 +1,4 @@
 # -*- coding: utf-8 -*-
-from hapic.ext import bottle,flask
+from hapic.ext import bottle
+from hapic.ext import pyramid
+from hapic.ext import flask

hapic/ext/bottle/context.py

@@ -1,23 +1,45 @@
 # -*- coding: utf-8 -*-
 import json
+import re
 import typing
 from http import HTTPStatus
 
 import bottle
+from multidict import MultiDict
 
 from hapic.context import ContextInterface
+from hapic.context import RouteRepresentation
+from hapic.decorator import DecoratedController
+from hapic.decorator import DECORATION_ATTRIBUTE_NAME
 from hapic.exception import OutputValidationException
-from hapic.processor import RequestParameters, ProcessValidationError
+from hapic.exception import NoRoutesException
+from hapic.exception import RouteNotFound
+from hapic.processor import RequestParameters
+from hapic.processor import ProcessValidationError
+
+# Bottle regular expression to locate url parameters
+BOTTLE_RE_PATH_URL = re.compile(r'<(?:[^:<>]+:)?([^<>]+)>')
 
 
 class BottleContext(ContextInterface):
+    def __init__(self, app: bottle.Bottle):
+        self.app = app
+
     def get_request_parameters(self, *args, **kwargs) -> RequestParameters:
+        path_parameters = dict(bottle.request.url_args)
+        query_parameters = MultiDict(bottle.request.query.allitems())
+        body_parameters = dict(bottle.request.json or {})
+        form_parameters = MultiDict(bottle.request.forms.allitems())
+        header_parameters = dict(bottle.request.headers)
+        files_parameters = dict(bottle.request.files)
+
         return RequestParameters(
-            path_parameters=bottle.request.url_args,
-            query_parameters=bottle.request.params,
-            body_parameters=bottle.request.json,
-            form_parameters=bottle.request.forms,
-            header_parameters=bottle.request.headers,
+            path_parameters=path_parameters,
+            query_parameters=query_parameters,
+            body_parameters=body_parameters,
+            form_parameters=form_parameters,
+            header_parameters=header_parameters,
+            files_parameters=files_parameters,
         )
 
     def get_response(
@@ -55,3 +77,38 @@ class BottleContext(ContextInterface):
             ],
             status=int(http_code),
         )
+
+    def find_route(
+        self,
+        decorated_controller: DecoratedController,
+    ) -> RouteRepresentation:
+        if not self.app.routes:
+            raise NoRoutesException('There is no routes in your bottle app')
+
+        reference = decorated_controller.reference
+        for route in self.app.routes:
+            route_token = getattr(
+                route.callback,
+                DECORATION_ATTRIBUTE_NAME,
+                None,
+            )
+
+            match_with_wrapper = route.callback == reference.wrapper
+            match_with_wrapped = route.callback == reference.wrapped
+            match_with_token = route_token == reference.token
+
+            if match_with_wrapper or match_with_wrapped or match_with_token:
+                return RouteRepresentation(
+                    rule=self.get_swagger_path(route.rule),
+                    method=route.method.lower(),
+                    original_route_object=route,
+                )
+        # TODO BS 20171010: Raise exception or print error ? see #10
+        raise RouteNotFound(
+            'Decorated route "{}" was not found in bottle routes'.format(
+                decorated_controller.name,
+            )
+        )
+
+    def get_swagger_path(self, contextualised_rule: str) -> str:
+        return BOTTLE_RE_PATH_URL.sub(r'{\1}', contextualised_rule)

hapic/ext/pyramid/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+from hapic.ext.pyramid.context import PyramidContext

hapic/ext/pyramid/context.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+import json
+import re
+import typing
+from http import HTTPStatus
+
+from hapic.context import ContextInterface
+from hapic.context import RouteRepresentation
+from hapic.decorator import DecoratedController
+from hapic.decorator import DECORATION_ATTRIBUTE_NAME
+from hapic.ext.bottle.context import BOTTLE_RE_PATH_URL
+from hapic.exception import OutputValidationException
+from hapic.processor import RequestParameters
+from hapic.processor import ProcessValidationError
+
+if typing.TYPE_CHECKING:
+    from pyramid.response import Response
+    from pyramid.config import Configurator
+
+# Bottle regular expression to locate url parameters
+PYRAMID_RE_PATH_URL = re.compile(r'')
+
+
+class PyramidContext(ContextInterface):
+    def __init__(self, configurator: 'Configurator'):
+        self.configurator = configurator
+
+    def get_request_parameters(self, *args, **kwargs) -> RequestParameters:
+        req = args[-1]  # TODO : Check
+        # TODO : move this code to check_json
+        # same idea as in : https://bottlepy.org/docs/dev/_modules/bottle.html#BaseRequest.json
+        if req.body and req.content_type in ('application/json', 'application/json-rpc'):
+            json_body = req.json_body
+            # TODO : raise exception if not correct , return 400 if uncorrect instead ?
+        else:
+            json_body = None
+
+        return RequestParameters(
+            path_parameters=req.matchdict,
+            query_parameters=req.GET,
+            body_parameters=json_body,
+            form_parameters=req.POST,
+            header_parameters=req.headers,
+        )
+
+    def get_response(
+        self,
+        response: dict,
+        http_code: int,
+    ) -> 'Response':
+        from pyramid.response import Response
+        return Response(
+            body=json.dumps(response),
+            headers=[
+                ('Content-Type', 'application/json'),
+            ],
+            status=http_code,
+        )
+
+    def get_validation_error_response(
+        self,
+        error: ProcessValidationError,
+        http_code: HTTPStatus=HTTPStatus.BAD_REQUEST,
+    ) -> typing.Any:
+        # TODO BS 20171010: Manage error schemas, see #4
+        from pyramid.response import Response
+        from hapic.hapic import _default_global_error_schema
+        unmarshall = _default_global_error_schema.dump(error)
+        if unmarshall.errors:
+            raise OutputValidationException(
+                'Validation error during dump of error response: {}'.format(
+                    str(unmarshall.errors)
+                )
+            )
+
+        return Response(
+            body=json.dumps(unmarshall.data),
+            headers=[
+                ('Content-Type', 'application/json'),
+            ],
+            status=int(http_code),
+        )
+
+    def find_route(
+        self,
+        decorated_controller: DecoratedController,
+    ) -> RouteRepresentation:
+        for category in self.configurator.introspector.get_category('views'):
+            view_intr = category['introspectable']
+            route_intr = category['related']
+
+            reference = decorated_controller.reference
+            route_token = getattr(
+                view_intr.get('callable'),
+                DECORATION_ATTRIBUTE_NAME,
+                None,
+            )
+
+            match_with_wrapper = view_intr.get('callable') == reference.wrapper
+            match_with_wrapped = view_intr.get('callable') == reference.wrapped
+            match_with_token = route_token == reference.token
+
+            if match_with_wrapper or match_with_wrapped or match_with_token:
+                # TODO BS 20171107: C'est une liste de route sous pyramid !!!
+                # Mais de toute maniere les framework womme pyramid, flask
+                # peuvent avoir un controlleur pour plusieurs routes doc
+                # .find_route doit retourner une liste au lieu d'une seule
+                # route
+                route_pattern = route_intr[0].get('pattern')
+                route_method = route_intr[0].get('request_methods')[0]
+
+                return RouteRepresentation(
+                    rule=self.get_swagger_path(route_pattern),
+                    method=route_method,
+                    original_route_object=route_intr[0],
+                )
+
+    def get_swagger_path(self, contextualised_rule: str) -> str:
+        # TODO BS 20171110: Pyramid allow route like '/{foo:\d+}', so adapt
+        # and USE regular expression (see https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/urldispatch.html#custom-route-predicates)  # nopep8
+        return contextualised_rule

hapic/hapic.py

@@ -16,19 +16,24 @@ from hapic.decorator import InputBodyControllerWrapper
 from hapic.decorator import InputHeadersControllerWrapper
 from hapic.decorator import InputPathControllerWrapper
 from hapic.decorator import InputQueryControllerWrapper
+from hapic.decorator import InputFilesControllerWrapper
 from hapic.decorator import OutputBodyControllerWrapper
 from hapic.decorator import OutputHeadersControllerWrapper
+from hapic.decorator import OutputFileControllerWrapper
 from hapic.description import InputBodyDescription
 from hapic.description import ErrorDescription
 from hapic.description import InputFormsDescription
 from hapic.description import InputHeadersDescription
 from hapic.description import InputPathDescription
 from hapic.description import InputQueryDescription
+from hapic.description import InputFilesDescription
 from hapic.description import OutputBodyDescription
 from hapic.description import OutputHeadersDescription
+from hapic.description import OutputFileDescription
 from hapic.doc import DocGenerator
 from hapic.processor import ProcessorInterface
 from hapic.processor import MarshmallowInputProcessor
+from hapic.processor import MarshmallowInputFilesProcessor
 from hapic.processor import MarshmallowOutputProcessor
 
 
@@ -50,6 +55,7 @@ class Hapic(object):
         self._buffer = DecorationBuffer()
         self._controllers = []  # type: typing.List[DecoratedController]
         self._context = None  # type: ContextInterface
+        self.doc_generator = DocGenerator()
 
         # This local function will be pass to different components
         # who will need context but declared (like with decorator)
@@ -148,6 +154,23 @@ class Hapic(object):
             return decoration.get_wrapper(func)
         return decorator
 
+    # TODO BS 20171102: Think about possibilities to validate output ?
+    # (with mime type, or validator)
+    def output_file(
+        self,
+        output_types: typing.List[str],
+        default_http_code: HTTPStatus = HTTPStatus.OK,
+    ) -> typing.Callable[[typing.Callable[..., typing.Any]], typing.Any]:
+        decoration = OutputFileControllerWrapper(
+            output_types=output_types,
+            default_http_code=default_http_code,
+        )
+
+        def decorator(func):
+            self._buffer.output_file = OutputFileDescription(decoration)
+            return decoration.get_wrapper(func)
+        return decorator
+
     def input_headers(
         self,
         schema: typing.Any,
@@ -203,6 +226,7 @@ class Hapic(object):
         context: ContextInterface = None,
         error_http_code: HTTPStatus = HTTPStatus.BAD_REQUEST,
         default_http_code: HTTPStatus = HTTPStatus.OK,
+        as_list: typing.List[str]=None,
     ) -> typing.Callable[[typing.Callable[..., typing.Any]], typing.Any]:
         processor = processor or MarshmallowInputProcessor()
         processor.schema = schema
@@ -213,6 +237,7 @@ class Hapic(object):
             processor=processor,
             error_http_code=error_http_code,
             default_http_code=default_http_code,
+            as_list=as_list,
         )
 
         def decorator(func):
@@ -268,6 +293,30 @@ class Hapic(object):
             return decoration.get_wrapper(func)
         return decorator
 
+    def input_files(
+        self,
+        schema: typing.Any,
+        processor: ProcessorInterface=None,
+        context: ContextInterface=None,
+        error_http_code: HTTPStatus = HTTPStatus.BAD_REQUEST,
+        default_http_code: HTTPStatus = HTTPStatus.OK,
+    ) -> typing.Callable[[typing.Callable[..., typing.Any]], typing.Any]:
+        processor = processor or MarshmallowInputFilesProcessor()
+        processor.schema = schema
+        context = context or self._context_getter
+
+        decoration = InputFilesControllerWrapper(
+            context=context,
+            processor=processor,
+            error_http_code=error_http_code,
+            default_http_code=default_http_code,
+        )
+
+        def decorator(func):
+            self._buffer.input_files = InputFilesDescription(decoration)
+            return decoration.get_wrapper(func)
+        return decorator
+
     def handle_exception(
         self,
         handled_exception_class: typing.Type[Exception],
@@ -289,10 +338,5 @@ class Hapic(object):
             return decoration.get_wrapper(func)
         return decorator
 
-    def generate_doc(self, app):
-        # FIXME: j'ai du tricher avec app, see #11
-        # FIXME @Damien bottle specific code ! see #11
-        # rendre ca generique
-        app = app or self._context.get_app()
-        doc_generator = DocGenerator()
-        return doc_generator.get_doc(self._controllers, app)
+    def generate_doc(self):
+        return self.doc_generator.get_doc(self._controllers, self.context)

hapic/processor.py

@@ -1,23 +1,57 @@
 # -*- coding: utf-8 -*-
 import typing
 
-from hapic.exception import InputValidationException, OutputValidationException
+from multidict import MultiDict
+
+from hapic.exception import OutputValidationException
+from hapic.exception import ConfigurationException
 
 
 class RequestParameters(object):
     def __init__(
         self,
-        path_parameters,
-        query_parameters,
-        body_parameters,
-        form_parameters,
-        header_parameters,
+        path_parameters: dict,
+        query_parameters: MultiDict,
+        body_parameters: dict,
+        form_parameters: MultiDict,
+        header_parameters: dict,
+        files_parameters: dict,
     ):
+        """
+        :param path_parameters: Parameters found in path, example:
+            (for '/users/<user_id>') '/users/42' =>{'user_id': '42'}
+
+        :param query_parameters: Parameters found in query, example:
+            '/foo?group_id=1&group_id=2&deleted=false' => MultiDict(
+                (
+                    ('group_id', '1'),
+                    ('group_id', '2'),
+                    ('deleted', 'false'),
+                )
+            )
+
+        :param body_parameters: Body content in dict format, example:
+            JSON body '{"user": {"name":"bob"}}' => {'user': {'name':'bob'}}
+
+        :param form_parameters: Form parameters, example:
+            <input type="text" name="name" value="bob"/> => {'name': 'bob'}
+
+        :param header_parameters: headers in dict format, example:
+            Connection: keep-alive
+            Content-Type: text/plain => {
+                                            'Connection': 'keep-alive',
+                                            'Content-Type': 'text/plain',
+                                        }
+
+        :param files_parameters: TODO BS 20171113: Specify type of file
+        storage ?
+        """
         self.path_parameters = path_parameters
         self.query_parameters = query_parameters
         self.body_parameters = body_parameters
         self.form_parameters = form_parameters
         self.header_parameters = header_parameters
+        self.files_parameters = files_parameters
 
 
 class ProcessValidationError(object):
@@ -32,7 +66,17 @@ class ProcessValidationError(object):
 
 class ProcessorInterface(object):
     def __init__(self):
-        self.schema = None
+        self._schema = None
+
+    @property
+    def schema(self):
+        if not self._schema:
+            raise ConfigurationException('Schema not set for processor {}'.format(str(self)))
+        return self._schema
+
+    @schema.setter
+    def schema(self, schema):
+        self._schema = schema
 
     def process(self, value):
         raise NotImplementedError
@@ -108,3 +152,60 @@ class MarshmallowInputProcessor(InputProcessor):
             message='Validation error of input data',
             details=marshmallow_errors,
         )
+
+
+class MarshmallowInputFilesProcessor(MarshmallowInputProcessor):
+    def process(self, data: dict):
+        clean_data = self.clean_data(data)
+        unmarshall = self.schema.load(clean_data)
+        additional_errors = self._get_files_errors(unmarshall.data)
+
+        if unmarshall.errors:
+            raise OutputValidationException(
+                'Error when validate ouput: {}'.format(
+                    str(unmarshall.errors),
+                )
+            )
+
+        if additional_errors:
+            raise OutputValidationException(
+                'Error when validate ouput: {}'.format(
+                    str(additional_errors),
+                )
+            )
+
+        return unmarshall.data
+
+    def get_validation_error(self, data: dict) -> ProcessValidationError:
+        clean_data = self.clean_data(data)
+        unmarshall = self.schema.load(clean_data)
+        marshmallow_errors = unmarshall.errors
+        additional_errors = self._get_files_errors(unmarshall.data)
+
+        if marshmallow_errors:
+            return ProcessValidationError(
+                message='Validation error of input data',
+                details=marshmallow_errors,
+            )
+
+        if additional_errors:
+            return ProcessValidationError(
+                message='Validation error of input data',
+                details=additional_errors,
+            )
+
+    def _get_files_errors(self, validated_data: dict) -> typing.Dict[str, str]:
+        """
+        Additional check of data
+        :param validated_data: previously validated data by marshmallow schema
+        :return: list of error if any
+        """
+        errors = {}
+
+        for field_name, field in self.schema.fields.items():
+            # Actually just check if value not empty
+            # TODO BS 20171102: Think about case where test file content is more complicated
+            if field.required and (field_name not in validated_data or not validated_data[field_name]):
+                errors.setdefault(field_name, []).append('Missing data for required field')
+
+        return errors

setup.py

@@ -11,11 +11,18 @@ install_requires = [
     # TODO: marshmallow an extension too ? see #2
     'bottle',
     'marshmallow',
-    'apispec',
+    'apispec==0.25.4-algoo',
+    'multidict'
+]
+dependency_links = [
+    'git+https://github.com/algoo/apispec.git@dev-algoo#egg=apispec-0.25.4-algoo'  # nopep8
 ]
 tests_require = [
     'pytest',
 ]
+dev_require = [
+    'requests',
+]
 
 setup(
     name='hapic',
@@ -23,14 +30,14 @@ setup(
     # Versions should comply with PEP440.  For a discussion on single-sourcing
     # the version across setup.py and the project code, see
     # https://packaging.python.org/en/latest/single_source_version.html
-    version='0.4.2',
+    version='0.14',
 
     description='HTTP api input/output manager',
     # long_description=long_description,
     long_description='',
 
     # The project's main homepage.
-    url='http://gitlab.algoo.fr:10080/algoo/hapic.git',
+    url='https://github.com/algoo/hapic',
 
     # Author details
     author='Algoo Development Team',
@@ -55,6 +62,7 @@ setup(
     # requirements files see:
     # https://packaging.python.org/en/latest/requirements.html
     install_requires=install_requires,
+    dependency_links=dependency_links,
 
     # List additional groups of dependencies here (e.g. development
     # dependencies). You can install these using the following syntax,
@@ -62,6 +70,7 @@ setup(
     # $ pip install -e ".[test]"
     extras_require={
         'test': tests_require,
+        'dev': dev_require,
     },
 
     # If there are data files included in your packages that need to be

tests/base.py

@@ -1,4 +1,64 @@
 # -*- coding: utf-8 -*-
+import typing
+from http import HTTPStatus
+
+from multidict import MultiDict
+
+from hapic.ext.bottle import BottleContext
+from hapic.processor import RequestParameters
+from hapic.processor import ProcessValidationError
+
 
 class Base(object):
     pass
+
+
+# TODO BS 20171105: Make this bottle agnostic !
+class MyContext(BottleContext):
+    def __init__(
+        self,
+        app,
+        fake_path_parameters=None,
+        fake_query_parameters=None,
+        fake_body_parameters=None,
+        fake_form_parameters=None,
+        fake_header_parameters=None,
+        fake_files_parameters=None,
+    ) -> None:
+        super().__init__(app=app)
+        self.fake_path_parameters = fake_path_parameters or {}
+        self.fake_query_parameters = fake_query_parameters or MultiDict()
+        self.fake_body_parameters = fake_body_parameters or {}
+        self.fake_form_parameters = fake_form_parameters or MultiDict()
+        self.fake_header_parameters = fake_header_parameters or {}
+        self.fake_files_parameters = fake_files_parameters or {}
+
+    def get_request_parameters(self, *args, **kwargs) -> RequestParameters:
+        return RequestParameters(
+            path_parameters=self.fake_path_parameters,
+            query_parameters=self.fake_query_parameters,
+            body_parameters=self.fake_body_parameters,
+            form_parameters=self.fake_form_parameters,
+            header_parameters=self.fake_header_parameters,
+            files_parameters=self.fake_files_parameters,
+        )
+
+    def get_response(
+        self,
+        response: dict,
+        http_code: int,
+    ) -> typing.Any:
+        return {
+            'original_response': response,
+            'http_code': http_code,
+        }
+
+    def get_validation_error_response(
+        self,
+        error: ProcessValidationError,
+        http_code: HTTPStatus=HTTPStatus.BAD_REQUEST,
+    ) -> typing.Any:
+        return {
+            'original_error': error,
+            'http_code': http_code,
+        }

tests/ext/unit/test_bottle.py

@@ -2,16 +2,15 @@
 import bottle
 
 import hapic
-from hapic.doc import find_bottle_route
 from tests.base import Base
 
 
 class TestBottleExt(Base):
     def test_unit__map_binding__ok__decorated_function(self):
         hapic_ = hapic.Hapic()
-        hapic_.set_context(hapic.ext.bottle.BottleContext())
-
         app = bottle.Bottle()
+        context = hapic.ext.bottle.BottleContext(app=app)
+        hapic_.set_context(context)
 
         @hapic_.with_api_doc()
         @app.route('/')
@@ -20,18 +19,18 @@ class TestBottleExt(Base):
 
         assert hapic_.controllers
         decoration = hapic_.controllers[0]
-        route = find_bottle_route(decoration, app)
+        route = context.find_route(decoration)
 
         assert route
-        assert route.callback != controller_a
-        assert route.callback == decoration.reference.wrapped
-        assert route.callback != decoration.reference.wrapper
+        assert route.original_route_object.callback != controller_a
+        assert route.original_route_object.callback == decoration.reference.wrapped  # nopep8
+        assert route.original_route_object.callback != decoration.reference.wrapper  # nopep8
 
     def test_unit__map_binding__ok__mapped_function(self):
         hapic_ = hapic.Hapic()
-        hapic_.set_context(hapic.ext.bottle.BottleContext())
-
         app = bottle.Bottle()
+        context = hapic.ext.bottle.BottleContext(app=app)
+        hapic_.set_context(context)
 
         @hapic_.with_api_doc()
         def controller_a():
@@ -41,18 +40,18 @@ class TestBottleExt(Base):
 
         assert hapic_.controllers
         decoration = hapic_.controllers[0]
-        route = find_bottle_route(decoration, app)
+        route = context.find_route(decoration)
 
         assert route
-        assert route.callback == controller_a
-        assert route.callback == decoration.reference.wrapper
-        assert route.callback != decoration.reference.wrapped
+        assert route.original_route_object.callback == controller_a
+        assert route.original_route_object.callback == decoration.reference.wrapper  # nopep8
+        assert route.original_route_object.callback != decoration.reference.wrapped  # nopep8
 
     def test_unit__map_binding__ok__mapped_method(self):
         hapic_ = hapic.Hapic()
-        hapic_.set_context(hapic.ext.bottle.BottleContext())
-
         app = bottle.Bottle()
+        context = hapic.ext.bottle.BottleContext(app=app)
+        hapic_.set_context(context)
 
         class MyControllers(object):
             def bind(self, app):
@@ -67,11 +66,11 @@ class TestBottleExt(Base):
 
         assert hapic_.controllers
         decoration = hapic_.controllers[0]
-        route = find_bottle_route(decoration, app)
+        route = context.find_route(decoration)
 
         assert route
         # Important note: instance controller_a method is
         # not class controller_a, so no matches with callbacks
-        assert route.callback != MyControllers.controller_a
-        assert route.callback != decoration.reference.wrapped
-        assert route.callback != decoration.reference.wrapper
+        assert route.original_route_object.callback != MyControllers.controller_a  # nopep8
+        assert route.original_route_object.callback != decoration.reference.wrapped  # nopep8
+        assert route.original_route_object.callback != decoration.reference.wrapper  # nopep8

tests/func/__init__.py

@@ -0,0 +1 @@
+# coding: utf-8

tests/func/test_doc.py

@@ -0,0 +1,149 @@
+# coding: utf-8
+import marshmallow
+import bottle
+
+from hapic import Hapic
+from tests.base import Base
+from tests.base import MyContext
+
+
+class TestDocGeneration(Base):
+    def test_func__input_files_doc__ok__one_file(self):
+        hapic = Hapic()
+        app = bottle.Bottle()
+        hapic.set_context(MyContext(app=app))
+
+        class MySchema(marshmallow.Schema):
+            file_abc = marshmallow.fields.Raw(required=True)
+
+        @hapic.with_api_doc()
+        @hapic.input_files(MySchema())
+        def my_controller(hapic_data=None):
+            assert hapic_data
+            assert hapic_data.files
+
+        app.route('/upload', method='POST', callback=my_controller)
+        doc = hapic.generate_doc()
+
+        assert doc
+        assert '/upload' in doc['paths']
+        assert 'consumes' in doc['paths']['/upload']['post']
+        assert 'multipart/form-data' in doc['paths']['/upload']['post']['consumes']  # nopep8
+        assert 'parameters' in doc['paths']['/upload']['post']
+        assert {
+                   'name': 'file_abc',
+                   'required': True,
+                   'in': 'formData',
+                   'type': 'file',
+               } in doc['paths']['/upload']['post']['parameters']
+
+    def test_func__input_files_doc__ok__two_file(self):
+        hapic = Hapic()
+        app = bottle.Bottle()
+        hapic.set_context(MyContext(app=app))
+
+        class MySchema(marshmallow.Schema):
+            file_abc = marshmallow.fields.Raw(required=True)
+            file_def = marshmallow.fields.Raw(required=False)
+
+        @hapic.with_api_doc()
+        @hapic.input_files(MySchema())
+        def my_controller(hapic_data=None):
+            assert hapic_data
+            assert hapic_data.files
+
+        app.route('/upload', method='POST', callback=my_controller)
+        doc = hapic.generate_doc()
+
+        assert doc
+        assert '/upload' in doc['paths']
+        assert 'consumes' in doc['paths']['/upload']['post']
+        assert 'multipart/form-data' in doc['paths']['/upload']['post']['consumes']  # nopep8
+        assert 'parameters' in doc['paths']['/upload']['post']
+        assert {
+                   'name': 'file_abc',
+                   'required': True,
+                   'in': 'formData',
+                   'type': 'file',
+               } in doc['paths']['/upload']['post']['parameters']
+        assert {
+                   'name': 'file_def',
+                   'required': False,
+                   'in': 'formData',
+                   'type': 'file',
+               } in doc['paths']['/upload']['post']['parameters']
+
+    def test_func__output_file_doc__ok__nominal_case(self):
+        hapic = Hapic()
+        app = bottle.Bottle()
+        hapic.set_context(MyContext(app=app))
+
+        @hapic.with_api_doc()
+        @hapic.output_file(['image/jpeg'])
+        def my_controller():
+            return b'101010100101'
+
+        app.route('/avatar', method='GET', callback=my_controller)
+        doc = hapic.generate_doc()
+
+        assert doc
+        assert '/avatar' in doc['paths']
+        assert 'produces' in doc['paths']['/avatar']['get']
+        assert 'image/jpeg' in doc['paths']['/avatar']['get']['produces']
+        assert 200 in doc['paths']['/avatar']['get']['responses']
+
+    def test_func__input_files_doc__ok__one_file_and_text(self):
+        hapic = Hapic()
+        app = bottle.Bottle()
+        hapic.set_context(MyContext(app=app))
+
+        class MySchema(marshmallow.Schema):
+            name = marshmallow.fields.String(required=True)
+
+        class MyFilesSchema(marshmallow.Schema):
+            file_abc = marshmallow.fields.Raw(required=True)
+
+        @hapic.with_api_doc()
+        @hapic.input_files(MyFilesSchema())
+        @hapic.input_body(MySchema())
+        def my_controller(hapic_data=None):
+            assert hapic_data
+            assert hapic_data.files
+
+        app.route('/upload', method='POST', callback=my_controller)
+        doc = hapic.generate_doc()
+
+        assert doc
+        assert '/upload' in doc['paths']
+        assert 'consumes' in doc['paths']['/upload']['post']
+        assert 'multipart/form-data' in doc['paths']['/upload']['post']['consumes']  # nopep8
+        assert 'parameters' in doc['paths']['/upload']['post']
+        assert {
+                   'name': 'file_abc',
+                   'required': True,
+                   'in': 'formData',
+                   'type': 'file',
+               } in doc['paths']['/upload']['post']['parameters']
+
+    def test_func__docstring__ok__simple_case(self):
+        hapic = Hapic()
+        app = bottle.Bottle()
+        hapic.set_context(MyContext(app=app))
+
+        # TODO BS 20171113: Make this test non-bottle
+        @hapic.with_api_doc()
+        def my_controller(hapic_data=None):
+            """
+            Hello doc
+            """
+            assert hapic_data
+            assert hapic_data.files
+
+        app.route('/upload', method='POST', callback=my_controller)
+        doc = hapic.generate_doc()
+
+        assert doc.get('paths')
+        assert '/upload' in doc['paths']
+        assert 'post' in doc['paths']['/upload']
+        assert 'description' in doc['paths']['/upload']['post']
+        assert 'Hello doc' == doc['paths']['/upload']['post']['description']

tests/func/test_marshmallow_decoration.py

@@ -0,0 +1,82 @@
+# coding: utf-8
+from http import HTTPStatus
+
+import marshmallow
+
+from hapic import Hapic
+from tests.base import Base
+from tests.base import MyContext
+
+
+class TestMarshmallowDecoration(Base):
+    def test_unit__input_files__ok__file_is_present(self):
+        hapic = Hapic()
+        hapic.set_context(MyContext(
+            app=None,
+            fake_files_parameters={
+                'file_abc': '10101010101',
+            }
+        ))
+
+        class MySchema(marshmallow.Schema):
+            file_abc = marshmallow.fields.Raw(required=True)
+
+        @hapic.with_api_doc()
+        @hapic.input_files(MySchema())
+        def my_controller(hapic_data=None):
+            assert hapic_data
+            assert hapic_data.files
+            return 'OK'
+
+        result = my_controller()
+        assert 'OK' == result
+
+    def test_unit__input_files__ok__file_is_not_present(self):
+        hapic = Hapic()
+        hapic.set_context(MyContext(
+            app=None,
+            fake_files_parameters={
+                # No file here
+            }
+        ))
+
+        class MySchema(marshmallow.Schema):
+            file_abc = marshmallow.fields.Raw(required=True)
+
+        @hapic.with_api_doc()
+        @hapic.input_files(MySchema())
+        def my_controller(hapic_data=None):
+            assert hapic_data
+            assert hapic_data.files
+            return 'OK'
+
+        result = my_controller()
+        assert 'http_code' in result
+        assert HTTPStatus.BAD_REQUEST == result['http_code']
+        assert {
+                   'file_abc': ['Missing data for required field.']
+               } == result['original_error'].details
+
+    def test_unit__input_files__ok__file_is_empty_string(self):
+        hapic = Hapic()
+        hapic.set_context(MyContext(
+            app=None,
+            fake_files_parameters={
+                'file_abc': '',
+            }
+        ))
+
+        class MySchema(marshmallow.Schema):
+            file_abc = marshmallow.fields.Raw(required=True)
+
+        @hapic.with_api_doc()
+        @hapic.input_files(MySchema())
+        def my_controller(hapic_data=None):
+            assert hapic_data
+            assert hapic_data.files
+            return 'OK'
+
+        result = my_controller()
+        assert 'http_code' in result
+        assert HTTPStatus.BAD_REQUEST == result['http_code']
+        assert {'file_abc': ['Missing data for required field']} == result['original_error'].details

tests/unit/test_decorator.py

@@ -3,55 +3,42 @@ import typing
 from http import HTTPStatus
 
 import marshmallow
+from multidict import MultiDict
 
-from hapic.context import ContextInterface
 from hapic.data import HapicData
-from hapic.decorator import InputOutputControllerWrapper
 from hapic.decorator import ExceptionHandlerControllerWrapper
+from hapic.decorator import InputQueryControllerWrapper
 from hapic.decorator import InputControllerWrapper
+from hapic.decorator import InputOutputControllerWrapper
 from hapic.decorator import OutputControllerWrapper
 from hapic.hapic import ErrorResponseSchema
-from hapic.processor import RequestParameters
 from hapic.processor import MarshmallowOutputProcessor
 from hapic.processor import ProcessValidationError
 from hapic.processor import ProcessorInterface
+from hapic.processor import RequestParameters
 from tests.base import Base
+from tests.base import MyContext
 
 
-class MyContext(ContextInterface):
-    def get_request_parameters(self, *args, **kwargs) -> RequestParameters:
-        return RequestParameters(
-            path_parameters={'fake': args},
-            query_parameters={},
-            body_parameters={},
-            form_parameters={},
-            header_parameters={},
-        )
-
-    def get_response(
-        self,
-        response: dict,
-        http_code: int,
-    ) -> typing.Any:
-        return {
-            'original_response': response,
-            'http_code': http_code,
-        }
+class MyProcessor(ProcessorInterface):
+    def process(self, value):
+        return value + 1
 
-    def get_validation_error_response(
+    def get_validation_error(
         self,
-        error: ProcessValidationError,
-        http_code: HTTPStatus=HTTPStatus.BAD_REQUEST,
-    ) -> typing.Any:
-        return {
-            'original_error': error,
-            'http_code': http_code,
-        }
+        request_context: RequestParameters,
+    ) -> ProcessValidationError:
+        return ProcessValidationError(
+            details={
+                'original_request_context': request_context,
+            },
+            message='ERROR',
+        )
 
 
-class MyProcessor(ProcessorInterface):
+class MySimpleProcessor(ProcessorInterface):
     def process(self, value):
-        return value + 1
+        return value
 
     def get_validation_error(
         self,
@@ -82,12 +69,12 @@ class MyControllerWrapper(InputOutputControllerWrapper):
         return response * 2
 
 
-class MyInputControllerWrapper(InputControllerWrapper):
+class MyInputQueryControllerWrapper(InputControllerWrapper):
     def get_processed_data(
         self,
         request_parameters: RequestParameters,
     ) -> typing.Any:
-        return {'we_are_testing': request_parameters.path_parameters}
+        return request_parameters.query_parameters
 
     def update_hapic_data(
         self,
@@ -103,7 +90,7 @@ class MySchema(marshmallow.Schema):
 
 class TestControllerWrapper(Base):
     def test_unit__base_controller_wrapper__ok__no_behaviour(self):
-        context = MyContext()
+        context = MyContext(app=None)
         processor = MyProcessor()
         wrapper = InputOutputControllerWrapper(context, processor)
 
@@ -115,7 +102,7 @@ class TestControllerWrapper(Base):
         assert result == 42
 
     def test_unit__base_controller__ok__replaced_response(self):
-        context = MyContext()
+        context = MyContext(app=None)
         processor = MyProcessor()
         wrapper = MyControllerWrapper(context, processor)
 
@@ -129,7 +116,7 @@ class TestControllerWrapper(Base):
         assert {'error_response': 'we are testing'} == result
 
     def test_unit__controller_wrapper__ok__overload_input(self):
-        context = MyContext()
+        context = MyContext(app=None)
         processor = MyProcessor()
         wrapper = MyControllerWrapper(context, processor)
 
@@ -146,25 +133,87 @@ class TestControllerWrapper(Base):
 
 class TestInputControllerWrapper(Base):
     def test_unit__input_data_wrapping__ok__nominal_case(self):
-        context = MyContext()
+        context = MyContext(
+            app=None,
+            fake_query_parameters=MultiDict(
+                (
+                    ('foo', 'bar',),
+                )
+            )
+        )
         processor = MyProcessor()
-        wrapper = MyInputControllerWrapper(context, processor)
+        wrapper = MyInputQueryControllerWrapper(context, processor)
 
         @wrapper.get_wrapper
         def func(foo, hapic_data=None):
             assert hapic_data
             assert isinstance(hapic_data, HapicData)
             # see MyControllerWrapper#before_wrapped_func
-            assert hapic_data.query == {'we_are_testing': {'fake': (42,)}}
+            assert hapic_data.query == {'foo': 'bar'}
             return foo
 
         result = func(42)
         assert result == 42
 
+    def test_unit__multi_query_param_values__ok__use_as_list(self):
+        context = MyContext(
+            app=None,
+            fake_query_parameters=MultiDict(
+                (
+                    ('user_id', 'abc'),
+                    ('user_id', 'def'),
+                ),
+            )
+        )
+        processor = MySimpleProcessor()
+        wrapper = InputQueryControllerWrapper(
+            context,
+            processor,
+            as_list=['user_id'],
+        )
+
+        @wrapper.get_wrapper
+        def func(hapic_data=None):
+            assert hapic_data
+            assert isinstance(hapic_data, HapicData)
+            # see MyControllerWrapper#before_wrapped_func
+            assert ['abc', 'def'] == hapic_data.query.get('user_id')
+            return hapic_data.query.get('user_id')
+
+        result = func()
+        assert result == ['abc', 'def']
+
+    def test_unit__multi_query_param_values__ok__without_as_list(self):
+        context = MyContext(
+            app=None,
+            fake_query_parameters=MultiDict(
+                (
+                    ('user_id', 'abc'),
+                    ('user_id', 'def'),
+                ),
+            )
+        )
+        processor = MySimpleProcessor()
+        wrapper = InputQueryControllerWrapper(
+            context,
+            processor,
+        )
+
+        @wrapper.get_wrapper
+        def func(hapic_data=None):
+            assert hapic_data
+            assert isinstance(hapic_data, HapicData)
+            # see MyControllerWrapper#before_wrapped_func
+            assert 'abc' == hapic_data.query.get('user_id')
+            return hapic_data.query.get('user_id')
+
+        result = func()
+        assert result == 'abc'
+
 
 class TestOutputControllerWrapper(Base):
     def test_unit__output_data_wrapping__ok__nominal_case(self):
-        context = MyContext()
+        context = MyContext(app=None)
         processor = MyProcessor()
         wrapper = OutputControllerWrapper(context, processor)
 
@@ -182,7 +231,7 @@ class TestOutputControllerWrapper(Base):
                } == result
 
     def test_unit__output_data_wrapping__fail__error_response(self):
-        context = MyContext()
+        context = MyContext(app=None)
         processor = MarshmallowOutputProcessor()
         processor.schema = MySchema()
         wrapper = OutputControllerWrapper(context, processor)
@@ -204,7 +253,7 @@ class TestOutputControllerWrapper(Base):
 
 class TestExceptionHandlerControllerWrapper(Base):
     def test_unit__exception_handled__ok__nominal_case(self):
-        context = MyContext()
+        context = MyContext(app=None)
         wrapper = ExceptionHandlerControllerWrapper(
             ZeroDivisionError,
             context,
@@ -232,7 +281,7 @@ class TestExceptionHandlerControllerWrapper(Base):
                 super().__init__(*args, **kwargs)
                 self.error_dict = {}
 
-        context = MyContext()
+        context = MyContext(app=None)
         wrapper = ExceptionHandlerControllerWrapper(
             MyException,
             context,