Skip to content
Packet Loom markminiproto

miniproto.media.download.download_file

miniproto.media.download.download_file

Section titled “miniproto.media.download.download_file”
download_file(invoke: RawInvoker, location: object, destination: Destination = None, *, offset: int = 0, limit: int | None = None, part_size: int = DEFAULT_DOWNLOAD_PART_SIZE, resume: bool = False, progress: ProgressCallback | None = None, precise: bool = False, cdn_supported: bool = True, total_size: int | None = None, request_timeout: float | None = None, max_retries: int = 2, flood_sleep_threshold: int | None = 30, max_buffer_size: int | None = None, concurrency: int = DEFAULT_DOWNLOAD_CONCURRENCY, adaptive_concurrency: bool = True, launch_stagger: bool = True, max_in_flight_bytes: int | None = None, adaptive_part_size: bool = True, max_part_size: int = MAX_DOWNLOAD_CHUNK_SIZE, range_cache: DownloadRangeCache | bool | None = None, range_cache_key: str | None = None, range_cache_max_bytes: int = DEFAULT_RANGE_CACHE_BYTES, read_ahead_bytes: int = 0, verify_plain_hashes: bool = False, file_reference_refresher: FileReferenceRefresher | None = None) -> MediaDownloadResult

Download media into memory, a path, or a caller-owned binary stream.

Parameters:

  • invoke (RawInvoker) – Async raw-RPC invoker used for Telegram file requests.
  • location (object) – Telegram input file location to retrieve.
  • destination (Destination) – None for in-memory bytes, a path to create/overwrite, or an open binary stream.
  • offset (int) – Starting byte offset; defaults to 0.
  • limit (int | None) – Exact requested byte count, or None to continue until EOF.
  • part_size (int) – Initial power-of-two request size; defaults to 512 KiB.
  • resume (bool) – Append to an existing path from its 1 KiB-aligned size; defaults to False.
  • progress (ProgressCallback | None) – Optional synchronous or async (current, total) callback; current is committed operation bytes and begins at any retained resume prefix, while total is limit or otherwise total_size.
  • precise (bool) – Request Telegram’s 1 KiB precise mode; enabled automatically when required.
  • cdn_supported (bool) – Permit CDN redirects and their mandatory block verification.
  • total_size (int | None) – Known full file size used to preserve finite concurrent coverage.
  • request_timeout (float | None) – Optional timeout passed to each raw request.
  • max_retries (int) – Non-flood transient retry budget per part; defaults to 2.
  • flood_sleep_threshold (int | None) – Retry eligible flood waits at or below this number of seconds; None disables them. Eligible waits retain their slot and are separately capped at 16 per part.
  • max_buffer_size (int | None) – Legacy maximum in-flight byte window alias.
  • concurrency (int) – Maximum concurrent requests and queued writes.
  • adaptive_concurrency (bool) – Adapt the active request window to connection failures.
  • launch_stagger (bool) – Pace start and flood-recovery request launches.
  • max_in_flight_bytes (int | None) – Maximum requested bytes not yet released by the stream.
  • adaptive_part_size (bool) – Probe larger legal part sizes for large transfers.
  • max_part_size (int) – Upper bound for adaptive parts, no greater than one MiB.
  • range_cache (DownloadRangeCache | bool | None) – Exact-range cache instance, True for shared cache, or disabled value.
  • range_cache_key (str | None) – Stable media identity for range-cache sharing.
  • range_cache_max_bytes (int) – Capacity used by an implicit shared cache.
  • read_ahead_bytes (int) – Best-effort range prefetch budget; disabled for a full-file transfer.
  • verify_plain_hashes (bool) – Verify non-CDN data with Telegram plain-file SHA-256 metadata.
  • file_reference_refresher (FileReferenceRefresher | None) – Optional sync/async callback for one stale-reference refresh per part.

Returns:

Destination Ownership and Rollback

None creates an internal BytesIO returned as data and clears it on failure. A path creates parent directories; a new path is removed on cancellation/failure, while an existing non-resume path is overwritten rather than restored. A resumed path preserves its existing prefix after truncating any non-1-KiB tail, and failure truncates it back to that aligned prefix. A caller BytesIO is restored to its original contents and position; arbitrary caller streams remain open and are not generally restorable. Payload/key buffers are not explicitly zeroized.

Raises:

  • ValueError – An offset, limit, part/cache/window option is invalid.
  • TypeError – A boolean option has the wrong type.
  • MediaDownloadError – A response, finite range, or destination write is invalid.
  • MediaIntegrityError – CDN or requested plain-file integrity verification fails.
  • OSError – A path destination cannot be created, written, or restored.
  • CancelledError – The transfer is cancelled; created paths are removed and owned buffers restored.
miniproto

Fast paths where they count. Explicit boundaries everywhere else.