1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
.. module:: aiohttp.streams
.. _aiohttp-streams:
Streaming API
=============
.. module:: aiohttp
.. currentmodule:: aiohttp
``aiohttp`` uses streams for retrieving *BODIES*:
:attr:`aiohttp.web.Request.content` and
:attr:`aiohttp.ClientResponse.content` are properties with stream API.
.. class:: StreamReader
The reader from incoming stream.
User should never instantiate streams manually but use existing
:attr:`aiohttp.web.Request.content` and
:attr:`aiohttp.ClientResponse.content` properties for accessing raw
BODY data.
Reading Methods
---------------
.. comethod:: StreamReader.read(n=-1)
Read up to *n* bytes. If *n* is not provided, or set to ``-1``, read until
EOF and return all read bytes.
If the EOF was received and the internal buffer is empty, return an
empty bytes object.
:param int n: how many bytes to read, ``-1`` for the whole stream.
:return bytes: the given data
.. comethod:: StreamReader.readany()
Read next data portion for the stream.
Returns immediately if internal buffer has a data.
:return bytes: the given data
.. comethod:: StreamReader.readexactly(n)
Read exactly *n* bytes.
Raise an :exc:`asyncio.IncompleteReadError` if the end of the
stream is reached before *n* can be read, the
:attr:`asyncio.IncompleteReadError.partial` attribute of the
exception contains the partial read bytes.
:param int n: how many bytes to read.
:return bytes: the given data
.. comethod:: StreamReader.readline()
Read one line, where “line” is a sequence of bytes ending
with ``\n``.
If EOF is received, and ``\n`` was not found, the method will
return the partial read bytes.
If the EOF was received and the internal buffer is empty, return an
empty bytes object.
:return bytes: the given line
Asynchronous Iteration Support
------------------------------
Stream reader supports asynchronous iteration over BODY.
By default it iterates over lines::
async for line in response.content:
print(line)
Also there are methods for iterating over data chunks with maximum
size limit and over any available data.
.. comethod:: StreamReader.iter_chunked(n)
:async-for:
Iterates over data chunks with maximum size limit::
async for data in response.content.iter_chunked(1024):
print(data)
.. comethod:: StreamReader.iter_any(n)
:async-for:
Iterates over data chunks in order of intaking them into the stream::
async for data in response.content.iter_any():
print(data)
Helpers
-------
.. method:: StreamReader.exception()
Get the exception occurred on data reading.
.. method:: is_eof()
Return ``True`` if EOF was reached.
Internal buffer may be not empty at the moment.
.. seealso::
:meth:`StreamReader.at_eof()`
.. method:: StreamReader.at_eof()
Return ``True`` if the buffer is empty and EOF was reached.
.. method:: StreamReader.read_nowait(n=None)
Returns data from internal buffer if any, empty bytes object otherwise.
Raises :exc:`RuntimeError` if other coroutine is waiting for stream.
:param int n: how many bytes to read, ``-1`` for the whole internal
buffer.
:return bytes: the given data
.. method:: StreamReader.unread_data(data)
Rollback reading some data from stream, inserting it to buffer head.
:param bytes data: data to push back into the stream.
.. warning:: The method doesn't wake up waiters.
E.g. :meth:`~StreamReader.read()` will not be resumed.
.. comethod:: wait_eof()
Wait for EOF. The given data may be accessible by upcoming read calls.
.. disqus::
:title: aiohttp streaming api
|
