Merge pull request #81 from algoo/develop

.travis.yml

@@ -1,7 +1,6 @@
 sudo: false
 language: python
 python:
-  - "3.4"
   - "3.5"
   - "3.6"
 

README.md

@@ -34,6 +34,8 @@ Hapic source code is ready for production. Some refactoring are identified and r
 
 Hapic is under active development, based on Algoo projects. We will answer your questions and accept merge requests if you find bugs or want to include functionnalities.
 
+Hapic is currently tested on python 3.5 and 3.6.
+
 ## TODO references
 
 TODO can make reference to #X, this is github issues references.

example/example_a_aiohttp.py

@@ -0,0 +1,78 @@
+# coding: utf-8
+from aiohttp import web
+from hapic import async as hapic
+from hapic import async as HapicData
+import marshmallow
+
+from hapic.ext.aiohttp.context import AiohttpContext
+
+
+class DisplayNameInputPathSchema(marshmallow.Schema):
+    name = marshmallow.fields.String(
+        required=False,
+        allow_none=True,
+    )
+
+
+class DisplayBodyInputBodySchema(marshmallow.Schema):
+    foo = marshmallow.fields.String(
+        required=True,
+    )
+
+
+class DisplayBodyOutputBodySchema(marshmallow.Schema):
+    data = marshmallow.fields.Dict(
+        required=True,
+    )
+
+
+@hapic.with_api_doc()
+@hapic.input_path(DisplayNameInputPathSchema())
+async def display_name(request, hapic_data):
+    name = request.match_info.get('name', "Anonymous")
+    text = "Hello, " + name
+    return web.json_response({
+        'sentence': text,
+    })
+
+
+@hapic.with_api_doc()
+@hapic.input_body(DisplayBodyInputBodySchema())
+@hapic.output_body(DisplayBodyOutputBodySchema())
+async def display_body(request, hapic_data: HapicData):
+    data = hapic_data.body
+    return {
+        'data': data,
+    }
+
+
+async def do_login(request):
+    data = await request.json()
+    login = data['login']
+    password = data['password']
+
+    return web.json_response({
+        'login': login,
+    })
+
+app = web.Application(debug=True)
+app.add_routes([
+    web.get('/n/', display_name),
+    web.get('/n/{name}', display_name),
+    web.post('/n/{name}', display_name),
+    web.post('/b/', display_body),
+    web.post('/login', do_login),
+])
+
+
+hapic.set_context(AiohttpContext(app))
+
+
+# import json
+# import yaml
+# print(yaml.dump(
+#     json.loads(json.dumps(hapic.generate_doc())),
+#     default_flow_style=False,
+# ))
+
+web.run_app(app)

hapic/__init__.py

@@ -20,3 +20,4 @@ set_context = _hapic_default.set_context
 reset_context = _hapic_default.reset_context
 add_documentation_view = _hapic_default.add_documentation_view
 handle_exception = _hapic_default.handle_exception
+output_stream = _hapic_default.output_stream

hapic/async.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+from hapic.hapic import Hapic
+
+_hapic_default = Hapic(async_=True)
+
+with_api_doc = _hapic_default.with_api_doc
+input_headers = _hapic_default.input_headers
+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
+reset_context = _hapic_default.reset_context
+add_documentation_view = _hapic_default.add_documentation_view
+handle_exception = _hapic_default.handle_exception
+output_stream = _hapic_default.output_stream

hapic/buffer.py

@@ -9,6 +9,7 @@ from hapic.description import InputHeadersDescription
 from hapic.description import InputFormsDescription
 from hapic.description import InputFilesDescription
 from hapic.description import OutputBodyDescription
+from hapic.description import OutputStreamDescription
 from hapic.description import OutputFileDescription
 from hapic.description import OutputHeadersDescription
 from hapic.description import ErrorDescription
@@ -96,6 +97,16 @@ class DecorationBuffer(object):
         self._description.output_body = description
 
     @property
+    def output_stream(self) -> OutputStreamDescription:
+        return self._description.output_stream
+
+    @output_stream.setter
+    def output_stream(self, description: OutputStreamDescription) -> None:
+        if self._description.output_stream is not None:
+            raise AlreadyDecoratedException()
+        self._description.output_stream = description
+
+    @property
     def output_file(self) -> OutputFileDescription:
         return self._description.output_file
 

hapic/decorator.py

@@ -73,11 +73,12 @@ class ControllerWrapper(object):
         self,
         func: 'typing.Callable[..., typing.Any]',
     ) -> 'typing.Callable[..., typing.Any]':
+        # async def wrapper(*args, **kwargs) -> typing.Any:
         def wrapper(*args, **kwargs) -> typing.Any:
             # Note: Design of before_wrapped_func can be to update kwargs
             # by reference here
             replacement_response = self.before_wrapped_func(args, kwargs)
-            if replacement_response:
+            if replacement_response is not None:
                 return replacement_response
 
             response = self._execute_wrapped_function(func, args, kwargs)
@@ -190,6 +191,56 @@ class InputControllerWrapper(InputOutputControllerWrapper):
         return error_response
 
 
+# TODO BS 2018-07-23: This class is an async version of InputControllerWrapper
+# (and ControllerWrapper.get_wrapper rewrite) to permit async compatibility.
+# Please re-think about code refact. TAG: REFACT_ASYNC
+class AsyncInputControllerWrapper(InputControllerWrapper):
+    def get_wrapper(
+        self,
+        func: 'typing.Callable[..., typing.Any]',
+    ) -> 'typing.Callable[..., typing.Any]':
+        async def wrapper(*args, **kwargs) -> typing.Any:
+            # Note: Design of before_wrapped_func can be to update kwargs
+            # by reference here
+            replacement_response = await self.before_wrapped_func(args, kwargs)
+            if replacement_response is not None:
+                return replacement_response
+
+            response = await self._execute_wrapped_function(func, args, kwargs)
+            new_response = self.after_wrapped_function(response)
+            return new_response
+        return functools.update_wrapper(wrapper, func)
+
+    async def before_wrapped_func(
+        self,
+        func_args: typing.Tuple[typing.Any, ...],
+        func_kwargs: typing.Dict[str, typing.Any],
+    ) -> typing.Any:
+        # Retrieve hapic_data instance or create new one
+        # hapic_data is given though decorators
+        # Important note here: func_kwargs is update by reference !
+        hapic_data = self.ensure_hapic_data(func_kwargs)
+        request_parameters = self.get_request_parameters(
+            func_args,
+            func_kwargs,
+        )
+
+        try:
+            processed_data = await self.get_processed_data(request_parameters)
+            self.update_hapic_data(hapic_data, processed_data)
+        except ProcessException:
+            error_response = await self.get_error_response(request_parameters)
+            return error_response
+
+    async def get_processed_data(
+        self,
+        request_parameters: RequestParameters,
+    ) -> typing.Any:
+        parameters_data = await self.get_parameters_data(request_parameters)
+        processed_data = self.processor.process(parameters_data)
+        return processed_data
+
+
 class OutputControllerWrapper(InputOutputControllerWrapper):
     def __init__(
         self,
@@ -262,6 +313,94 @@ class OutputBodyControllerWrapper(OutputControllerWrapper):
     pass
 
 
+# TODO BS 2018-07-23: This class is an async version of
+# OutputBodyControllerWrapper (ControllerWrapper.get_wrapper rewrite)
+# to permit async compatibility.
+# Please re-think about code refact. TAG: REFACT_ASYNC
+class AsyncOutputBodyControllerWrapper(OutputControllerWrapper):
+    def get_wrapper(
+        self,
+        func: 'typing.Callable[..., typing.Any]',
+    ) -> 'typing.Callable[..., typing.Any]':
+        # async def wrapper(*args, **kwargs) -> typing.Any:
+        async def wrapper(*args, **kwargs) -> typing.Any:
+            # Note: Design of before_wrapped_func can be to update kwargs
+            # by reference here
+            replacement_response = self.before_wrapped_func(args, kwargs)
+            if replacement_response is not None:
+                return replacement_response
+
+            response = await self._execute_wrapped_function(func, args, kwargs)
+            new_response = self.after_wrapped_function(response)
+            return new_response
+        return functools.update_wrapper(wrapper, func)
+
+
+class AsyncOutputStreamControllerWrapper(OutputControllerWrapper):
+    """
+    This controller wrapper produce a wrapper who caught the http view items
+    to check and serialize them into a stream response.
+    """
+    def __init__(
+        self,
+        context: typing.Union[ContextInterface, typing.Callable[[], ContextInterface]],  # nopep8
+        processor: ProcessorInterface,
+        error_http_code: HTTPStatus=HTTPStatus.INTERNAL_SERVER_ERROR,
+        default_http_code: HTTPStatus=HTTPStatus.OK,
+        ignore_on_error: bool = True,
+    ) -> None:
+        super().__init__(
+            context,
+            processor,
+            error_http_code,
+            default_http_code,
+        )
+        self.ignore_on_error = ignore_on_error
+
+    def get_wrapper(
+        self,
+        func: 'typing.Callable[..., typing.Any]',
+    ) -> 'typing.Callable[..., typing.Any]':
+        # async def wrapper(*args, **kwargs) -> typing.Any:
+        async def wrapper(*args, **kwargs) -> typing.Any:
+            # Note: Design of before_wrapped_func can be to update kwargs
+            # by reference here
+            replacement_response = self.before_wrapped_func(args, kwargs)
+            if replacement_response is not None:
+                return replacement_response
+
+            stream_response = await self.context.get_stream_response_object(
+                args,
+                kwargs,
+            )
+            async for stream_item in await self._execute_wrapped_function(
+                func,
+                args,
+                kwargs,
+            ):
+                try:
+                    serialized_item = self._get_serialized_item(stream_item)
+                    await self.context.feed_stream_response(
+                        stream_response,
+                        serialized_item,
+                    )
+                except OutputValidationException as exc:
+                    if not self.ignore_on_error:
+                        # TODO BS 2018-07-31: Something should inform about
+                        # error, a log ?
+                        return stream_response
+
+            return stream_response
+
+        return functools.update_wrapper(wrapper, func)
+
+    def _get_serialized_item(
+        self,
+        item_object: typing.Any,
+    ) -> dict:
+        return self.processor.process(item_object)
+
+
 class OutputHeadersControllerWrapper(OutputControllerWrapper):
     pass
 
@@ -344,6 +483,32 @@ class InputBodyControllerWrapper(InputControllerWrapper):
         return request_parameters.body_parameters
 
 
+# TODO BS 2018-07-23: This class is an async version of InputControllerWrapper
+# to permit async compatibility. Please re-think about code refact
+# TAG: REFACT_ASYNC
+class AsyncInputBodyControllerWrapper(AsyncInputControllerWrapper):
+    def update_hapic_data(
+        self, hapic_data: HapicData,
+        processed_data: typing.Any,
+    ) -> None:
+        hapic_data.body = processed_data
+
+    async def get_parameters_data(self, request_parameters: RequestParameters) -> dict:  # nopep8
+        return await request_parameters.body_parameters
+
+    async def get_error_response(
+        self,
+        request_parameters: RequestParameters,
+    ) -> typing.Any:
+        parameters_data = await 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,
+        )
+        return error_response
+
+
 class InputHeadersControllerWrapper(InputControllerWrapper):
     def update_hapic_data(
         self, hapic_data: HapicData,
@@ -420,24 +585,65 @@ class ExceptionHandlerControllerWrapper(ControllerWrapper):
                 func_kwargs,
             )
         except self.handled_exception_class as exc:
-            response_content = self.error_builder.build_from_exception(
-                exc,
-                include_traceback=self.context.is_debug(),
-            )
+            return self._build_error_response(exc)
 
-            # Check error format
-            dumped = self.error_builder.dump(response_content).data
-            unmarshall = self.error_builder.load(dumped)
-            if unmarshall.errors:
-                raise OutputValidationException(
-                    'Validation error during dump of error response: {}'
+    def _build_error_response(self, exc: Exception) -> typing.Any:
+        response_content = self.error_builder.build_from_exception(
+            exc,
+            include_traceback=self.context.is_debug(),
+        )
+
+        # Check error format
+        dumped = self.error_builder.dump(response_content).data
+        unmarshall = self.error_builder.load(dumped)
+        if unmarshall.errors:
+            raise OutputValidationException(
+                'Validation error during dump of error response: {}'
                     .format(
-                        str(unmarshall.errors)
-                    )
+                    str(unmarshall.errors)
                 )
+            )
+
+        error_response = self.context.get_response(
+            json.dumps(dumped),
+            self.http_code,
+        )
+        return error_response
+
+
+# TODO BS 2018-07-23: This class is an async version of
+# ExceptionHandlerControllerWrapper
+# to permit async compatibility. Please re-think about code refact
+# TAG: REFACT_ASYNC
+class AsyncExceptionHandlerControllerWrapper(ExceptionHandlerControllerWrapper):
+    def get_wrapper(
+        self,
+        func: 'typing.Callable[..., typing.Any]',
+    ) -> 'typing.Callable[..., typing.Any]':
+        # async def wrapper(*args, **kwargs) -> typing.Any:
+        async def wrapper(*args, **kwargs) -> typing.Any:
+            # Note: Design of before_wrapped_func can be to update kwargs
+            # by reference here
+            replacement_response = self.before_wrapped_func(args, kwargs)
+            if replacement_response is not None:
+                return replacement_response
 
-            error_response = self.context.get_response(
-                json.dumps(dumped),
-                self.http_code,
+            response = await self._execute_wrapped_function(func, args, kwargs)
+            new_response = self.after_wrapped_function(response)
+            return new_response
+        return functools.update_wrapper(wrapper, func)
+
+    async def _execute_wrapped_function(
+        self,
+        func,
+        func_args,
+        func_kwargs,
+    ) -> typing.Any:
+        try:
+            return await super()._execute_wrapped_function(
+                func,
+                func_args,
+                func_kwargs,
             )
-            return error_response
+        except self.handled_exception_class as exc:
+            return self._build_error_response(exc)

hapic/description.py

@@ -38,6 +38,10 @@ class OutputBodyDescription(Description):
     pass
 
 
+class OutputStreamDescription(Description):
+    pass
+
+
 class OutputFileDescription(Description):
     pass
 
@@ -60,6 +64,7 @@ class ControllerDescription(object):
         input_forms: InputFormsDescription=None,
         input_files: InputFilesDescription=None,
         output_body: OutputBodyDescription=None,
+        output_stream: OutputStreamDescription=None,
         output_file: OutputFileDescription=None,
         output_headers: OutputHeadersDescription=None,
         errors: typing.List[ErrorDescription]=None,
@@ -72,6 +77,7 @@ class ControllerDescription(object):
         self.input_forms = input_forms
         self.input_files = input_files
         self.output_body = output_body
+        self.output_stream = output_stream
         self.output_file = output_file
         self.output_headers = output_headers
         self.errors = errors or []

hapic/doc.py

@@ -158,6 +158,23 @@ def bottle_generate_operations(
                 )
             }
 
+    if description.output_stream:
+        # TODO BS 2018-07-31: Is that a correct way to re
+        # instanciate with .__class__ ... ?
+        method_operations.setdefault('responses', {})\
+            [int(description.output_stream.wrapper.default_http_code)] = {
+                'description': str(int(description.output_stream.wrapper.default_http_code)),  # nopep8
+                'schema': generate_schema_ref(
+                    spec,
+                    description
+                        .output_stream
+                        .wrapper
+                        .processor
+                        .schema
+                        .__class__(many=True),
+                )
+            }
+
     if description.output_file:
         method_operations.setdefault('produces', []).extend(
             description.output_file.wrapper.output_types

hapic/ext/aiohttp/__init__.py

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

hapic/ext/aiohttp/context.py

@@ -0,0 +1,276 @@
+# coding: utf-8
+import json
+import re
+import typing
+from http import HTTPStatus
+
+from aiohttp.web_request import Request
+from aiohttp.web_response import Response
+from multidict import MultiDict
+
+from hapic.context import BaseContext
+from hapic.context import RouteRepresentation
+from hapic.decorator import DecoratedController
+from hapic.decorator import DECORATION_ATTRIBUTE_NAME
+from hapic.error import ErrorBuilderInterface
+from hapic.error import DefaultErrorBuilder
+from hapic.exception import WorkflowException
+from hapic.exception import OutputValidationException
+from hapic.exception import NoRoutesException
+from hapic.exception import RouteNotFound
+from hapic.processor import ProcessValidationError
+from hapic.processor import RequestParameters
+from aiohttp import web
+
+
+# Aiohttp regular expression to locate url parameters
+AIOHTTP_RE_PATH_URL = re.compile(r'{([^:<>]+)(?::[^<>]+)?}')
+
+
+class AiohttpRequestParameters(object):
+    def __init__(
+        self,
+        request: Request,
+    ) -> None:
+        self._request = request
+        self._parsed_body = None
+
+    @property
+    async def body_parameters(self) -> dict:
+        if self._parsed_body is None:
+            content_type = self.header_parameters.get('Content-Type')
+            is_json = content_type == 'application/json'
+
+            if is_json:
+                self._parsed_body = await self._request.json()
+            else:
+                self._parsed_body = await self._request.post()
+
+        return self._parsed_body
+
+    @property
+    def path_parameters(self):
+        return dict(self._request.match_info)
+
+    @property
+    def query_parameters(self):
+        return MultiDict(self._request.query.items())
+
+    @property
+    def form_parameters(self):
+        # TODO BS 2018-07-24: There is misunderstanding around body/form/json
+        return self.body_parameters
+
+    @property
+    def header_parameters(self):
+        return dict(self._request.headers.items())
+
+    @property
+    def files_parameters(self):
+        # TODO BS 2018-07-24: To do
+        raise NotImplementedError('todo')
+
+
+class AiohttpContext(BaseContext):
+    def __init__(
+        self,
+        app: web.Application,
+        default_error_builder: ErrorBuilderInterface=None,
+        debug: bool = False,
+    ) -> None:
+        self._app = app
+        self._debug = debug
+        self.default_error_builder = \
+            default_error_builder or DefaultErrorBuilder()  # FDV
+
+    @property
+    def app(self) -> web.Application:
+        return self._app
+
+    def get_request_parameters(
+        self,
+        *args,
+        **kwargs
+    ) -> RequestParameters:
+        try:
+            request = args[0]
+        except IndexError:
+            raise WorkflowException(
+                'Unable to get aiohttp request object',
+            )
+        request = typing.cast(Request, request)
+        return AiohttpRequestParameters(request)
+
+    def get_response(
+        self,
+        response: str,
+        http_code: int,
+        mimetype: str = 'application/json',
+    ) -> typing.Any:
+        # A 204 no content response should not have content type header
+        if http_code == HTTPStatus.NO_CONTENT:
+            mimetype = None
+            response = ''
+
+        return Response(
+            body=response,
+            status=http_code,
+            content_type=mimetype,
+        )
+
+    def get_validation_error_response(
+        self,
+        error: ProcessValidationError,
+        http_code: HTTPStatus = HTTPStatus.BAD_REQUEST,
+    ) -> typing.Any:
+        error_builder = self.get_default_error_builder()
+        error_content = error_builder.build_from_validation_error(
+            error,
+        )
+
+        # Check error
+        dumped = error_builder.dump(error_content).data
+        unmarshall = error_builder.load(dumped)
+        if unmarshall.errors:
+            raise OutputValidationException(
+                'Validation error during dump of error response: {}'.format(
+                    str(unmarshall.errors)
+                )
+            )
+
+        return web.Response(
+            text=json.dumps(dumped),
+            headers=[
+                ('Content-Type', 'application/json'),
+            ],
+            status=int(http_code),
+        )
+
+    def find_route(
+        self,
+        decorated_controller: DecoratedController,
+    ) -> RouteRepresentation:
+        if not len(self.app.router.routes()):
+            raise NoRoutesException('There is no routes in your aiohttp app')
+
+        reference = decorated_controller.reference
+
+        for route in self.app.router.routes():
+            route_token = getattr(
+                route.handler,
+                DECORATION_ATTRIBUTE_NAME,
+                None,
+            )
+
+            match_with_wrapper = route.handler == reference.wrapper
+            match_with_wrapped = route.handler == reference.wrapped
+            match_with_token = route_token == reference.token
+
+            # TODO BS 2018-07-27: token is set in HEAD view to, must solve this
+            # case
+            if not match_with_wrapper \
+                    and not match_with_wrapped \
+                    and match_with_token \
+                    and route.method.lower() == 'head':
+                continue
+
+            if match_with_wrapper or match_with_wrapped or match_with_token:
+                return RouteRepresentation(
+                    rule=self.get_swagger_path(route.resource.canonical),
+                    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 aiohttp routes'.format(
+                decorated_controller.name,
+            )
+        )
+
+    def get_swagger_path(
+        self,
+        contextualised_rule: str,
+    ) -> str:
+        return AIOHTTP_RE_PATH_URL.sub(r'{\1}', contextualised_rule)
+
+    def by_pass_output_wrapping(
+        self,
+        response: typing.Any,
+    ) -> bool:
+        return isinstance(response, web.Response)
+
+    def add_view(
+        self,
+        route: str,
+        http_method: str,
+        view_func: typing.Callable[..., typing.Any],
+    ) -> None:
+        # TODO BS 2018-07-15: to do
+        raise NotImplementedError('todo')
+
+    def serve_directory(
+        self,
+        route_prefix: str,
+        directory_path: str,
+    ) -> None:
+        # TODO BS 2018-07-15: to do
+        raise NotImplementedError('todo')
+
+    def is_debug(
+        self,
+    ) -> bool:
+        return self._debug
+
+    def handle_exception(
+        self,
+        exception_class: typing.Type[Exception],
+        http_code: int,
+    ) -> None:
+        # TODO BS 2018-07-15: to do
+        raise NotImplementedError('todo')
+
+    def handle_exceptions(
+        self,
+        exception_classes: typing.List[typing.Type[Exception]],
+        http_code: int,
+    ) -> None:
+        # TODO BS 2018-07-15: to do
+        raise NotImplementedError('todo')
+
+    async def get_stream_response_object(
+        self,
+        func_args,
+        func_kwargs,
+        http_code: HTTPStatus = HTTPStatus.OK,
+        headers: dict = None,
+    ) -> web.StreamResponse:
+        headers = headers or {
+            'Content-Type': 'text/plain; charset=utf-8',
+        }
+
+        response = web.StreamResponse(
+            status=http_code,
+            headers=headers,
+        )
+
+        try:
+            request = func_args[0]
+        except IndexError:
+            raise WorkflowException(
+                'Unable to get aiohttp request object',
+            )
+        request = typing.cast(Request, request)
+
+        await response.prepare(request)
+
+        return response
+
+    async def feed_stream_response(
+        self,
+        stream_response: web.StreamResponse,
+        serialized_item: dict,
+    ) -> None:
+        await stream_response.write(
+            # FIXME BS 2018-07-25: need \n :/
+            json.dumps(serialized_item).encode('utf-8') + b'\n',
+        )

hapic/hapic.py

@@ -14,12 +14,16 @@ from hapic.decorator import DecoratedController
 from hapic.decorator import DECORATION_ATTRIBUTE_NAME
 from hapic.decorator import ControllerReference
 from hapic.decorator import ExceptionHandlerControllerWrapper
+from hapic.decorator import AsyncExceptionHandlerControllerWrapper
 from hapic.decorator import InputBodyControllerWrapper
+from hapic.decorator import AsyncInputBodyControllerWrapper
 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 AsyncOutputBodyControllerWrapper
+from hapic.decorator import AsyncOutputStreamControllerWrapper
 from hapic.decorator import OutputHeadersControllerWrapper
 from hapic.decorator import OutputFileControllerWrapper
 from hapic.description import InputBodyDescription
@@ -30,6 +34,7 @@ from hapic.description import InputPathDescription
 from hapic.description import InputQueryDescription
 from hapic.description import InputFilesDescription
 from hapic.description import OutputBodyDescription
+from hapic.description import OutputStreamDescription
 from hapic.description import OutputHeadersDescription
 from hapic.description import OutputFileDescription
 from hapic.doc import DocGenerator
@@ -45,11 +50,15 @@ from hapic.error import ErrorBuilderInterface
 
 
 class Hapic(object):
-    def __init__(self):
+    def __init__(
+        self,
+        async_: bool = False,
+    ):
         self._buffer = DecorationBuffer()
         self._controllers = []  # type: typing.List[DecoratedController]
         self._context = None  # type: ContextInterface
         self._error_builder = None  # type: ErrorBuilderInterface
+        self._async = async_
         self.doc_generator = DocGenerator()
 
         # This local function will be pass to different components
@@ -143,18 +152,71 @@ class Hapic(object):
         processor = processor or MarshmallowOutputProcessor()
         processor.schema = schema
         context = context or self._context_getter
-        decoration = OutputBodyControllerWrapper(
-            context=context,
-            processor=processor,
-            error_http_code=error_http_code,
-            default_http_code=default_http_code,
-        )
+
+        if self._async:
+            decoration = AsyncOutputBodyControllerWrapper(
+                context=context,
+                processor=processor,
+                error_http_code=error_http_code,
+                default_http_code=default_http_code,
+            )
+        else:
+            decoration = OutputBodyControllerWrapper(
+                context=context,
+                processor=processor,
+                error_http_code=error_http_code,
+                default_http_code=default_http_code,
+            )
 
         def decorator(func):
             self._buffer.output_body = OutputBodyDescription(decoration)
             return decoration.get_wrapper(func)
         return decorator
 
+    def output_stream(
+        self,
+        item_schema: typing.Any,
+        processor: ProcessorInterface = None,
+        context: ContextInterface = None,
+        error_http_code: HTTPStatus = HTTPStatus.INTERNAL_SERVER_ERROR,
+        default_http_code: HTTPStatus = HTTPStatus.OK,
+        ignore_on_error: bool = True,
+    ) -> typing.Callable[[typing.Callable[..., typing.Any]], typing.Any]:
+        """
+        Decorate with a wrapper who check and serialize each items in output
+        stream.
+
+        :param item_schema: Schema of output stream items
+        :param processor: ProcessorInterface object to process with given
+        schema
+        :param context: Context to use here
+        :param error_http_code: http code in case of error
+        :param default_http_code: http code in case of success
+        :param ignore_on_error: if set, an error of serialization will be
+        ignored: stream will not send this failed object
+        :return: decorator
+        """
+        processor = processor or MarshmallowOutputProcessor()
+        processor.schema = item_schema
+        context = context or self._context_getter
+
+        if self._async:
+            decoration = AsyncOutputStreamControllerWrapper(
+                context=context,
+                processor=processor,
+                error_http_code=error_http_code,
+                default_http_code=default_http_code,
+                ignore_on_error=ignore_on_error,
+            )
+        else:
+            # TODO BS 2018-07-25: To do
+            raise NotImplementedError('todo')
+
+        def decorator(func):
+            self._buffer.output_stream = OutputStreamDescription(decoration)
+            return decoration.get_wrapper(func)
+        return decorator
+
     def output_headers(
         self,
         schema: typing.Any,
@@ -282,12 +344,20 @@ class Hapic(object):
         processor.schema = schema
         context = context or self._context_getter
 
-        decoration = InputBodyControllerWrapper(
-            context=context,
-            processor=processor,
-            error_http_code=error_http_code,
-            default_http_code=default_http_code,
-        )
+        if self._async:
+            decoration = AsyncInputBodyControllerWrapper(
+                context=context,
+                processor=processor,
+                error_http_code=error_http_code,
+                default_http_code=default_http_code,
+            )
+        else:
+            decoration = InputBodyControllerWrapper(
+                context=context,
+                processor=processor,
+                error_http_code=error_http_code,
+                default_http_code=default_http_code,
+            )
 
         def decorator(func):
             self._buffer.input_body = InputBodyDescription(decoration)
@@ -352,12 +422,21 @@ class Hapic(object):
         context = context or self._context_getter
         error_builder = error_builder or self._error_builder_getter
 
-        decoration = ExceptionHandlerControllerWrapper(
-            handled_exception_class,
-            context,
-            error_builder=error_builder,
-            http_code=http_code,
-        )
+        if self._async:
+            decoration = AsyncExceptionHandlerControllerWrapper(
+                handled_exception_class,
+                context,
+                error_builder=error_builder,
+                http_code=http_code,
+            )
+
+        else:
+            decoration = ExceptionHandlerControllerWrapper(
+                handled_exception_class,
+                context,
+                error_builder=error_builder,
+                http_code=http_code,
+            )
 
         def decorator(func):
             self._buffer.errors.append(ErrorDescription(decoration))

setup.py

@@ -29,6 +29,8 @@ tests_require = [
     'flask',
     'pyramid',
     'webtest',
+    'aiohttp',
+    'pytest-aiohttp',
 ]
 dev_require = [
     'requests',

tests/ext/unit/test_aiohttp.py

@@ -0,0 +1,448 @@
+# coding: utf-8
+from aiohttp import web
+import marshmallow
+
+from hapic import Hapic
+from hapic import HapicData
+from hapic.ext.aiohttp.context import AiohttpContext
+
+
+class TestAiohttpExt(object):
+    async def test_aiohttp_only__ok__nominal_case(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        async def hello(request):
+            return web.Response(text='Hello, world')
+
+        app = web.Application(debug=True)
+        app.router.add_get('/', hello)
+        client = await aiohttp_client(app)
+        resp = await client.get('/')
+        assert resp.status == 200
+        text = await resp.text()
+        assert 'Hello, world' in text
+
+    async def test_aiohttp_input_path__ok__nominal_case(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class InputPathSchema(marshmallow.Schema):
+            name = marshmallow.fields.String()
+
+        @hapic.input_path(InputPathSchema())
+        async def hello(request, hapic_data: HapicData):
+            name = hapic_data.path.get('name')
+            return web.Response(text='Hello, {}'.format(name))
+
+        app = web.Application(debug=True)
+        app.router.add_get('/{name}', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.get('/bob')
+        assert resp.status == 200
+
+        text = await resp.text()
+        assert 'Hello, bob' in text
+
+    async def test_aiohttp_input_path__error_wrong_input_parameter(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class InputPathSchema(marshmallow.Schema):
+            i = marshmallow.fields.Integer()
+
+        @hapic.input_path(InputPathSchema())
+        async def hello(request, hapic_data: HapicData):
+            i = hapic_data.path.get('i')
+            return web.Response(text='integer: {}'.format(str(i)))
+
+        app = web.Application(debug=True)
+        app.router.add_get('/{i}', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.get('/bob')  # NOTE: should be integer here
+        assert resp.status == 400
+
+        error = await resp.json()
+        assert 'Validation error of input data' in error.get('message')
+        assert {'i': ['Not a valid integer.']} == error.get('details')
+
+    async def test_aiohttp_input_body__ok_nominal_case(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class InputBodySchema(marshmallow.Schema):
+            name = marshmallow.fields.String()
+
+        @hapic.input_body(InputBodySchema())
+        async def hello(request, hapic_data: HapicData):
+            name = hapic_data.body.get('name')
+            return web.Response(text='Hello, {}'.format(name))
+
+        app = web.Application(debug=True)
+        app.router.add_post('/', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.post('/', data={'name': 'bob'})
+        assert resp.status == 200
+
+        text = await resp.text()
+        assert 'Hello, bob' in text
+
+    async def test_aiohttp_input_body__error__incorrect_input_body(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class InputBodySchema(marshmallow.Schema):
+            i = marshmallow.fields.Integer()
+
+        @hapic.input_body(InputBodySchema())
+        async def hello(request, hapic_data: HapicData):
+            i = hapic_data.body.get('i')
+            return web.Response(text='integer, {}'.format(i))
+
+        app = web.Application(debug=True)
+        app.router.add_post('/', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.post('/', data={'i': 'bob'})  # NOTE: should be int
+        assert resp.status == 400
+
+        error = await resp.json()
+        assert 'Validation error of input data' in error.get('message')
+        assert {'i': ['Not a valid integer.']} == error.get('details')
+
+    async def test_aiohttp_output_body__ok__nominal_case(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class OuputBodySchema(marshmallow.Schema):
+            name = marshmallow.fields.String()
+
+        @hapic.output_body(OuputBodySchema())
+        async def hello(request):
+            return {
+                'name': 'bob',
+            }
+
+        app = web.Application(debug=True)
+        app.router.add_get('/', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.get('/')
+        assert resp.status == 200
+
+        data = await resp.json()
+        assert 'bob' == data.get('name')
+
+    async def test_aiohttp_output_body__error__incorrect_output_body(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class OuputBodySchema(marshmallow.Schema):
+            i = marshmallow.fields.Integer(required=True)
+
+        @hapic.output_body(OuputBodySchema())
+        async def hello(request):
+            return {
+                'i': 'bob',  # NOTE: should be integer
+            }
+
+        app = web.Application(debug=True)
+        app.router.add_get('/', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.get('/')
+        assert resp.status == 500
+
+        data = await resp.json()
+        assert 'Validation error of output data' == data.get('message')
+        assert {
+                   'i': ['Missing data for required field.'],
+               } == data.get('details')
+
+    async def test_aiohttp_handle_excpetion__ok__nominal_case(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        @hapic.handle_exception(ZeroDivisionError, http_code=400)
+        async def hello(request):
+            1 / 0
+
+        app = web.Application(debug=True)
+        app.router.add_get('/', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.get('/')
+        assert resp.status == 400
+
+        data = await resp.json()
+        assert 'division by zero' == data.get('message')
+
+    async def test_aiohttp_output_stream__ok__nominal_case(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class AsyncGenerator:
+            def __init__(self):
+                self._iterator = iter([
+                    {'name': 'Hello, bob'},
+                    {'name': 'Hello, franck'},
+                ])
+
+            async def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                return next(self._iterator)
+
+        class OuputStreamItemSchema(marshmallow.Schema):
+            name = marshmallow.fields.String()
+
+        @hapic.output_stream(OuputStreamItemSchema())
+        async def hello(request):
+            return AsyncGenerator()
+
+        app = web.Application(debug=True)
+        app.router.add_get('/', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.get('/')
+        assert resp.status == 200
+
+        line = await resp.content.readline()
+        assert b'{"name": "Hello, bob"}\n' == line
+
+        line = await resp.content.readline()
+        assert b'{"name": "Hello, franck"}\n' == line
+
+    async def test_aiohttp_output_stream__error__ignore(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class AsyncGenerator:
+            def __init__(self):
+                self._iterator = iter([
+                    {'name': 'Hello, bob'},
+                    {'nameZ': 'Hello, Z'},  # This line is incorrect
+                    {'name': 'Hello, franck'},
+                ])
+
+            async def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                return next(self._iterator)
+
+        class OuputStreamItemSchema(marshmallow.Schema):
+            name = marshmallow.fields.String(required=True)
+
+        @hapic.output_stream(OuputStreamItemSchema(), ignore_on_error=True)
+        async def hello(request):
+            return AsyncGenerator()
+
+        app = web.Application(debug=True)
+        app.router.add_get('/', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.get('/')
+        assert resp.status == 200
+
+        line = await resp.content.readline()
+        assert b'{"name": "Hello, bob"}\n' == line
+
+        line = await resp.content.readline()
+        assert b'{"name": "Hello, franck"}\n' == line
+
+    async def test_aiohttp_output_stream__error__interrupt(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class AsyncGenerator:
+            def __init__(self):
+                self._iterator = iter([
+                    {'name': 'Hello, bob'},
+                    {'nameZ': 'Hello, Z'},  # This line is incorrect
+                    {'name': 'Hello, franck'},  # This line must not be reached
+                ])
+
+            async def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                return next(self._iterator)
+
+        class OuputStreamItemSchema(marshmallow.Schema):
+            name = marshmallow.fields.String(required=True)
+
+        @hapic.output_stream(OuputStreamItemSchema(), ignore_on_error=False)
+        async def hello(request):
+            return AsyncGenerator()
+
+        app = web.Application(debug=True)
+        app.router.add_get('/', hello)
+        hapic.set_context(AiohttpContext(app))
+        client = await aiohttp_client(app)
+
+        resp = await client.get('/')
+        assert resp.status == 200
+
+        line = await resp.content.readline()
+        assert b'{"name": "Hello, bob"}\n' == line
+
+        line = await resp.content.readline()
+        assert b'' == line
+
+    def test_unit__generate_doc__ok__nominal_case(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class InputPathSchema(marshmallow.Schema):
+            username = marshmallow.fields.String(required=True)
+
+        class InputQuerySchema(marshmallow.Schema):
+            show_deleted = marshmallow.fields.Boolean(required=False)
+
+        class UserSchema(marshmallow.Schema):
+            name = marshmallow.fields.String(required=True)
+
+        @hapic.with_api_doc()
+        @hapic.input_path(InputPathSchema())
+        @hapic.input_query(InputQuerySchema())
+        @hapic.output_body(UserSchema())
+        async def get_user(request, hapic_data):
+            pass
+
+        @hapic.with_api_doc()
+        @hapic.input_path(InputPathSchema())
+        @hapic.output_body(UserSchema())
+        async def post_user(request, hapic_data):
+            pass
+
+        app = web.Application(debug=True)
+        app.router.add_get('/{username}', get_user)
+        app.router.add_post('/{username}', post_user)
+        hapic.set_context(AiohttpContext(app))
+
+        doc = hapic.generate_doc('aiohttp', 'testing')
+        assert 'UserSchema' in doc.get('definitions')
+        assert {
+                   'name': {'type': 'string'}
+               } == doc['definitions']['UserSchema'].get('properties')
+        assert '/{username}' in doc.get('paths')
+        assert 'get' in doc['paths']['/{username}']
+        assert 'post' in doc['paths']['/{username}']
+
+        assert [
+            {
+                'name': 'username',
+                'in': 'path',
+                'required': True,
+                'type': 'string',
+            },
+            {
+                'name': 'show_deleted',
+                'in': 'query',
+                'required': False,
+                'type': 'boolean',
+            }
+        ] == doc['paths']['/{username}']['get']['parameters']
+        assert {
+            200: {
+                'schema': {
+                    '$ref': '#/definitions/UserSchema',
+                },
+                'description': '200',
+            }
+        } == doc['paths']['/{username}']['get']['responses']
+
+        assert [
+                   {
+                       'name': 'username',
+                       'in': 'path',
+                       'required': True,
+                       'type': 'string',
+                   }
+               ] == doc['paths']['/{username}']['post']['parameters']
+        assert {
+                   200: {
+                       'schema': {
+                           '$ref': '#/definitions/UserSchema',
+                       },
+                       'description': '200',
+                   }
+               } == doc['paths']['/{username}']['get']['responses']
+
+    def test_unit__generate_output_stream_doc__ok__nominal_case(
+        self,
+        aiohttp_client,
+        loop,
+    ):
+        hapic = Hapic(async_=True)
+
+        class OuputStreamItemSchema(marshmallow.Schema):
+            name = marshmallow.fields.String(required=True)
+
+        @hapic.with_api_doc()
+        @hapic.output_stream(OuputStreamItemSchema())
+        async def get_users(request, hapic_data):
+            pass
+
+        app = web.Application(debug=True)
+        app.router.add_get('/', get_users)
+        hapic.set_context(AiohttpContext(app))
+
+        doc = hapic.generate_doc('aiohttp', 'testing')
+        assert '/' in doc.get('paths')
+        assert 'get' in doc['paths']['/']
+        assert 200 in doc['paths']['/']['get'].get('responses', {})
+        assert {
+            'items': {
+                '$ref': '#/definitions/OuputStreamItemSchema'
+            },
+            'type': 'array',
+        } == doc['paths']['/']['get']['responses'][200]['schema']