Streams

Streams provide a minimal file-like interface for reading bytes from a data source. They are used as the abstraction for reading the body of a request or response.

The interfaces here are simplified versions of Python's standard I/O operations.

Stream

The base Stream class. The core of the interface is a subset of Python's io.IOBase...

• .read(size=-1) - (bytes) Return the bytes from the data stream. If the size argument is omitted or negative then the entire stream will be read. If size is an positive integer then the call returns at most size bytes. A return value of b'' indicates the end of the stream has been reached.
• .write(self, data: bytes) - None Write the given bytes to the data stream. May raise NotImplmentedError if this is not a writeable stream.
• .close() - Close the stream. Any further operations will raise a ValueError.

Additionally, the following property is also defined...

• .size - (int or None) Return an integer indicating the size of the stream, or None if the size is unknown. When working with HTTP this is used to either set a Content-Length: <size> header, or a Content-Encoding: chunked header.

The Stream interface and ContentType interface are related, with streams being used as the abstraction for the bytewise representation, and content types being used to encapsulate the parsed data structure.

For example, encoding some JSON data...

>>> data = httpx.JSON({'name': 'zelda', 'score': '478'})
>>> stream = data.encode()
>>> stream.read()
b'{"name":"zelda","score":"478"}'
>>> stream.content_type
'application/json'

ByteStream

A byte stream returning fixed byte content. Similar to Python's io.BytesIO class.

>>> s = httpx.ByteStream(b'{"msg": "Hello, world!"}')
>>> s.read()
b'{"msg": "Hello, world!"}'

FileStream

A byte stream returning content from a file.

The standard pattern for instantiating a FileStream is to use File as a context manager:

>>> with httpx.File('upload.json') as s:
...     s.read()
b'{"msg": "Hello, world!"}'

MultiPartStream

A byte stream returning multipart upload data.

The standard pattern for instantiating a MultiPartStream is to use MultiPart as a context manager:

>>> files = {'avatar-upload': 'image.png'}
>>> with httpx.MultiPart(files=files) as s:
...     s.read()
# ...

HTTPStream

A byte stream returning unparsed content from an HTTP request or response.

>>> with httpx.Client() as cli:
...     r = cli.get('https://www.example.com/')
...     r.stream.read()
# ...

GZipStream

...

← Content Types Connections →