Resp prepare

CHANGES.txt

@@ -2,7 +2,7 @@ CHANGES
 =======
 
 0.18.0a0 (XX-XX-XXXX)
--------------------
+---------------------
 
 - Use errors.HttpProcessingError.message as HTTP error reason and
   message #459

aiohttp/web.py

@@ -92,7 +92,7 @@ def handle_request(self, message, payload):
         except HTTPException as exc:
             resp = exc
 
-        resp_msg = resp.start(request)
+        resp_msg = yield from resp.prepare(request)
         yield from resp.write_eof()
 
         # notify server about keep-alive

aiohttp/web_reqrep.py

@@ -425,9 +425,14 @@ def _copy_cookies(self):
             self.headers.add(hdrs.SET_COOKIE, value)
 
     @property
-    def started(self):
+    def prepared(self):
         return self._resp_impl is not None
 
+    @property
+    def started(self):
+        warnings.warn('use Response.prepared instead', DeprecationWarning)
+        return self.prepared
+
     @property
     def status(self):
         return self._status
@@ -612,27 +617,39 @@ def _start_pre_check(self, request):
             return None
 
     def _start_compression(self, request):
-        def start(coding):
+        def _start(coding):
             if coding != ContentCoding.identity:
                 self.headers[hdrs.CONTENT_ENCODING] = coding.value
                 self._resp_impl.add_compression_filter(coding.value)
                 self.content_length = None
 
         if self._compression_force:
-            start(self._compression_force)
+            _start(self._compression_force)
         else:
             accept_encoding = request.headers.get(
                 hdrs.ACCEPT_ENCODING, '').lower()
             for coding in ContentCoding:
                 if coding.value in accept_encoding:
-                    start(coding)
+                    _start(coding)
                     return
 
     def start(self, request):
+        warnings.warn('use .prepare(request) instead', DeprecationWarning)
         resp_impl = self._start_pre_check(request)
         if resp_impl is not None:
             return resp_impl
 
+        return self._start(request)
+
+    @asyncio.coroutine
+    def prepare(self, request):
+        resp_impl = self._start_pre_check(request)
+        if resp_impl is not None:
+            return resp_impl
+
+        return self._start(request)
+
+    def _start(self, request):
         self._req = request
         keep_alive = self._keep_alive
         if keep_alive is None:

aiohttp/web_urldispatcher.py

@@ -281,7 +281,7 @@ def handle(self, request):
         file_size = st.st_size
 
         resp.content_length = file_size
-        resp.start(request)
+        yield from resp.prepare(request)
 
         with open(filepath, 'rb') as f:
             yield from self._sendfile(request, resp, f, file_size)

aiohttp/web_ws.py

@@ -35,12 +35,19 @@ def __init__(self, *,
         self._autoclose = autoclose
         self._autoping = autoping
 
-    def start(self, request):
+    @asyncio.coroutine
+    def prepare(self, request):
         # make pre-check to don't hide it by do_handshake() exceptions
         resp_impl = self._start_pre_check(request)
         if resp_impl is not None:
             return resp_impl
 
+        parser, protocol, writer = self._pre_start(request)
+        resp_impl = yield from super().prepare(request)
+        self._post_start(request, parser, protocol, writer)
+        return resp_impl
+
+    def _pre_start(self, request):
         try:
             status, headers, parser, writer, protocol = do_handshake(
                 request.method, request.headers, request.transport,
@@ -59,17 +66,27 @@ def start(self, request):
         for k, v in headers:
             self.headers[k] = v
         self.force_close()
+        return parser, protocol, writer
 
-        resp_impl = super().start(request)
-
+    def _post_start(self, request, parser, protocol, writer):
         self._reader = request._reader.set_parser(parser)
         self._writer = writer
         self._protocol = protocol
         self._loop = request.app.loop
 
+    def start(self, request):
+        warnings.warn('use .prepare(request) instead', DeprecationWarning)
+        # make pre-check to don't hide it by do_handshake() exceptions
+        resp_impl = self._start_pre_check(request)
+        if resp_impl is not None:
+            return resp_impl
+
+        parser, protocol, writer = self._pre_start(request)
+        resp_impl = super().start(request)
+        self._post_start(request, parser, protocol, writer)
         return resp_impl
 
-    def can_start(self, request):
+    def can_prepare(self, request):
         if self._writer is not None:
             raise RuntimeError('Already started')
         try:
@@ -81,6 +98,10 @@ def can_start(self, request):
         else:
             return True, protocol
 
+    def can_start(self, request):
+        warnings.warn('use .can_prepare(request) instead', DeprecationWarning)
+        return self.can_prepare(request)
+
     @property
     def closed(self):
         return self._closed
@@ -98,22 +119,22 @@ def exception(self):
 
     def ping(self, message='b'):
         if self._writer is None:
-            raise RuntimeError('Call .start() first')
+            raise RuntimeError('Call .prepare() first')
         if self._closed:
             raise RuntimeError('websocket connection is closing')
         self._writer.ping(message)
 
     def pong(self, message='b'):
         # unsolicited pong
         if self._writer is None:
-            raise RuntimeError('Call .start() first')
+            raise RuntimeError('Call .prepare() first')
         if self._closed:
             raise RuntimeError('websocket connection is closing')
         self._writer.pong(message)
 
     def send_str(self, data):
         if self._writer is None:
-            raise RuntimeError('Call .start() first')
+            raise RuntimeError('Call .prepare() first')
         if self._closed:
             raise RuntimeError('websocket connection is closing')
         if not isinstance(data, str):
@@ -122,7 +143,7 @@ def send_str(self, data):
 
     def send_bytes(self, data):
         if self._writer is None:
-            raise RuntimeError('Call .start() first')
+            raise RuntimeError('Call .prepare() first')
         if self._closed:
             raise RuntimeError('websocket connection is closing')
         if not isinstance(data, (bytes, bytearray, memoryview)):
@@ -151,7 +172,7 @@ def write_eof(self):
     @asyncio.coroutine
     def close(self, *, code=1000, message=b''):
         if self._writer is None:
-            raise RuntimeError('Call .start() first')
+            raise RuntimeError('Call .prepare() first')
 
         if not self._closed:
             self._closed = True
@@ -190,7 +211,7 @@ def close(self, *, code=1000, message=b''):
     @asyncio.coroutine
     def receive(self):
         if self._reader is None:
-            raise RuntimeError('Call .start() first')
+            raise RuntimeError('Call .prepare() first')
         if self._waiting:
             raise RuntimeError('Concurrent call to receive() is not allowed')
 
@@ -239,7 +260,7 @@ def receive(self):
             self._waiting = False
 
     @asyncio.coroutine
-    def receive_msg(self):  # pragma: no cover
+    def receive_msg(self):
         warnings.warn(
             'receive_msg() coroutine is deprecated. use receive() instead',
             DeprecationWarning)

docs/web.rst

@@ -407,7 +407,7 @@ using response's methods:
     def websocket_handler(request):
 
         ws = web.WebSocketResponse()
-        ws.start(request)
+        yield from ws.prepare(request)
 
         while True:
             msg = yield from ws.receive()

docs/web_reference.rst

@@ -339,11 +339,10 @@ StreamResponse
    The most important thing you should know about *response* --- it
    is *Finite State Machine*.
 
-   That means you can do any manipulations with *headers*,
-   *cookies* and *status code* only before :meth:`start`
-   called.
+   That means you can do any manipulations with *headers*, *cookies*
+   and *status code* only before :meth:`prepare` coroutine is called.
 
-   Once you call :meth:`start` any change of
+   Once you call :meth:`prepare` any change of
    the *HTTP header* part will raise :exc:`RuntimeError` exception.
 
    Any :meth:`write` call after :meth:`write_eof` is also forbidden.
@@ -355,11 +354,19 @@ StreamResponse
                       parameter. Otherwise pass :class:`str` with
                       arbitrary *status* explanation..
 
-   .. attribute:: started
+   .. attribute:: prepared
 
-      Read-only :class:`bool` property, ``True`` if :meth:`start` has
+      Read-only :class:`bool` property, ``True`` if :meth:`prepare` has
       been called, ``False`` otherwise.
 
+      .. versionadded:: 0.18
+
+   .. attribute:: started
+
+      Deprecated alias for :attr:`prepared`.
+
+      .. deprecated:: 0.18
+
    .. attribute:: status
 
       Read-only property for *HTTP response status code*, :class:`int`.
@@ -550,16 +557,30 @@ StreamResponse
       Send *HTTP header*. You should not change any header data after
       calling this method.
 
+      .. deprecated:: 0.18
+
+         Use :meth:`prepare` instead.
+
+   .. coroutinemethod:: prepare(request)
+
+      :param aiohttp.web.Request request: HTTP request object, that the
+                                          response answers.
+
+      Send *HTTP header*. You should not change any header data after
+      calling this method.
+
+      .. versionadded:: 0.18
+
    .. method:: write(data)
 
       Send byte-ish data as the part of *response BODY*.
 
-      :meth:`start` must be called before.
+      :meth:`prepare` must be called before.
 
       Raises :exc:`TypeError` if data is not :class:`bytes`,
       :class:`bytearray` or :class:`memoryview` instance.
 
-      Raises :exc:`RuntimeError` if :meth:`start` has not been called.
+      Raises :exc:`RuntimeError` if :meth:`prepare` has not been called.
 
       Raises :exc:`RuntimeError` if :meth:`write_eof` has been called.
 
@@ -651,11 +672,23 @@ WebSocketResponse
 
    Class for handling server-side websockets.
 
-   After starting (by :meth:`start` call) the response you
+   After starting (by :meth:`prepare` call) the response you
    cannot use :meth:`~StreamResponse.write` method but should to
    communicate with websocket client by :meth:`send_str`,
    :meth:`receive` and others.
 
+   .. coroutinemethod:: prepare(request)
+
+      Starts websocket. After the call you can use websocket methods.
+
+      :param aiohttp.web.Request request: HTTP request object, that the
+                                          response answers.
+
+
+      :raises HTTPException: if websocket handshake has failed.
+
+      .. versionadded:: 0.18
+
    .. method:: start(request)
 
       Starts websocket. After the call you can use websocket methods.
@@ -666,12 +699,17 @@ WebSocketResponse
 
       :raises HTTPException: if websocket handshake has failed.
 
-   .. method:: can_start(request)
+      .. deprecated:: 0.18
+
+         Use :meth:`prepare` instead.
+
+   .. method:: can_prepare(request)
 
       Performs checks for *request* data to figure out if websocket
       can be started on the request.
 
-      If :meth:`can_start` call is success then :meth:`start` will success too.
+      If :meth:`can_prepare` call is success then :meth:`prepare` will
+      success too.
 
       :param aiohttp.web.Request request: HTTP request object, that the
                                           response answers.
@@ -684,6 +722,12 @@ WebSocketResponse
 
       .. note:: The method never raises exception.
 
+   .. method:: can_start(request)
+
+      Deprecated alias for :meth:`can_prepare`
+
+      .. deprecated:: 0.18
+
    .. attribute:: closed
 
       Read-only property, ``True`` if connection has been closed or in process

examples/web_srv.py

@@ -15,7 +15,7 @@ def intro(request):
     binary = txt.encode('utf8')
     resp = StreamResponse()
     resp.content_length = len(binary)
-    resp.start(request)
+    yield from resp.prepare(request)
     resp.write(binary)
     return resp
 
@@ -36,7 +36,7 @@ def hello(request):
     name = request.match_info.get('name', 'Anonymous')
     answer = ('Hello, ' + name).encode('utf8')
     resp.content_length = len(answer)
-    resp.start(request)
+    yield from resp.prepare(request)
     resp.write(answer)
     yield from resp.write_eof()
     return resp

examples/web_ws.py

@@ -17,7 +17,7 @@ def wshandler(request):
         with open(WS_FILE, 'rb') as fp:
             return Response(body=fp.read(), content_type='text/html')
 
-    resp.start(request)
+    yield from resp.prepare(request)
     print('Someone joined.')
     for ws in request.app['sockets']:
         ws.send_str('Someone joined')

tests/autobahn/server.py

@@ -12,7 +12,7 @@ def wshandler(request):
     if not ok:
         return web.HTTPBadRequest()
 
-    ws.start(request)
+    yield from ws.prepare(request)
 
     while True:
         msg = yield from ws.receive()