Add input_files and output_file

hapic/buffer.py

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

         self.query = {}
         self.headers = {}
         self.forms = {}
+        self.files = {}

hapic/decorator.py

         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(
         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,
     pass
 
 
+class OutputFileControllerWrapper(ControllerWrapper):
+    def __init__(
+        self,
+        output_type: str,
+        default_http_code: HTTPStatus=HTTPStatus.OK,
+    ) -> None:
+        self.output_type = output_type
+        self.default_http_code = default_http_code
+
+
 class InputPathControllerWrapper(InputControllerWrapper):
     def update_hapic_data(
         self, hapic_data: HapicData,
     ) -> 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:
+        return request_parameters.path_parameters
 
 
 class InputQueryControllerWrapper(InputControllerWrapper):
     ) -> 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) -> dict:
+        return request_parameters.query_parameters
 
 
 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:
+        return request_parameters.body_parameters
 
 
 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:
+        return request_parameters.header_parameters
 
 
 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:
+        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:
+        return request_parameters.files_parameters
 
 
 class ExceptionHandlerControllerWrapper(ControllerWrapper):

hapic/description.py

 
 
 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
 
         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,
     ):
         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

     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:
                 }
             }
 
+    if description.output_file:
+        method_operations.setdefault('produce', []).append(
+            description.output_file.wrapper.output_type
+        )
+        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)
                 'type': schema['type']
             })
 
+    if description.input_files:
+        method_operations.setdefault('consume', []).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,
     }

hapic/exception.py

     pass
 
 
+class ConfigurationException(HapicException):
+    pass
+
+
 class WorkflowException(HapicException):
     pass
 

hapic/hapic.py

 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
 
 
             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_type: str,
+        default_http_code: HTTPStatus = HTTPStatus.OK,
+    ) -> typing.Callable[[typing.Callable[..., typing.Any]], typing.Any]:
+        decoration = OutputFileControllerWrapper(
+            output_type=output_type,
+            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,
             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

 # -*- coding: utf-8 -*-
 import typing
 
-from hapic.exception import InputValidationException, OutputValidationException
+from hapic.exception import OutputValidationException
+from hapic.exception import ConfigurationException
 
 
 class RequestParameters(object):
         body_parameters,
         form_parameters,
         header_parameters,
+        files_parameters,
     ):
         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):
 
 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
             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

tests/base.py

 # -*- coding: utf-8 -*-
+import typing
+from http import HTTPStatus
+
+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 {}
+        self.fake_body_parameters = fake_body_parameters or {}
+        self.fake_form_parameters = fake_form_parameters or {}
+        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

+# coding: utf-8

tests/func/test_doc.py

+# 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 'consume' in doc['paths']['/upload']['post']
+        assert 'multipart/form-data' in doc['paths']['/upload']['post']['consume']
+        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 'consume' in doc['paths']['/upload']['post']
+        assert 'multipart/form-data' in doc['paths']['/upload']['post']['consume']
+        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 'produce' in doc['paths']['/avatar']['get']
+        assert 'image/jpeg' in doc['paths']['/avatar']['get']['produce']
+        assert 200 in doc['paths']['/avatar']['get']['responses']

tests/func/test_marshmallow_decoration.py

+# 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

 
 import marshmallow
 
-from hapic.context import ContextInterface
 from hapic.data import HapicData
-from hapic.decorator import InputOutputControllerWrapper
 from hapic.decorator import ExceptionHandlerControllerWrapper
 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
-
-
-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,
-        }
-
-    def get_validation_error_response(
-        self,
-        error: ProcessValidationError,
-        http_code: HTTPStatus=HTTPStatus.BAD_REQUEST,
-    ) -> typing.Any:
-        return {
-            'original_error': error,
-            'http_code': http_code,
-        }
+from tests.base import MyContext
 
 
 class MyProcessor(ProcessorInterface):
         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,
 
 class TestInputControllerWrapper(Base):
     def test_unit__input_data_wrapping__ok__nominal_case(self):
-        context = MyContext()
+        context = MyContext(fake_query_parameters={
+            '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)