fastsaver 0.1.0__py3-none-any.whl

fastsaver/__init__.py

@@ -0,0 +1,115 @@
+"""fastsaver — Python SDK for FastSaverAPI (https://api.fastsaver.io).
+
+Download media from Instagram, TikTok, YouTube (up to 4K + MP3), Pinterest,
+Facebook, X/Twitter, RuTube and Likee (8 platforms, one JSON shape), get Telegram
+``file_id`` audio for bots and identify songs with Shazam. Sync
+(:class:`FastSaver`) and async (:class:`AsyncFastSaver`) clients with identical
+method names.
+
+Quick start::
+
+    from fastsaver import FastSaver
+
+    client = FastSaver(api_key="fs_sk_...")  # or set FASTSAVER_API_KEY
+    media = client.fetch("https://www.instagram.com/reel/DRsmm9UjKfH/")
+    print(media.type, media.download_url)
+"""
+
+from __future__ import annotations
+
+from ._base import FileInput, TimeoutArg
+from ._constants import (
+    CREDIT_COSTS,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    PLATFORM_HOSTS,
+    YOUTUBE_FORMATS,
+    YouTubeFormat,
+)
+from ._version import __version__
+from .async_client import AsyncFastSaver, AsyncShazam, AsyncYouTube
+from .client import FastSaver, Shazam, YouTube
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    DownloadError,
+    FastSaverError,
+    FetchError,
+    InsufficientCreditsError,
+    InvalidArgumentError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+from .models import (
+    Balance,
+    MediaItem,
+    MediaResult,
+    Music,
+    ShazamMatch,
+    ShazamTop,
+    TelegramAudio,
+    Thumbnails,
+    Track,
+    YouTubeDownload,
+    YouTubeFormatInfo,
+    YouTubeInfo,
+    YouTubeSearch,
+    parse_duration_seconds,
+)
+from .utils import detect_platform, extract_youtube_id, normalize_bot_username
+
+__all__ = [
+    "CREDIT_COSTS",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "PLATFORM_HOSTS",
+    "YOUTUBE_FORMATS",
+    "APIError",
+    "AsyncFastSaver",
+    "AsyncShazam",
+    "AsyncYouTube",
+    "AuthenticationError",
+    "Balance",
+    "ConfigurationError",
+    "DownloadError",
+    "FastSaver",
+    "FastSaverError",
+    "FetchError",
+    "FileInput",
+    "InsufficientCreditsError",
+    "InvalidArgumentError",
+    "InvalidRequestError",
+    "MediaItem",
+    "MediaResult",
+    "Music",
+    "NotFoundError",
+    "RateLimitError",
+    "RequestTimeoutError",
+    "ServerError",
+    "Shazam",
+    "ShazamMatch",
+    "ShazamTop",
+    "TelegramAudio",
+    "Thumbnails",
+    "TimeoutArg",
+    "Track",
+    "TransportError",
+    "ValidationError",
+    "YouTube",
+    "YouTubeDownload",
+    "YouTubeFormat",
+    "YouTubeFormatInfo",
+    "YouTubeInfo",
+    "YouTubeSearch",
+    "__version__",
+    "detect_platform",
+    "extract_youtube_id",
+    "normalize_bot_username",
+    "parse_duration_seconds",
+]

fastsaver/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m fastsaver`` entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

fastsaver/_base.py

@@ -0,0 +1,578 @@
+"""Plumbing shared by :class:`~fastsaver.FastSaver` and :class:`~fastsaver.AsyncFastSaver`.
+
+Handles API-key/base-URL resolution, header construction, timeout
+normalisation, upload-file coercion and download filename derivation. Nothing
+here performs network I/O.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import mimetypes
+import os
+import re
+import tempfile
+import time
+from pathlib import Path, PureWindowsPath
+from typing import IO, Any, Optional, Union
+from urllib.parse import unquote, urlparse
+
+import httpx
+
+from ._constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_CONNECT_TIMEOUT,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    ENV_API_KEY,
+    ENV_BASE_URL,
+    MAX_IDENTIFY_FILE_SIZE,
+    SIGNUP_URL,
+    build_user_agent,
+)
+from ._endpoints import RequestSpec, UploadTuple
+from ._transport import backoff_delay, parse_json, parse_retry_after, should_retry
+from .exceptions import ConfigurationError, DownloadError, InvalidArgumentError
+
+logger = logging.getLogger("fastsaver")
+
+#: Accepted ``timeout`` arguments: seconds, an ``httpx.Timeout`` or ``None`` (no timeout).
+TimeoutArg = Union[float, httpx.Timeout, None]
+
+#: Accepted ``file`` arguments for ``shazam.identify``.
+FileInput = Union[
+    str,
+    "os.PathLike[str]",
+    bytes,
+    bytearray,
+    memoryview,
+    IO[bytes],
+    tuple[str, Any],
+    tuple[str, Any, Optional[str]],
+]
+
+_AUDIO_MIME_TYPES: dict[str, str] = {
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/mp4",
+    ".aac": "audio/aac",
+    ".ogg": "audio/ogg",
+    ".oga": "audio/ogg",
+    ".opus": "audio/ogg",
+    ".wav": "audio/wav",
+    ".flac": "audio/flac",
+    ".weba": "audio/webm",
+    ".webm": "video/webm",
+    ".mp4": "video/mp4",
+    ".m4v": "video/mp4",
+}
+_DEFAULT_CONTENT_TYPE = "application/octet-stream"
+_DEFAULT_UPLOAD_NAME = "audio"
+
+_CD_FILENAME_STAR_RE = re.compile(r"filename\*\s*=\s*([^;]+)", re.IGNORECASE)
+_CD_FILENAME_RE = re.compile(r'filename\s*=\s*(?:"([^"]*)"|([^;]+))', re.IGNORECASE)
+#: Control characters plus the characters Windows forbids in file names.
+_UNSAFE_FILENAME_CHARS_RE = re.compile(r'[\x00-\x1f\x7f<>:"|?*]')
+_WINDOWS_RESERVED_NAMES = frozenset(
+    {"con", "prn", "aux", "nul"}
+    | {f"com{i}" for i in range(1, 10)}
+    | {f"lpt{i}" for i in range(1, 10)}
+)
+#: Byte budget for a derived file name (well under every common filesystem limit).
+_MAX_FILENAME_BYTES = 200
+
+
+# --- Configuration resolution ------------------------------------------------
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    """Return the API key from the argument or ``FASTSAVER_API_KEY``; raise when missing."""
+    key = api_key if api_key is not None else os.environ.get(ENV_API_KEY)
+    key = (key or "").strip()
+    if not key:
+        raise ConfigurationError(
+            "No API key provided. Pass api_key='fs_sk_...' to the client or set the "
+            f"{ENV_API_KEY} environment variable. A free key with 1,000 credits "
+            f"(no credit card required) is available at {SIGNUP_URL}"
+        )
+    return key
+
+
+def resolve_base_url(base_url: Optional[str]) -> str:
+    """Return the base URL (argument > ``FASTSAVER_BASE_URL`` > default) without trailing slash."""
+    url = base_url if base_url is not None else os.environ.get(ENV_BASE_URL)
+    url = (url or "").strip() or DEFAULT_BASE_URL
+    return url.rstrip("/")
+
+
+def normalize_timeout(timeout: TimeoutArg) -> httpx.Timeout:
+    """``float`` → ``httpx.Timeout(t, connect=10.0)``; ``None`` → no timeout.
+
+    An ``httpx.Timeout`` instance is passed through unchanged.
+    """
+    if timeout is None:
+        return httpx.Timeout(None)
+    if isinstance(timeout, httpx.Timeout):
+        return timeout
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        raise TypeError("timeout must be a number of seconds, an httpx.Timeout or None")
+    seconds = float(timeout)
+    if seconds <= 0:
+        raise InvalidArgumentError("timeout must be positive (or None to disable)")
+    return httpx.Timeout(seconds, connect=DEFAULT_CONNECT_TIMEOUT)
+
+
+def mask_api_key(key: str) -> str:
+    """``fs_sk_abcdef...yz`` → ``fs_sk_ab…yz`` (never reveals the full key)."""
+    if not key:
+        return ""
+    if key.startswith("fs_sk_") and len(key) > 10:
+        return f"{key[:8]}…{key[-2:]}"
+    if len(key) > 6:
+        return f"{key[:2]}…{key[-2:]}"
+    return "…"
+
+
+# --- Upload coercion ---------------------------------------------------------
+
+
+def guess_content_type(filename: str) -> Optional[str]:
+    ext = os.path.splitext(filename)[1].lower()
+    if ext in _AUDIO_MIME_TYPES:
+        return _AUDIO_MIME_TYPES[ext]
+    guessed, _ = mimetypes.guess_type(filename)
+    return guessed
+
+
+def _too_large(size: int) -> InvalidArgumentError:
+    return InvalidArgumentError(
+        f"File is too large for /shazam/identify: {size} bytes "
+        f"(max {MAX_IDENTIFY_FILE_SIZE} bytes = 50 MiB). Trim the clip — 5-15 s of audio is enough."
+    )
+
+
+def _read_content(obj: Any) -> tuple[bytes, Optional[str]]:
+    """Materialise ``obj`` into bytes and return ``(data, filename_hint)``.
+
+    Reads are capped at the 50 MiB limit plus one byte, so an oversized stream is
+    rejected without being held in memory in full.
+    """
+    if isinstance(obj, (bytes, bytearray, memoryview)):
+        return bytes(obj), None
+    if isinstance(obj, (str, os.PathLike)):
+        raw = os.fspath(obj)
+        if not raw:
+            raise InvalidArgumentError("file path must not be empty")
+        path = Path(raw)
+        if not path.is_file():
+            raise InvalidArgumentError(f"{path} is not a regular file")
+        size = path.stat().st_size
+        if size > MAX_IDENTIFY_FILE_SIZE:
+            raise _too_large(size)
+        with open(path, "rb") as fh:
+            return fh.read(MAX_IDENTIFY_FILE_SIZE + 1), path.name
+    if hasattr(obj, "read"):
+        data = obj.read(MAX_IDENTIFY_FILE_SIZE + 1)
+        if isinstance(data, str):
+            raise TypeError("file objects must be opened in binary mode ('rb')")
+        name = getattr(obj, "name", None)
+        hint = os.path.basename(name) if isinstance(name, str) and name else None
+        return bytes(data), hint
+    raise TypeError(
+        "file must be a path, bytes, a binary file object or a "
+        "(filename, content[, content_type]) tuple; got " + type(obj).__name__
+    )
+
+
+def coerce_upload_file(
+    file: FileInput,
+    filename: Optional[str] = None,
+    content_type: Optional[str] = None,
+) -> UploadTuple:
+    """Turn any supported ``file`` argument into ``(filename, bytes, content_type)``.
+
+    Raises :class:`ValueError` when the content exceeds 50 MiB or is empty and
+    :class:`TypeError` for unsupported inputs.
+    """
+    name = filename
+    ctype = content_type
+    if isinstance(file, tuple):
+        if len(file) not in (2, 3):
+            raise InvalidArgumentError(
+                "file tuple must be (filename, content) or (filename, content, type)"
+            )
+        tuple_name = file[0]
+        if name is None and isinstance(tuple_name, str) and tuple_name:
+            name = tuple_name
+        if len(file) == 3 and ctype is None and isinstance(file[2], str) and file[2]:
+            ctype = file[2]
+        data, hint = _read_content(file[1])
+    else:
+        data, hint = _read_content(file)
+    if name is None:
+        name = hint
+    size = len(data)
+    if size > MAX_IDENTIFY_FILE_SIZE:
+        raise _too_large(size)
+    if size == 0:
+        raise InvalidArgumentError("file is empty — nothing to identify")
+    if not name:
+        ext = mimetypes.guess_extension(ctype) if ctype else None
+        name = _DEFAULT_UPLOAD_NAME + (ext or "")
+    name = os.path.basename(name) or _DEFAULT_UPLOAD_NAME
+    if not ctype:
+        ctype = guess_content_type(name) or _DEFAULT_CONTENT_TYPE
+    return (name, data, ctype)
+
+
+# --- Download filename derivation -------------------------------------------
+
+
+def _sanitize_filename(name: str) -> Optional[str]:
+    """Reduce a server-supplied name to a single safe path component (or ``None``)."""
+    name = name.replace("\\", "/").rsplit("/", 1)[-1]
+    name = _UNSAFE_FILENAME_CHARS_RE.sub("", name).strip().strip(".").strip()
+    if not name or name in (".", ".."):
+        return None
+    if PureWindowsPath(name).anchor or PureWindowsPath(name).name != name:
+        return None
+    if name.split(".", 1)[0].lower() in _WINDOWS_RESERVED_NAMES:
+        return None
+    encoded = name.encode("utf-8", errors="ignore")
+    if len(encoded) > _MAX_FILENAME_BYTES:
+        stem, dot, ext = name.rpartition(".")
+        ext = ("." + ext) if dot and len(ext) <= 16 and stem else ""
+        base = name[: len(name) - len(ext)]
+        budget = _MAX_FILENAME_BYTES - len(ext.encode("utf-8"))
+        name = base.encode("utf-8", errors="ignore")[:budget].decode("utf-8", errors="ignore")
+        name = name.rstrip(" .") + ext
+        if not name.strip(" ."):
+            return None
+    return name
+
+
+def filename_from_content_disposition(value: Optional[str]) -> Optional[str]:
+    """Extract a filename from a ``Content-Disposition`` header (``filename*=`` preferred)."""
+    if not value:
+        return None
+    star = _CD_FILENAME_STAR_RE.search(value)
+    if star:
+        token = star.group(1).strip().strip('"')
+        charset, sep, encoded = token.partition("''")
+        if sep:
+            try:
+                decoded = unquote(encoded, encoding=charset or "utf-8", errors="replace")
+            except LookupError:
+                decoded = unquote(encoded, errors="replace")
+        else:
+            decoded = unquote(token, errors="replace")
+        name = _sanitize_filename(decoded)
+        if name:
+            return name
+    plain = _CD_FILENAME_RE.search(value)
+    if plain:
+        candidate = plain.group(1) if plain.group(1) is not None else plain.group(2)
+        name = _sanitize_filename(candidate.strip())
+        if name:
+            return name
+    return None
+
+
+def filename_from_url(url: Optional[str]) -> Optional[str]:
+    if not url:
+        return None
+    path = urlparse(url).path
+    if not path:
+        return None
+    return _sanitize_filename(unquote(path.rsplit("/", 1)[-1]))
+
+
+def derive_filename(headers: Optional[httpx.Headers], final_url: Optional[str]) -> str:
+    """``Content-Disposition`` → URL path basename → ``"download"``."""
+    cd = headers.get("Content-Disposition") if headers is not None else None
+    return filename_from_content_disposition(cd) or filename_from_url(final_url) or "download"
+
+
+def dest_is_directory(dest: Union[str, os.PathLike[str]]) -> bool:
+    """``True`` when ``dest`` is an existing directory or is written with a trailing separator.
+
+    ``"downloads/"`` therefore means "put the file inside *downloads*" even before that
+    directory exists (it is created on demand), while ``"downloads"`` is a file name.
+    """
+    raw = os.fspath(dest)
+    seps = tuple(sep for sep in (os.sep, os.altsep, "/") if sep)
+    return raw.endswith(seps) or Path(raw).is_dir()
+
+
+def resolve_dest_path(
+    dest: Union[str, os.PathLike[str]],
+    headers: Optional[httpx.Headers],
+    final_url: Optional[str],
+) -> Path:
+    """Return ``dest`` itself, or ``dest/<derived filename>`` when ``dest`` is a directory.
+
+    A directory destination (existing, or given with a trailing ``/``) is created
+    when missing. A resolved target that is itself a directory raises
+    :class:`IsADirectoryError` before anything is written.
+    """
+    path = Path(dest)
+    if dest_is_directory(dest):
+        path.mkdir(parents=True, exist_ok=True)
+        target = path / derive_filename(headers, final_url)
+    else:
+        target = path
+    if target.is_dir():
+        raise IsADirectoryError(f"{target} is a directory; pass a file path or a directory dest")
+    return target
+
+
+def warn_if_not_media(response: httpx.Response) -> None:
+    """Log a warning when a download link answered with an HTML page instead of a file."""
+    content_type = (response.headers.get("Content-Type") or "").lower()
+    if content_type.startswith("text/html"):
+        logger.warning(
+            "download_url answered with an HTML page (%s), not media: %s",
+            content_type.split(";")[0],
+            response.url,
+        )
+
+
+def download_error(response: httpx.Response) -> DownloadError:
+    """Build the :class:`DownloadError` for a non-2xx final download response."""
+    body = parse_json(response)
+    detail = body.get("detail") if isinstance(body, dict) else None
+    message = f"Download failed with HTTP {response.status_code}"
+    if isinstance(detail, str) and detail:
+        message += f" ({detail})"
+        if detail == "tunnel.not_found":
+            message += " — the download link expired (links are valid for 10 minutes)"
+    message += f": {response.url}"
+    return DownloadError(
+        message,
+        status_code=response.status_code,
+        url=str(response.url),
+        body=body if body is not None else response.text[:500],
+    )
+
+
+class PartFile:
+    """A uniquely named ``.part`` temp file next to ``target``, atomically renamed on success.
+
+    ``tempfile.mkstemp`` creates the file exclusively (no pre-existing symlink is
+    followed) and with a random suffix, so concurrent saves to the same
+    destination cannot corrupt each other. Use as a context manager: the temp
+    file is removed unless :meth:`commit` was called.
+    """
+
+    def __init__(self, target: Path) -> None:
+        self.target = target
+        target.parent.mkdir(parents=True, exist_ok=True)
+        fd, name = tempfile.mkstemp(
+            dir=str(target.parent), prefix="." + target.name[:40] + ".", suffix=".part"
+        )
+        self.path = Path(name)
+        self.file = os.fdopen(fd, "wb")
+        self._committed = False
+
+    def write(self, chunk: bytes) -> None:
+        self.file.write(chunk)
+
+    def commit(self) -> None:
+        self.file.close()
+        os.replace(self.path, self.target)
+        self._committed = True
+
+    def __enter__(self) -> PartFile:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        if not self.file.closed:
+            self.file.close()
+        if not self._committed:
+            with contextlib.suppress(OSError):
+                self.path.unlink()
+
+
+def validate_save_args(url: object, chunk_size: object) -> None:
+    """Argument checks shared by the sync and async ``save()``."""
+    if not isinstance(url, str) or not url.strip():
+        raise InvalidArgumentError("url must be a non-empty string")
+    if isinstance(chunk_size, bool) or not isinstance(chunk_size, int) or chunk_size <= 0:
+        raise InvalidArgumentError("chunk_size must be a positive integer")
+
+
+def check_overwrite(dest: Union[str, os.PathLike[str]], overwrite: bool) -> None:
+    """Raise :class:`FileExistsError` early for a file destination that already exists."""
+    if not overwrite and not dest_is_directory(dest) and Path(dest).exists():
+        raise FileExistsError(f"{os.fspath(dest)} already exists (overwrite=False)")
+
+
+# --- Base client --------------------------------------------------------------
+
+
+class BaseClient:
+    """Configuration and request preparation shared by the sync and async clients."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: TimeoutArg = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        self._api_key = resolve_api_key(api_key)
+        self._base_url = resolve_base_url(base_url)
+        self._timeout = normalize_timeout(timeout)
+        if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+            raise InvalidArgumentError("max_retries must be a non-negative integer")
+        self._max_retries = max_retries
+        self._user_agent = build_user_agent(user_agent)
+        self._closed = False
+
+    # -- public read-only configuration --------------------------------------
+
+    @property
+    def api_key(self) -> str:
+        """The API key in use (masked in ``repr``)."""
+        return self._api_key
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def timeout(self) -> httpx.Timeout:
+        return self._timeout
+
+    @property
+    def max_retries(self) -> int:
+        return self._max_retries
+
+    @property
+    def user_agent(self) -> str:
+        return self._user_agent
+
+    @property
+    def is_closed(self) -> bool:
+        """``True`` once :meth:`close`/:meth:`aclose` has been called on this client."""
+        return self._closed
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(api_key={mask_api_key(self._api_key)!r}, "
+            f"base_url={self._base_url!r}, max_retries={self._max_retries})"
+        )
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ConfigurationError(
+                f"{type(self).__name__} is closed — create a new client "
+                "(or use it as a context manager)"
+            )
+
+    # -- request preparation --------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        return self._base_url + path
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "X-Api-Key": self._api_key,
+            "Accept": "application/json",
+            "User-Agent": self._user_agent,
+        }
+
+    def _download_headers(self) -> dict[str, str]:
+        """Headers for ``save()`` — deliberately **without** ``X-Api-Key``."""
+        return {"Accept": "*/*", "User-Agent": self._user_agent}
+
+    def _resolve_timeout(self, timeout: TimeoutArg, default_read: Optional[float]) -> httpx.Timeout:
+        """Per-call ``timeout`` > per-endpoint read default > client default."""
+        if timeout is not None:
+            return normalize_timeout(timeout)
+        if default_read is not None:
+            return httpx.Timeout(
+                connect=self._timeout.connect,
+                read=default_read,
+                write=self._timeout.write,
+                pool=self._timeout.pool,
+            )
+        return self._timeout
+
+    def _request_kwargs(self, spec: RequestSpec[Any], timeout: TimeoutArg) -> dict[str, Any]:
+        headers = self._headers()
+        if spec.headers:
+            headers.update(spec.headers)
+        kwargs: dict[str, Any] = {
+            "method": spec.method,
+            "url": self._url(spec.path),
+            "headers": headers,
+            "timeout": self._resolve_timeout(timeout, spec.timeout_default),
+            # API calls never follow redirects (also when the user's own httpx client
+            # is configured to), so the key is never replayed to another origin.
+            "follow_redirects": False,
+        }
+        if spec.params is not None:
+            kwargs["params"] = spec.params
+        if spec.json is not None:
+            kwargs["json"] = spec.json
+        if spec.files is not None:
+            kwargs["files"] = spec.files
+        return kwargs
+
+    # -- retry decisions ------------------------------------------------------
+
+    def _retry_delay_for_exception(self, exc: BaseException, attempt: int) -> Optional[float]:
+        if not should_retry(exc, attempt, self._max_retries):
+            return None
+        return backoff_delay(attempt)
+
+    def _retry_delay_for_response(self, response: httpx.Response, attempt: int) -> Optional[float]:
+        if not should_retry(response.status_code, attempt, self._max_retries):
+            return None
+        rate_limited = response.status_code == 429
+        retry_after = None
+        if rate_limited:
+            retry_after = parse_retry_after(response.headers.get("Retry-After"))
+        return backoff_delay(attempt, retry_after, rate_limited=rate_limited)
+
+    # -- logging --------------------------------------------------------------
+
+    @staticmethod
+    def _elapsed_ms(started: float) -> int:
+        return int((time.perf_counter() - started) * 1000)
+
+    def _log_response(self, spec: RequestSpec[Any], status_code: int, started: float) -> None:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "%s %s -> %s in %dms",
+                spec.method,
+                spec.path,
+                status_code,
+                self._elapsed_ms(started),
+            )
+
+    def _log_retry(self, spec: RequestSpec[Any], reason: str, attempt: int, delay: float) -> None:
+        logger.debug(
+            "%s %s failed (%s); retry %d/%d in %.2fs",
+            spec.method,
+            spec.path,
+            reason,
+            attempt + 1,
+            self._max_retries,
+            delay,
+        )
+
+    def _log_transport_error(
+        self, spec: RequestSpec[Any], exc: BaseException, started: float
+    ) -> None:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "%s %s -> %s after %dms",
+                spec.method,
+                spec.path,
+                type(exc).__name__,
+                self._elapsed_ms(started),
+            )