API reference

Everything below is importable from browser_download_filename. See Usage for examples.

suggested_filename

def suggested_filename(
    headers: HeadersLike | None = None,
    *,
    url: str | None = None,
    content_disposition: str | bytes | None = None,
    content_type: str | bytes | None = None,
    download_attribute: str | None = None,
    default_name: str | None = "download",
    fallback_charset: str | None = None,
    headers_encoding: str | None = None,
    platform: Literal["posix", "windows"] | None = None,
) -> str

The file name Chromium suggests for a download (net::GetSuggestedFilename), which is the name Chrome reports to DevTools and Playwright, except in the cases listed under Limits of the port. It is never empty.

sanitize_filename

def sanitize_filename(
    name: str,
    *,
    default_name: str = "download",
    platform: Literal["posix", "windows"] | None = None,
) -> str

Chrome's file name cleaning, applied to a name from anywhere, such as a page title or user input. The result is what suggested_filename(download_attribute=name, default_name=default_name, platform=platform) returns: name is cleaned as Chrome cleans an <a download> value. It is never empty.

HeadersLike

HeadersLike = SupportsHeaderItems | Iterable[tuple[str | bytes, HeaderValue]]

The type of a response's headers, in the shapes HTTP libraries hold them:

• an object with an items() method (SupportsHeaderItems), such as a dict, the http.client.HTTPMessage that urllib.request gives as response.headers, the urllib3 headers that requests gives as response.raw.headers, or the response.headers of requests, httpx and httpx2; the package calls items();
• otherwise, an iterable of (name, value) pairs, such as a list of tuples, the response.headers.raw of httpx and httpx2, or aiohttp's response.raw_headers.

A name is a str or bytes, matched as Reading header lines describes. A value (HeaderValue) is a str or bytes, or a list or tuple of them, one for each header line. The lines keep their order, and repeated lines all count. The headers are read only once, so a generator works too.

Each value is the rest of its header line as it was sent. It can hold line breaks, which are read as Chrome reads them: a line that starts with a space or a tab is joined on, and any other line, or a blank line, ends the value (see Reading header lines). The same goes for the values of content_disposition, content_type and parse_content_disposition.

A str or bytes is not headers: suggested_filename raises TypeError for one; pass a single Content-Disposition value as content_disposition.

parse_content_disposition

def parse_content_disposition(
    value: str | bytes | HeadersLike | None,
    /,
    *,
    fallback_charset: str | None = None,
    headers_encoding: str | None = None,
) -> ContentDisposition

Parses Content-Disposition as Chromium's net::HttpContentDisposition does. value is one header, as bytes or as the str an HTTP library produced; or a response's headers (see HeadersLike), of which every Content-Disposition line is read; None stands for a missing header. type and filename come from the first comma-separated value of the first line, which is the value Chrome's download code reads, and blocks_download says whether Chrome refuses the response because the values differ or the headers hold a NUL. fallback_charset and headers_encoding are as above.

ContentDisposition

@dataclass(frozen=True, slots=True)
class ContentDisposition:
    type: Literal["inline", "attachment"]
    filename: str | None
    blocks_download: bool = False

    @property
    def is_attachment(self) -> bool: ...

A parsed header: an immutable value that compares and hashes by its fields.

__version__

The installed version of the package, as a str.

Exceptions

Malformed headers and URLs never raise; only invalid arguments do.

All of these are checked, for every header in headers, before any header is parsed.

Inputs as str

Chromium reads headers as bytes, so a str is mapped back to bytes first. With headers_encoding, that is exact: the str is encoded with that codec, with surrogate escapes turned back into the bytes they stand for (value.encode(headers_encoding, "surrogateescape")).

Without it, the bytes are guessed. If every character is in U+0000–U+00FF and their Latin-1 bytes are valid UTF-8, those bytes are used; that is what requests, urllib3 and http.client, which urllib.request uses, give for a header that carried UTF-8. Any other str is encoded as UTF-8, with the surrogate escapes that aiohttp uses for undecodable bytes turned back into those bytes. The guess can be wrong, for example for bytes in a legacy charset that an HTTP library decoded as Latin-1, such as caf\xe9.txt in windows-1252. It changes nothing in Content-Type and X-Content-Type-Options, though: only ASCII characters can match a MIME type or nosniff, and the guess always gives them back as the bytes they were.

URLs and the other str arguments are taken as text; lone surrogates in them become U+FFFD.