Module hdrezka.api.http

HTTP request typing helpers and browser-like session factories.

Global variables

var DEFAULT_BROWSER_HEADERS : dict[str, str]

Conservative Chrome-like headers used when TLS impersonation is off or as a baseline.

var ImpersonateTarget

True enables default Chrome impersonation; False disables it; a string selects a curl_cffi target.

Functions

def build_async_client(*,
proxy: str | None = None,
headers: dict | None = None,
impersonate: bool | str = True) ‑> httpx.AsyncClient

Expand source code

def build_async_client(
        *,
        proxy: str | None = None,
        headers: dict | None = None,
        impersonate: ImpersonateTarget = True,
) -> httpx.AsyncClient:
    """
    Build an ``httpx.AsyncClient`` tuned for HDRezka mirrors.

    When ``impersonate`` is enabled (default), uses ``curl_cffi`` via
    ``httpx-curl-cffi`` so TLS/HTTP2 fingerprints look like a real browser.
    Falls back to plain httpx with browser-like headers if the transport
    cannot be loaded and ``impersonate`` was only the default ``True``.
    """
    target = _resolve_impersonate(impersonate)
    client_headers = dict(DEFAULT_BROWSER_HEADERS)
    if headers:
        client_headers.update(headers)

    if target is not None:
        try:
            from httpx_curl_cffi import AsyncCurlTransport, CurlOpt
        except Exception as exc:
            if impersonate is not True:
                raise ImportError(
                    'Browser impersonation requires a working httpx-curl-cffi / curl_cffi '
                    'install. Fix the native dependency, or pass impersonate=False.'
                ) from exc
            warnings.warn(
                f'HDRezka browser impersonation disabled; falling back to plain httpx '
                f'({type(exc).__name__}: {exc}). Install/fix curl_cffi or pass '
                f'impersonate=False to silence this warning.',
                RuntimeWarning,
                stacklevel=2,
            )
        else:
            transport_kwargs: dict[str, Any] = {
                'impersonate': target,
                'default_headers': True,
                # Required for concurrent async requests (curl_cffi / httpx-curl-cffi).
                'curl_options': {CurlOpt.FRESH_CONNECT: True},
            }
            if proxy is not None:
                transport_kwargs['proxy'] = proxy
            return httpx.AsyncClient(
                transport=AsyncCurlTransport(**transport_kwargs),
                headers=client_headers,
                follow_redirects=True,
            )

    kwargs: dict[str, Any] = {'headers': client_headers, 'follow_redirects': True}
    if proxy is not None:
        kwargs['proxy'] = proxy
    return httpx.AsyncClient(**kwargs)

Build an httpx.AsyncClient tuned for HDRezka mirrors.

When impersonate is enabled (default), uses curl_cffi via httpx-curl-cffi so TLS/HTTP2 fingerprints look like a real browser. Falls back to plain httpx with browser-like headers if the transport cannot be loaded and impersonate was only the default True.

Classes

class RequestKwargs (*args, **kwargs)

Expand source code

class RequestKwargs(TypedDict, total=False):
    """Optional keyword arguments forwarded to ``httpx.AsyncClient.request``."""
    content: Optional[Any]
    data: Optional[Any]
    files: Optional[Any]
    json: Optional[Any]
    params: Optional[Any]
    headers: Optional[Any]
    cookies: Optional[Any]
    auth: Optional[Any]
    follow_redirects: Optional[bool | Any]
    timeout: Optional[Any]
    extensions: Optional[Any]

Optional keyword arguments forwarded to httpx.AsyncClient.request.

Ancestors

• builtins.dict

Class variables

var auth : Any | None

The type of the None singleton.

var content : Any | None

The type of the None singleton.

var cookies : Any | None

The type of the None singleton.

var data : Any | None

The type of the None singleton.

var extensions : Any | None

The type of the None singleton.

var files : Any | None

The type of the None singleton.

var follow_redirects : bool | Any | None

The type of the None singleton.

var headers : Any | None

The type of the None singleton.

var json : Any | None

The type of the None singleton.

var params : Any | None

The type of the None singleton.

var timeout : Any | None

The type of the None singleton.