API Reference

Complete API documentation for the URL Content Type Detector library. This reference includes all functions, classes, and utilities available in the package.

Main Functions & Classes

Core API - Content Type Detection

url_content_type_detector.get_content_type(url, timeout=10, is_secure=True)[source]

Fetch the content type of the resource at the given URL.

Parameters:

url (str) – The URL of the resource.
timeout (int | None) – Request timeout in seconds. Defaults to 10. Use None for no timeout. Recommended range is 1-60 seconds; avoid using None in production.
is_secure (bool) – When True, raises an error for HTTP status codes that indicate failure.

Returns:

The content type reported by the server, or "Not Found" if the Content-Type header is missing.

Raises:

ValueError – If the URL is invalid or the timeout is negative.
URLUtilsError – If the request times out, fails, or returns an HTTP error response when is_secure is True.

Return type:

str

Exception Classes

class url_content_type_detector.URLUtilsError[source]: Base exception for URL content type detection errors.

Utility Functions

The utils module provides convenient helper functions for detecting specific content types:

Convenience helpers for content-type checks.

Each helper calls url_content_type_detector.get_content_type() and performs a simple substring check on the returned Content-Type value.

url_content_type_detector.utils.is_7z(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a 7z archive.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates a 7z archive; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_audio(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates audio.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates audio; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_avif(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates an AVIF image.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates AVIF; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_css(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates CSS.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates CSS; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_csv(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates CSV.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates CSV; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_excel(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates an Excel file.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates Excel; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_gif(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a GIF image.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates GIF; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_graphql(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates GraphQL.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates GraphQL; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_gzip(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates gzip.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates gzip; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_html(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates HTML.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates HTML; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_image(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates an image.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates an image; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_javascript(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates JavaScript.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates JavaScript; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_jpeg(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a JPEG image.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates JPEG; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_json(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates JSON.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates JSON; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_markdown(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates Markdown.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates Markdown; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_mp3(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates an MP3 audio file.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates MP3; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_mp4(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates an MP4 video file.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates MP4; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_octet_stream(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates application/octet-stream.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates octet-stream; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_opendocument(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates an OpenDocument file.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates OpenDocument; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_pdf(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a PDF.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates PDF; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_png(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a PNG image.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates PNG; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_powerpoint(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a PowerPoint file.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates PowerPoint; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_rar(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a RAR archive.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates RAR; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_svg(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates an SVG image.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates SVG; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_text(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates plain text.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates plain text; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_video(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates video.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates video; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_webp(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a WebP image.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates WebP; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_word(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a Word document.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates Word; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_x_bz2(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a bzip2 archive.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates bzip2; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_xml(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates XML.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates XML; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_x_tar(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a tar archive.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates tar; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_xz(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates an xz archive.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates xz; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_zip(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a ZIP archive.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates ZIP; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

url_content_type_detector.utils.is_zstd(url, timeout=10, is_secure=True)[source]

Check whether the URL content type indicates a zstd archive.

Parameters:

url (str) – The URL to inspect.
timeout (int | None) – Request timeout in seconds. Use None for no timeout.
is_secure (bool) – When True, raise for HTTP error responses.

Returns:

True if the content type indicates zstd; otherwise False.

Raises:

ValueError – If the URL is invalid or timeout is negative.
URLUtilsError – If the request fails or times out.

Return type:

bool

Examples

Detect a URL’s content type:

from url_content_type_detector import get_content_type

content_type = get_content_type("https://example.com")

Check for specific content types:

from url_content_type_detector import utils

is_pdf = utils.is_pdf("https://example.com/document.pdf")
is_image = utils.is_image("https://example.com/photo.jpg")
is_video = utils.is_video("https://example.com/video.mp4")