Skip to content

Commit

Permalink
Fix docs and examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@asvetlov
asvetlov committed Aug 6, 2016
1 parent 4b79127 commit 058a256
Show file tree
Hide file tree
Showing 8 changed files with 72 additions and 69 deletions.
50 changes: 25 additions & 25 deletions docs/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,36 +17,36 @@ WebSocket utilities

An :class:`~enum.IntEnum` for keeping close message code.

.. attribute:: ok
.. attribute:: OK

A normal closure, meaning that the purpose for
which the connection was established has been fulfilled.

.. attribute:: going_away
.. attribute:: GOING_AWAY

An endpoint is "going away", such as a server
going down or a browser having navigated away from a page.

.. attribute:: protocol_error
.. attribute:: PROTOCOL_ERROR

An endpoint is terminating the connection due
to a protocol error.

.. attribute:: unsupported_data
.. attribute:: UNSUPPORTED_DATA

An endpoint is terminating the connection
because it has received a type of data it cannot accept (e.g., an
endpoint that understands only text data MAY send this if it
receives a binary message).

.. attribute:: invalid_text
.. attribute:: INVALID_TEXT

An endpoint is terminating the connection
because it has received data within a message that was not
consistent with the type of the message (e.g., non-UTF-8 :rfc:`3629`
data within a text message).

.. attribute:: policy_violation
.. attribute:: POLICY_VIOLATION

An endpoint is terminating the connection because it has
received a message that violates its policy. This is a generic
Expand All @@ -56,13 +56,13 @@ WebSocket utilities
:attr:`~WSCloseCode.message_too_big`) or if there is a need to
hide specific details about the policy.

.. attribute:: message_too_big
.. attribute:: MESSAGE_TOO_BIG

An endpoint is terminating the connection
because it has received a message that is too big for it to
process.

.. attribute:: mandatory_extension
.. attribute:: MANDATORY_EXTENSION

An endpoint (client) is terminating the
connection because it has expected the server to negotiate one or
Expand All @@ -72,18 +72,18 @@ WebSocket utilities
Note that this status code is not used by the server, because it
can fail the WebSocket handshake instead.

.. attribute:: internal_error
.. attribute:: INTERNAL_ERROR

A server is terminating the connection because
it encountered an unexpected condition that prevented it from
fulfilling the request.

.. attribute:: service_restart
.. attribute:: SERVICE_RESTART

The service is restarted. a client may reconnect, and if it
choses to do, should reconnect using a randomized delay of 5-30s.

.. attribute:: try_again_later
.. attribute:: TRY_AGAIN_LATER

The service is experiencing overload. A client should only
connect to a different IP (when there are multiple for the
Expand All @@ -94,37 +94,37 @@ WebSocket utilities

An :class:`~enum.IntEnum` for describing :class:`WSMessage` type.

.. attribute:: continuation
.. attribute:: CONTINUATION

A mark for continuation frame, user will never get the message
with this type.

.. attribute:: text
.. attribute:: TEXT

Text messsage, the value has :class:`str` type.

.. attribute:: binary
.. attribute:: BINARY

Binary messsage, the value has :class:`bytes` type.

.. attribute:: ping
.. attribute:: PING

Ping frame (sent by client peer).

.. attribute:: pong
.. attribute:: PONG

Pong frame, answer on ping. Sent by server peer.

.. attribute:: close
.. attribute:: CLOSE

Close frame.

.. attribute:: closed frame
.. attribute:: CLOSED FRAME

Actually not frame but a flag indicating that websocket was
closed.

.. attribute:: error
.. attribute:: ERROR

Actually not frame but a flag indicating that websocket was
received an error.
Expand All @@ -142,21 +142,21 @@ WebSocket utilities

Message payload.

1. :class:`str` for :attr:`WSMsgType.text` messages.
1. :class:`str` for :attr:`WSMsgType.TEXT` messages.

2. :class:`bytes` for :attr:`WSMsgType.text` messages.
2. :class:`bytes` for :attr:`WSMsgType.TEXT` messages.

3. :class:`WSCloseCode` for :attr:`WSMsgType.close` messages.
3. :class:`WSCloseCode` for :attr:`WSMsgType.CLOSE` messages.

4. :class:`bytes` for :attr:`WSMsgType.ping` messages.
4. :class:`bytes` for :attr:`WSMsgType.PING` messages.

5. :class:`bytes` for :attr:`WSMsgType.pong` messages.
5. :class:`bytes` for :attr:`WSMsgType.PONG` messages.

.. attribute:: extra

Additional info, :class:`str`.

Makes sense only for :attr:`WSMsgType.close` messages, contains
Makes sense only for :attr:`WSMsgType.CLOSE` messages, contains
optional message description.

.. method:: json(*, loads=json.loads)
Expand Down
6 changes: 3 additions & 3 deletions docs/client.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -642,15 +642,15 @@ methods::
async with session.ws_connect('http://example.org/websocket') as ws:

async for msg in ws:
if msg.tp == aiohttp.WSMsgType.text:
if msg.tp == aiohttp.WSMsgType.TEXT:
if msg.data == 'close cmd':
await ws.close()
break
else:
ws.send_str(msg.data + '/answer')
elif msg.tp == aiohttp.WSMsgType.closed:
elif msg.tp == aiohttp.WSMsgType.CLOSED:
break
elif msg.tp == aiohttp.WSMsgType.error:
elif msg.tp == aiohttp.WSMsgType.ERROR:
break


Expand Down
26 changes: 13 additions & 13 deletions docs/client_reference.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1251,7 +1251,7 @@ manually.
.. attribute:: closed

Read-only property, ``True`` if :meth:`close` has been called of
:const:`~aiohttp.WSMsgType.close` message has been received from peer.
:const:`~aiohttp.WSMsgType.CLOSE` message has been received from peer.

.. attribute:: protocol

Expand All @@ -1266,23 +1266,23 @@ manually.

.. method:: ping(message=b'')

Send :const:`~aiohttp.WSMsgType.ping` to peer.
Send :const:`~aiohttp.WSMsgType.PING` to peer.

:param message: optional payload of *ping* message,
:class:`str` (converted to *UTF-8* encoded bytes)
or :class:`bytes`.

.. method:: send_str(data)

Send *data* to peer as :const:`~aiohttp.WSMsgType.text` message.
Send *data* to peer as :const:`~aiohttp.WSMsgType.TEXT` message.

:param str data: data to send.

:raise TypeError: if data is not :class:`str`

.. method:: send_bytes(data)

Send *data* to peer as :const:`~aiohttp.WSMsgType.binary` message.
Send *data* to peer as :const:`~aiohttp.WSMsgType.BINARY` message.

:param data: data to send.

Expand All @@ -1309,7 +1309,7 @@ manually.
.. comethod:: close(*, code=1000, message=b'')

A :ref:`coroutine<coroutine>` that initiates closing handshake by sending
:const:`~aiohttp.WSMsgType.close` message. It waits for
:const:`~aiohttp.WSMsgType.CLOSE` message. It waits for
close response from server. It add timeout to `close()` call just wrap
call with `asyncio.wait()` or `asyncio.wait_for()`.

Expand All @@ -1325,9 +1325,9 @@ manually.
message from peer and returns it.

The coroutine implicitly handles
:const:`~aiohttp.WSMsgType.ping`,
:const:`~aiohttp.WSMsgType.pong` and
:const:`~aiohttp.WSMsgType.close` without returning the
:const:`~aiohttp.WSMsgType.PING`,
:const:`~aiohttp.WSMsgType.PONG` and
:const:`~aiohttp.WSMsgType.CLOSE` without returning the
message.

It process *ping-pong game* and performs *closing handshake* internally.
Expand All @@ -1339,21 +1339,21 @@ manually.

A :ref:`coroutine<coroutine>` that calls :meth:`receive` but
also asserts the message type is
:const:`~aiohttp.WSMsgType.text`.
:const:`~aiohttp.WSMsgType.TEXT`.

:return str: peer's message content.

:raise TypeError: if message is :const:`~aiohttp.WSMsgType.binary`.
:raise TypeError: if message is :const:`~aiohttp.WSMsgType.BINARY`.

.. coroutinemethod:: receive_bytes()

A :ref:`coroutine<coroutine>` that calls :meth:`receive` but
also asserts the message type is
:const:`~aiohttp.WSMsgType.binary`.
:const:`~aiohttp.WSMsgType.BINARY`.

:return bytes: peer's message content.

:raise TypeError: if message is :const:`~aiohttp.WSMsgType.text`.
:raise TypeError: if message is :const:`~aiohttp.WSMsgType.TEXT`.

.. coroutinemethod:: receive_json(*, loads=json.loads)

Expand All @@ -1367,7 +1367,7 @@ manually.

:return dict: loaded JSON content

:raise TypeError: if message is :const:`~aiohttp.WSMsgType.binary`.
:raise TypeError: if message is :const:`~aiohttp.WSMsgType.BINARY`.
:raise ValueError: if message is not valid JSON.

Utilities
Expand Down
4 changes: 3 additions & 1 deletion docs/testing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -218,8 +218,10 @@ conditions that hard to reproduce on real server::
aiohttp.test_utils
------------------

.. _pytest: http://pytest.org/latest/
.. automodule:: aiohttp.test_utils
:members: TestClient, AioHTTPTestCase, run_loop, loop_context, setup_test_loop, teardown_test_loop make_mocked_request
:undoc-members:
:show-inheritance:


.. _pytest: http://pytest.org/latest/
4 changes: 2 additions & 2 deletions docs/web.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -522,12 +522,12 @@ with the peer::
await ws.prepare(request)

async for msg in ws:
if msg.tp == aiohttp.WSMsgType.text:
if msg.tp == aiohttp.WSMsgType.TEXT:
if msg.data == 'close':
await ws.close()
else:
ws.send_str(msg.data + '/answer')
elif msg.tp == aiohttp.WSMsgType.error:
elif msg.tp == aiohttp.WSMsgType.ERROR:
print('ws connection closed with exception %s' %
ws.exception())

Expand Down
Loading

0 comments on commit 058a256

Please sign in to comment.