Skip to content
Packet Loom markminiproto

miniproto.media.upload.upload_file

miniproto.media.upload.upload_file

Section titled “miniproto.media.upload.upload_file”
upload_file(invoke: RawInvoker, source: FileSource, *, file_name: str | None = None, part_size: int = DEFAULT_CHUNK_SIZE, concurrency: int = DEFAULT_UPLOAD_CONCURRENCY, progress: ProgressCallback | None = None, file_id: int | None = None, max_retries: int = 2, max_buffer_size: int | None = None, request_timeout: float | None = None, flood_sleep_threshold: int | None = DEFAULT_UPLOAD_FLOOD_SLEEP_THRESHOLD, max_file_parts: int | None = 4000) -> MediaUploadResult

Upload a source as MTProto file parts and return its input-file handle.

Parameters:

  • invoke (RawInvoker) – Raw request callable used to save each part.
  • source (FileSource) – Path, bytes, readable stream, or synchronous/asynchronous byte iterable. Paths are opened by this function; caller-owned readers are not closed.
  • file_name (str | None) – Optional override for the Telegram file name.
  • part_size (int) – KiB-aligned part size in bytes, at most 512 KiB.
  • concurrency (int) – Maximum in-flight save requests and bounded read-ahead queue slots.
  • progress (ProgressCallback | None) – Optional callback receiving (completed_bytes, total_bytes) after accepted parts, serialized in completion order rather than part-index order.
  • file_id (int | None) – Optional ID converted with int and used verbatim, including zero; absent IDs are generated non-zero.
  • max_retries (int) – Transient non-flood retry attempts per part.
  • max_buffer_size (int | None) – Required to cover the configured concurrency window when set.
  • request_timeout (float | None) – Per-part timeout; defaults to the upload-tail-safe timeout.
  • flood_sleep_threshold (int | None) – Largest server flood wait in seconds treated as retryable pacing; each part has a separate cap of 16 accepted flood retries.
  • max_file_parts (int | None) – Maximum accepted part count; size is increased when possible.

Returns:

  • MediaUploadResult – The completed file metadata and a matching InputFile or InputFileBig.

Raises:

  • ValueError – If options are invalid or the normalized source is empty.
  • TypeError – If a streamed source yields a non-byte chunk.
  • MediaUploadError – If part-count constraints cannot be met or Telegram rejects a part.
  • CancelledError – After cancelling producer and in-flight part tasks and cleaning up.

The checksum covers exactly the bytes read for small files. Seekable callers are rewound to their initial offset before uploading and left at their final read position; one-shot streams and iterables are consumed into an owned temporary spool that is closed on success, failure, or cancellation.

miniproto

Fast paths where they count. Explicit boundaries everywhere else.