Skip to content
Packet Loom markminiproto

miniproto.media.download.iter_download

miniproto.media.download.iter_download

Section titled “miniproto.media.download.iter_download”
iter_download(invoke: RawInvoker, location: object, *, offset: int = 0, limit: int | None = None, part_size: int = DEFAULT_DOWNLOAD_PART_SIZE, 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) -> AsyncGenerator[bytes]

Stream an exact media range as ordered, bounded byte chunks.

Parameters:

  • invoke (RawInvoker) – Async raw-RPC invoker used for Telegram file requests.
  • location (object) – Telegram input file location to retrieve.
  • offset (int) – Starting byte offset; defaults to 0.
  • limit (int | None) – Exact byte count to yield, or None to stream until EOF.
  • part_size (int) – Initial power-of-two request size; defaults to 512 KiB.
  • progress (ProgressCallback | None) – Optional synchronous or async (current, total) callback; current is bytes yielded from this invocation, while total is limit for a finite range or total_size when streaming to EOF.
  • precise (bool) – Request Telegram’s 1 KiB precise mode; it is enabled automatically when needed.
  • cdn_supported (bool) – Allow Telegram to redirect requests to its CDN; defaults to True.
  • total_size (int | None) – Known full size, used for exact range completion and concurrency.
  • 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 server flood waits at or below this number of seconds; None disables them. Eligible waits do not consume max_retries but are capped at 16 per part.
  • max_buffer_size (int | None) – Legacy byte window alias used when max_in_flight_bytes is absent.
  • concurrency (int) – Maximum concurrent part requests; defaults to :data:DEFAULT_DOWNLOAD_CONCURRENCY.
  • adaptive_concurrency (bool) – Reduce the active window on connection-health failures.
  • launch_stagger (bool) – Pace launch bursts and flood recovery; defaults to True.
  • max_in_flight_bytes (int | None) – Maximum requested but unyielded bytes.
  • adaptive_part_size (bool) – Probe larger legal parts for sufficiently large transfers.
  • max_part_size (int) – Largest legal adaptive part size, at most one MiB.
  • range_cache (DownloadRangeCache | bool | None) – Exact-range cache instance, True for the shared cache, or False/None to disable it.
  • range_cache_key (str | None) – Stable identity used to share cached ranges.
  • range_cache_max_bytes (int) – Capacity for an implicitly created shared cache.
  • read_ahead_bytes (int) – Best-effort cached prefetch budget for ranged reads only.
  • verify_plain_hashes (bool) – Validate non-CDN chunks against Telegram’s file hashes.
  • file_reference_refresher (FileReferenceRefresher | None) – Optional sync/async callback to renew an expired file reference once per part.

Yields:

  • AsyncGenerator[bytes] – Contiguous bytes in increasing offset order. A bounded request window
  • AsyncGenerator[bytes] – limits in-flight resources; closing the generator cancels outstanding parts.
  • AsyncGenerator[bytes] – Progress reports current bytes only after a chunk has been yielded,
  • unlike (AsyncGenerator[bytes]) – func:download_file, which reports after destination-write
  • AsyncGenerator[bytes] – acknowledgement and starts current at any retained resume prefix.

Raises:

  • ValueError – A range, alignment, part size, retry, or cache option is invalid.
  • TypeError – verify_plain_hashes or launch_stagger is not boolean.
  • MediaDownloadError – Telegram ends a finite requested interval before full coverage.
  • MediaIntegrityError – Optional plain-file verification finds missing or mismatched hashes.
  • CancelledError – Iteration or an awaiting caller is cancelled.
miniproto

Fast paths where they count. Explicit boundaries everywhere else.