From 25870b4f2fecd4a023c923088729303aecae3050 Mon Sep 17 00:00:00 2001
From: Kolokotronis Panagiotis <panos122008@gmail.com>
Date: Fri, 17 Nov 2017 21:23:16 +0200
Subject: [PATCH] Add warning in documentation about HTTPException deprecation
 & docs

---
 CHANGES/2415.removal         |  1 +
 CONTRIBUTORS.txt             |  1 +
 aiohttp/web_protocol.py      |  9 +++++++++
 docs/web_quickstart.rst      |  5 +++++
 tests/test_web_functional.py | 13 +++++++++++++
 5 files changed, 29 insertions(+)
 create mode 100644 CHANGES/2415.removal

diff --git a/CHANGES/2415.removal b/CHANGES/2415.removal
new file mode 100644
index 00000000000..fd87ce07a61
--- /dev/null
+++ b/CHANGES/2415.removal
@@ -0,0 +1 @@
+Add DeprecationWarning for returning HTTPException
diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 9e675db82f3..6a50505ef96 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -140,6 +140,7 @@ Nicolas Braem
 Nikolay Novik
 Olaf Conradi
 Pahaz Blinov
+Panagiotis Kolokotronis
 Pankaj Pandey
 Pau Freixes
 Paul Colomiets
diff --git a/aiohttp/web_protocol.py b/aiohttp/web_protocol.py
index 877bdeb9a40..6eef5e8d216 100644
--- a/aiohttp/web_protocol.py
+++ b/aiohttp/web_protocol.py
@@ -3,6 +3,7 @@
 import http.server
 import socket
 import traceback
+import warnings
 from collections import deque
 from contextlib import suppress
 from html import escape as html_escape
@@ -427,6 +428,14 @@ async def start(self, message, payload, handler):
                 if self.access_log:
                     self.log_access(request, resp, loop.time() - now)
 
+                # Deprication warning (See #2415)
+                if isinstance(resp, HTTPException):
+                    warnings.warn(
+                        "returning HTTPException object is deprecated (#2415) "
+                        "and will be removed, "
+                        "please raise the exception instead",
+                        DeprecationWarning)
+
                 # check payload
                 if not payload.is_eof():
                     lingering_time = self._lingering_time
diff --git a/docs/web_quickstart.rst b/docs/web_quickstart.rst
index 0d52aba3129..e0dce54f235 100644
--- a/docs/web_quickstart.rst
+++ b/docs/web_quickstart.rst
@@ -590,6 +590,11 @@ The exceptions are also a subclass of :class:`Response`, allowing you to either
 ``raise`` or ``return`` them in a
 :ref:`request handler <aiohttp-web-handler>` for the same effect.
 
+.. warning::
+
+   Returning :class:`~HTTPException` or its subclasses is deprecated and will
+   be removed in subsequent aiohttp versions.
+
 The following snippets are the same::
 
     async def handler(request):
diff --git a/tests/test_web_functional.py b/tests/test_web_functional.py
index e638ed4aa66..21ccbe8da53 100644
--- a/tests/test_web_functional.py
+++ b/tests/test_web_functional.py
@@ -1576,3 +1576,16 @@ async def handler(request):
     async with aiohttp.ClientSession(loop=loop) as session:
         async with session.post(server.make_url('/'), data=data) as resp:
             assert resp.status == 200
+
+
+async def test_return_http_exception_deprecated(loop, test_client):
+
+    async def handler(request):
+        return web.HTTPForbidden()
+
+    app = web.Application()
+    app.router.add_route('GET', '/', handler)
+    client = await test_client(app)
+
+    with pytest.warns(DeprecationWarning):
+        await client.get('/')