From 83e9d0885373e6d5f43a328e861d2321c769e62b Mon Sep 17 00:00:00 2001
From: 38elements <mh19820223@gmail.com>
Date: Thu, 29 Dec 2016 13:11:27 +0900
Subject: [PATCH] Add document for custom protocol

---
 README.md                   |  1 +
 docs/custom_protocol.md     | 68 +++++++++++++++++++++++++++++++++++++
 examples/custom_protocol.py | 28 ---------------
 sanic/sanic.py              |  2 +-
 sanic/server.py             |  2 +-
 5 files changed, 71 insertions(+), 30 deletions(-)
 create mode 100644 docs/custom_protocol.md
 delete mode 100644 examples/custom_protocol.py

diff --git a/README.md b/README.md
index 5aded700..61b154ff 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,7 @@ if __name__ == "__main__":
  * [Class Based Views](docs/class_based_views.md)
  * [Cookies](docs/cookies.md)
  * [Static Files](docs/static_files.md)
+ * [Custom Protocol](docs/custom_protocol.md)
  * [Deploying](docs/deploying.md)
  * [Contributing](docs/contributing.md)
  * [License](LICENSE)
diff --git a/docs/custom_protocol.md b/docs/custom_protocol.md
new file mode 100644
index 00000000..a92f1b53
--- /dev/null
+++ b/docs/custom_protocol.md
@@ -0,0 +1,68 @@
+# Custom Protocol
+
+You can change the behavior of protocol by using custom protocol.
+If you want to use custom protocol, you should put subclass of [protocol class](https://docs.python.org/3/library/asyncio-protocol.html#protocol-classes) in the protocol keyword argument of `sanic.run()`. The constructor of custom protocol class gets following keyword arguments from Sanic.
+
+* loop
+`loop` is an asyncio compatible event loop.
+
+* connections
+`connections` is a `set object`  to  store protocol objects.
+When Sanic receives `SIGINT` or `SIGTERM`, Sanic executes `protocol.close_if_idle()` for a `protocol objects` stored in connections.
+
+* signal
+`signal` is a `sanic.server.Signal object` with `stopped attribute`.
+When Sanic receives `SIGINT` or `SIGTERM`, `signal.stopped` becomes `True`.
+
+* request_handler
+`request_handler` is a coroutine that takes a `sanic.request.Request` object and a `response callback` as arguments.
+
+* error_handler
+`error_handler` is a `sanic.exceptions.Handler` object.
+
+* request_timeout
+`request_timeout` is seconds for timeout.
+
+* request_max_size
+`request_max_size` is bytes of max request size.
+
+## Example
+
+```python
+from sanic import Sanic
+from sanic.server import HttpProtocol
+from sanic.response import text
+
+app = Sanic(__name__)
+
+
+class CustomHttpProtocol(HttpProtocol):
+
+    def __init__(self, *, loop, request_handler, error_handler,
+                 signal, connections, request_timeout, request_max_size):
+        super().__init__(
+            loop=loop, request_handler=request_handler,
+            error_handler=error_handler, signal=signal,
+            connections=connections, request_timeout=request_timeout,
+            request_max_size=request_max_size)
+
+    def write_response(self, response):
+        if isinstance(response, str):
+            response = text(response)
+        self.transport.write(
+            response.output(self.request.version)
+        )
+        self.transport.close()
+
+
+@app.route('/')
+async def string(request):
+    return 'string'
+
+
+@app.route('/1')
+async def response(request):
+    return text('response')
+
+app.run(host='0.0.0.0', port=8000, protocol=CustomHttpProtocol)
+```
diff --git a/examples/custom_protocol.py b/examples/custom_protocol.py
deleted file mode 100644
index d1df8fde..00000000
--- a/examples/custom_protocol.py
+++ /dev/null
@@ -1,28 +0,0 @@
-from sanic import Sanic
-from sanic.server import HttpProtocol
-from sanic.response import text
-
-app = Sanic(__name__)
-
-
-class CustomHttpProtocol(HttpProtocol):
-
-    def write_response(self, response):
-        if isinstance(response, str):
-            response = text(response)
-        self.transport.write(
-            response.output(self.request.version)
-        )
-        self.transport.close()
-
-
-@app.route('/')
-async def string(request):
-    return 'string'
-
-
-@app.route('/1')
-async def response(request):
-    return text('response')
-
-app.run(host='0.0.0.0', port=8000, protocol=CustomHttpProtocol)
diff --git a/sanic/sanic.py b/sanic/sanic.py
index 87f12ac3..e3115a69 100644
--- a/sanic/sanic.py
+++ b/sanic/sanic.py
@@ -251,7 +251,7 @@ class Sanic:
         :param workers: Number of processes
         received before it is respected
         :param loop: asyncio compatible event loop
-        :param protocol: Subclass of asyncio.Protocol
+        :param protocol: Subclass of asyncio protocol class
         :return: Nothing
         """
         self.error_handler.debug = True
diff --git a/sanic/server.py b/sanic/server.py
index 74e834b4..ffaf2d22 100644
--- a/sanic/server.py
+++ b/sanic/server.py
@@ -245,7 +245,7 @@ def serve(host, port, request_handler, error_handler, before_start=None,
     :param request_max_size: size in bytes, `None` for no limit
     :param reuse_port: `True` for multiple workers
     :param loop: asyncio compatible event loop
-    :param protocol: Subclass of asyncio.Protocol
+    :param protocol: Subclass of asyncio protocol class
     :return: Nothing
     """
     loop = loop or async_loop.new_event_loop()