pylegs.io.download_file

download_file(url: str, save_path: str | Path | BytesIO = None, query: Dict[str, Any] = None, overwrite: bool = False, http_client: Session = None, extract: bool = False, timeout: int | float = None) → bytes | None

Download a file from a URL and save it to a specified path.

Parameters:

urlstr

The URL from which to download the file.

save_pathPathOrFile

The path where the downloaded file will be saved. This can be a string or a pathlib.Path object.

queryDict[str, Any], optional

A dictionary of query parameters to include in the request. Defaults to None.

overwritebool, optional

If True, overwrite the existing file at save_path. Defaults to False.

http_clientrequests.Session, optional

The HTTP client to use for making the request. If None, the requests library is used. Defaults to None.

extractbool, optional

If True, decompress the downloaded file if it is in bz2 format. Defaults to False.

Returns:

bytes or None

The bytes of the downloaded (and possibly decompressed) file, or None if the file already exists and overwrite is False.

Raises:

Exception

If the HTTP request fails or if there is an error in writing the file.

Notes

• If overwrite is False and the file already exists at save_path, the function returns None without downloading the file.

• If extract is True, the function assumes the file is compressed with bz2 and decompresses it before saving.

Examples

>>> download_file('http://example.com/file.txt', 'file.txt')
b'file content'

>>> download_file('http://example.com/file.bz2', 'file.txt', extract=True)
b'decompressed content'