Utilities for Downloading Streaming Reponses¶

requests_toolbelt.downloadutils.stream.stream_response_to_file(response, path=None)¶

Stream a response body to the specified file.

Either use the path provided or use the name provided in the Content-Disposition header.

Warning

If you pass this function an open file-like object as the path parameter, the function will not close that file for you.

Warning

This function will not automatically close the response object passed in as the response parameter.

If no path parameter is supplied, this function will parse the Content-Disposition header on the response to determine the name of the file as reported by the server.

import requests
from requests_toolbelt import exceptions
from requests_toolbelt.downloadutils import stream

r = requests.get(url, stream=True)
try:
    filename = stream.stream_response_to_file(r)
except exceptions.StreamingError as e:
    # The toolbelt could not find the filename in the
    # Content-Disposition
    print(e.message)

You can also specify the filename as a string. This will be passed to the built-in open() and we will read the content into the file.

import requests
from requests_toolbelt.downloadutils import stream

r = requests.get(url, stream=True)
filename = stream.stream_response_to_file(r, path='myfile')

Instead, if you want to manage the file object yourself, you need to provide either a io.BytesIO object or a file opened with the ‘b’ flag. See the two examples below for more details.

import requests
from requests_toolbelt.downloadutils import stream

with open('myfile', 'wb') as fd:
    r = requests.get(url, stream=True)
    filename = stream.stream_response_to_file(r, path=fd)

print('{0} saved to {1}'.format(url, filename))

import io
import requests
from requests_toolbelt.downloadutils import stream

b = io.BytesIO()
r = requests.get(url, stream=True)
filename = stream.stream_response_to_file(r, path=b)
assert filename is None

Parameters:	response (requests.models.Response) – A Response object from requests path (`str`, or object with a `write()`) – (optional), Either a string with the path to the location to save the response content, or a file-like object expecting bytes.
Returns:	The name of the file, if one can be determined, else None
Return type:	str
Raises:	`requests_toolbelt.exceptions.StreamingError`