Merge branch 'master' into feature/pyramid_and_generic_doc_generation

.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

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()
 

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/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

@@ -19,7 +19,7 @@ def find_bottle_route(
     app: bottle.Bottle,
 ):
     if not app.routes:
-        raise NoRoutesException('There is no routes in yout bottle app')
+        raise NoRoutesException('There is no routes in your bottle app')
 
     reference = decorated_controller.reference
     for route in app.routes:
@@ -71,6 +71,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)
@@ -106,6 +115,16 @@ 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 = {
         route.method.lower(): method_operations,
     }
@@ -126,6 +145,7 @@ class DocGenerator(object):
                 # 'apispec.ext.bottle',
                 'apispec.ext.marshmallow',
             ],
+            schema_name_resolver_callable=generate_schema_name,
         )
 
         schemas = []
@@ -168,6 +188,12 @@ class DocGenerator(object):
                 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:
@@ -178,3 +204,8 @@ class DocGenerator(object):
             spec.add_path(path)
 
         return spec.to_dict()
+
+
+# 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/bottle/context.py

@@ -5,6 +5,7 @@ import typing
 from http import HTTPStatus
 
 import bottle
+from multidict import MultiDict
 
 from hapic.context import ContextInterface
 from hapic.exception import OutputValidationException
@@ -16,12 +17,20 @@ BOTTLE_RE_PATH_URL = re.compile(r'<(?:[^:<>]+:)?([^<>]+)>')
 
 class BottleContext(ContextInterface):
     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, ## query?
-            body_parameters=bottle.request.json,
-            form_parameters=bottle.request.forms,
-            header_parameters=bottle.request.headers,
+            path_parameters=path_parameters,
+            query_parameters=query_parameters, ## query?
+            body_parameters=body_parameters,
+            form_parameters=form_parameters,
+            header_parameters=header_parameters,
+            files_parameters=files_parameters,
         )
 
     def get_response(

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
 
 
@@ -149,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,
@@ -204,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
@@ -214,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):
@@ -269,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],

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,61 @@
 # -*- coding: utf-8 -*-
+import typing
+from http import HTTPStatus
+
+from multidict import MultiDict
+
+from hapic.context import ContextInterface
+from hapic.processor import RequestParameters
+from hapic.processor import ProcessValidationError
+
 
 class Base(object):
     pass
+
+
+class MyContext(ContextInterface):
+    def __init__(
+        self,
+        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:
+        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/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()
+        hapic.set_context(MyContext())
+        app = bottle.Bottle()
+
+        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(app)
+
+        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()
+        hapic.set_context(MyContext())
+        app = bottle.Bottle()
+
+        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(app)
+
+        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()
+        hapic.set_context(MyContext())
+        app = bottle.Bottle()
+
+        @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(app)
+
+        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()
+        hapic.set_context(MyContext())
+        app = bottle.Bottle()
+
+        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(app)
+
+        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()
+        hapic.set_context(MyContext())
+        app = bottle.Bottle()
+
+        # 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(app)
+
+        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,73 @@
+# 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(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(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(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,
@@ -146,21 +133,74 @@ class TestControllerWrapper(Base):
 
 class TestInputControllerWrapper(Base):
     def test_unit__input_data_wrapping__ok__nominal_case(self):
-        context = MyContext()
+        context = MyContext(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(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(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):