Skip to content

Commit

Permalink
Multipart doc (aio-libs#2459)
Browse files Browse the repository at this point in the history 
* Convert a part of multipart's doc

* Fix aio-libs#2395: get rid of autodoc in multipart.

* Fix typo
  • Loading branch information
@asvetlov
asvetlov authored Nov 3, 2017
1 parent 04f59e7 commit 1049c86
Show file tree
Hide file tree
Showing 3 changed files with 192 additions and 91 deletions.
112 changes: 31 additions & 81 deletions aiohttp/multipart.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,8 +162,11 @@ def content_disposition_filename(params, name='filename'):


class MultipartResponseWrapper(object):
"""Wrapper around the :class:`MultipartBodyReader` to take care about
underlying connection and close it when it needs in."""
"""Wrapper around the MultipartBodyReader.
It takes care about
underlying connection and close it when it needs in.
"""

def __init__(self, resp, stream):
self.resp = resp
Expand All @@ -180,10 +183,7 @@ def __anext__(self):
return part

def at_eof(self):
"""Returns ``True`` when all response data had been read.
:rtype: bool
"""
"""Returns True when all response data had been read."""
return self.resp.content.at_eof()

async def next(self):
Expand Down Expand Up @@ -238,11 +238,9 @@ def next(self):
def read(self, *, decode=False):
"""Reads body part data.
:param bool decode: Decodes data following by encoding
method from `Content-Encoding` header. If it missed
data remains untouched
:rtype: bytearray
decode: Decodes data following by encoding
method from Content-Encoding header. If it missed
data remains untouched
"""
if self._at_eof:
return b''
Expand All @@ -257,9 +255,7 @@ def read(self, *, decode=False):
def read_chunk(self, size=chunk_size):
"""Reads body part content chunk of the specified size.
:param int size: chunk size
:rtype: bytearray
size: chunk size
"""
if self._at_eof:
return b''
Expand All @@ -278,27 +274,17 @@ def read_chunk(self, size=chunk_size):
return chunk

async def _read_chunk_from_length(self, size):
"""Reads body part content chunk of the specified size.
The body part must has `Content-Length` header with proper value.
:param int size: chunk size
:rtype: bytearray
"""
# Reads body part content chunk of the specified size.
# The body part must has Content-Length header with proper value.
assert self._length is not None, \
'Content-Length required for chunked read'
chunk_size = min(size, self._length - self._read_bytes)
chunk = await self._content.read(chunk_size)
return chunk

async def _read_chunk_from_stream(self, size):
"""Reads content chunk of body part with unknown length.
The `Content-Length` header for body part is not necessary.
:param int size: chunk size
:rtype: bytearray
"""
# Reads content chunk of body part with unknown length.
# The Content-Length header for body part is not necessary.
assert size >= len(self._boundary) + 2, \
'Chunk size must be greater or equal than boundary length + 2'
first_chunk = self._prev_chunk is None
Expand Down Expand Up @@ -328,10 +314,7 @@ async def _read_chunk_from_stream(self, size):

@asyncio.coroutine
def readline(self):
"""Reads body part by line by line.
:rtype: bytearray
"""
"""Reads body part by line by line."""
if self._at_eof:
return b''

Expand Down Expand Up @@ -361,24 +344,15 @@ def readline(self):

@asyncio.coroutine
def release(self):
"""Like :meth:`read`, but reads all the data to the void.
:rtype: None
"""
"""Like read(), but reads all the data to the void."""
if self._at_eof:
return
while not self._at_eof:
yield from self.read_chunk(self.chunk_size)

@asyncio.coroutine
def text(self, *, encoding=None):
"""Like :meth:`read`, but assumes that body part contains text data.
:param str encoding: Custom text encoding. Overrides specified
in charset param of `Content-Type` header
:rtype: str
"""
"""Like read(), but assumes that body part contains text data."""
data = yield from self.read(decode=True)
# see https://www.w3.org/TR/html5/forms.html#multipart/form-data-encoding-algorithm # NOQA
# and https://dvcs.w3.org/hg/xhr/raw-file/tip/Overview.html#dom-xmlhttprequest-send # NOQA
Expand All @@ -387,11 +361,7 @@ def text(self, *, encoding=None):

@asyncio.coroutine
def json(self, *, encoding=None):
"""Like :meth:`read`, but assumes that body parts contains JSON data.
:param str encoding: Custom JSON encoding. Overrides specified
in charset param of `Content-Type` header
"""
"""Like read(), but assumes that body parts contains JSON data."""
data = yield from self.read(decode=True)
if not data:
return None
Expand All @@ -400,11 +370,8 @@ def json(self, *, encoding=None):

@asyncio.coroutine
def form(self, *, encoding=None):
"""Like :meth:`read`, but assumes that body parts contains form
"""Like read(), but assumes that body parts contains form
urlencoded data.
:param str encoding: Custom form encoding. Overrides specified
in charset param of `Content-Type` header
"""
data = yield from self.read(decode=True)
if not data:
Expand All @@ -415,28 +382,12 @@ def form(self, *, encoding=None):
encoding=encoding)

def at_eof(self):
"""Returns ``True`` if the boundary was reached or
``False`` otherwise.
:rtype: bool
"""
"""Returns True if the boundary was reached or False otherwise."""
return self._at_eof

def decode(self, data):
"""Decodes data according the specified `Content-Encoding`
or `Content-Transfer-Encoding` headers value.
Supports ``gzip``, ``deflate`` and ``identity`` encodings for
`Content-Encoding` header.
Supports ``base64``, ``quoted-printable``, ``binary`` encodings for
`Content-Transfer-Encoding` header.
:param bytearray data: Data to decode.
:raises: :exc:`RuntimeError` - if encoding is unknown.
:rtype: bytes
"""Decodes data according the specified Content-Encoding
or Content-Transfer-Encoding headers value.
"""
if CONTENT_TRANSFER_ENCODING in self.headers:
data = self._decode_content_transfer(data)
Expand Down Expand Up @@ -470,24 +421,25 @@ def _decode_content_transfer(self, data):
''.format(encoding))

def get_charset(self, default=None):
"""Returns charset parameter from ``Content-Type`` header or default.
"""
"""Returns charset parameter from Content-Type header or default."""
ctype = self.headers.get(CONTENT_TYPE, '')
mimetype = parse_mimetype(ctype)
return mimetype.parameters.get('charset', default)

@reify
def name(self):
"""Returns filename specified in Content-Disposition header or ``None``
if missed or header is malformed."""
"""Returns name specified in Content-Disposition header or None
if missed or header is malformed.
"""
_, params = parse_content_disposition(
self.headers.get(CONTENT_DISPOSITION))
return content_disposition_filename(params, 'name')

@reify
def filename(self):
"""Returns filename specified in Content-Disposition header or ``None``
if missed or header is malformed."""
"""Returns filename specified in Content-Disposition header or None
if missed or header is malformed.
"""
_, params = parse_content_disposition(
self.headers.get(CONTENT_DISPOSITION))
return content_disposition_filename(params, 'filename')
Expand Down Expand Up @@ -557,10 +509,8 @@ def from_response(cls, response):
return obj

def at_eof(self):
"""Returns ``True`` if the final boundary was reached or
``False`` otherwise.
:rtype: bool
"""Returns True if the final boundary was reached or
False otherwise.
"""
return self._at_eof

Expand Down
9 changes: 0 additions & 9 deletions docs/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -210,12 +210,3 @@ For concrete usage examples see :ref:`signals in aiohttp.web
.. method:: freeze()

Freeze the list. After the call any content modification is forbidden.


aiohttp.multipart module
------------------------

.. automodule:: aiohttp.multipart
:members:
:undoc-members:
:show-inheritance:
Loading

0 comments on commit 1049c86

Please sign in to comment.