89 lines
2.7 KiB
Markdown
89 lines
2.7 KiB
Markdown
# 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...
|
||
|
||
```python
|
||
>>> 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.
|
||
|
||
```python
|
||
>>> 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:
|
||
|
||
```python
|
||
>>> 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:
|
||
|
||
```python
|
||
>>> 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.
|
||
|
||
```python
|
||
>>> with httpx.Client() as cli:
|
||
... r = cli.get('https://www.example.com/')
|
||
... r.stream.read()
|
||
# ...
|
||
```
|
||
|
||
## GZipStream
|
||
|
||
...
|
||
|
||
---
|
||
|
||
<span class="link-prev">← [Content Types](content-types.md)</span>
|
||
<span class="link-next">[Connections](connections.md) →</span>
|
||
<span> </span>
|