Utilities

normalize_filename(filename)

Normalizes a filename into a filesystem-safe form.

Characters commonly rejected by filesystems are replaced with underscores. Control characters are removed, and consecutive underscores are collapsed into a single underscore.

Note

This function performs normalization only. It does not validate the resulting filename against platform-specific constraints.

detect_filename_from_response(response)

Determine a normalized filename from an HTTP response.

The filename is resolved using the following precedence rules:

1. Content-Disposition header, if present.
2. The final path segment of the response URL.
3. File extension inferred from the Content-Type header, if available.

The resulting filename is always normalized before being returned.

Parameters:

Name	Type	Description	Default
response	Response	HTTP response object.	required

Returns:

Type	Description
str	A normalized filename suitable for filesystem usage.

detect_filename_from_context_disposition(disposition)

Extracts a filename from a Content-Disposition header value.

Both standard filename parameters and RFC 5987 encoded filename parameters are supported. Charset-aware filenames are decoded according to the declared encoding, with a UTF-8 fallback when the charset is unknown.

Parameters:

Name	Type	Description	Default
disposition	str	Raw Content-Disposition header value.	required

Returns:

Type	Description
str | None	Decoded filename if present. None if no filename parameter is found.

detect_file_extension_from_content_type(content_type)

Determine a file extension from a Content-Type header value.

Parameters following the media type are ignored. The extension is resolved using the standard mimetypes registry.

Parameters:

Name	Type	Description	Default
content_type	str	Raw Content-Type header value.	required

Returns:

Type	Description
str	A file extension including the leading dot. Defaults to .txt if no
str	mapping is found.