Pausing and Resuming

Set checkpoint to a private local path when calling upload_file(), upload_stream(), download_file() or download_stream(). Repeat the same transfer with that checkpoint after an interruption. Uploads reuse accepted parts; version-bound downloads reuse recorded ranges where storage still honors Range. Successful completion removes the checkpoint.

Pass a files_sdk.PauseToken as pause_token to pause: the SDK starts no new parts, lets active parts finish, saves progress and raises TransferPausedError, whose checkpoint identifies the state. Cancellation instead stops active requests immediately and also saves supported checkpoint state.

An unbound download keeps no checkpoint. A partial whole response starts from the beginning on the next call. A pause before a whole-response fallback can retain earlier ranged progress, but if storage still ignores Range, that data is discarded and the same version is fetched whole. This is not mid-response continuation.

Pausing and Continuing an Upload

import threading
import files_sdk

try:
  pause = files_sdk.PauseToken()
  timer = threading.Timer(60, pause.pause)
  timer.start()
  try:
    files_sdk.upload_file("backup.tar", "archive/backup.tar",
      checkpoint="backup.tar.checkpoint", pause_token=pause)
  except files_sdk.error.TransferPausedError:
    files_sdk.upload_file("backup.tar", "archive/backup.tar", checkpoint="backup.tar.checkpoint")
  finally:
    timer.cancel()
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

Only the paused case runs the continuation. A successful first upload is not uploaded again.

What a Checkpoint Holds

Transfer	Recorded state
Upload	Files.com upload reference, planned parts, accepted ETags and whether completion was attempted.
API-identity download	Identity token, version size, private stage and written ranges.
Storage-bound download	Strong tag, size, storage-resource digest, private stage and written ranges.

Checkpoints contain no API key, session, headers or signed URL. The SDK obtains addresses again on recovery. The checkpoint belongs to the same site, Workspace, paths, stream/file and parameters. Credentials are not recorded, so keep separate checkpoints for different users. A .lock file prevents simultaneous use.

Using another transfer's checkpoint raises InvalidParameterError; damaged or incompatible state raises InvalidRequestError. Remove the checkpoint to start a fresh transfer only after resolving any uncertain upload completion, as below.

Where to Keep Checkpoints

The checkpoint and lock file must be yours and unmodifiable by other users. Their directory and the folders and links leading to it must be owned by you or the system and protected from other users changing them.

Platform	Additional trust requirements
Linux	No group/other write access, except protected sticky directories such as `/tmp`. Path links must belong to you or the system. Owner-only file permissions limit inherited ACL access.
macOS	The same path rules, plus refusal of ACL entries allowing others to write, delete, change attributes/access or take ownership. Denials, your own entries and inheritance-only entries are allowed.
Windows	Ownership by you, SYSTEM or Administrators; ACLs preventing others changing files or deleting/replacing directory entries. Links and junctions are refused. Private profile folders can qualify.

Untrusted paths raise InvalidRequestError before checkpoint reading or changing transfer files, though a lock file may already exist. Group-writable directories, including those created with umask 002, fail; use a private location or remove group write access from the checkpoint directory. An unreadable ACL is refused.

New checkpoints and locks are private from creation. On macOS they are created in an owner-only .stage folder with inherited ACLs removed, then placed at their final names; abandoned staging folders are never read. A macOS filesystem with ACLs but no hard links cannot create a new lock and fails. On Windows, a directory inheriting other-user access to new files is refused before creation.

If privacy or identity changes during a transfer, the checkpoint is not saved or removed. The SDK raises files_sdk.checkpoint.UntrustedCheckpointError, an OSError, or adds the cleanup problem to the original failure. A download's private stage gets final destination access from the current process or replaced file, never from checkpoint-controlled permissions.

When a Transfer Starts Again

Recovery never combines different source versions. Downloads renew their API identity or confirm the storage-bound version of the same object before reusing bytes. Missing ranges are fetched only if storage honors Range; otherwise the same version is fetched from the beginning.

Situation	Recovery
Local upload changed or upload expired	Starts a new upload from the beginning.
Upload's granted limits no longer allow its plan	Raises before sending more parts.
Download version gone; stage missing, replaced or no longer private	A local-file download starts fresh with the current file. An already-written stream raises `InvalidRequestError`.
Complete bound local stage saved but not published	May reuse it only after successful checkpoint sync/save and checks of the same private regular file, exact size, storage resource and version. Not every publication failure leaves reusable state.
Unbound download or interrupted whole response	Unbound transfers keep no checkpoint; a whole response is fetched again from byte zero.

When restarting a local download, an old stage still proven to belong to the SDK is removed on POSIX systems; Windows leaves it in place. Avoid editing transfer files or their private directories during recovery.

Upload Completion Can Be Unknown

The SDK saves the final-request record before completing an upload. If that request's answer is lost, unusable or an error of any status, the upload may already be complete. A later call raises APIConnectionError with remote_outcome_unknown instead of completing it again. Check the remote file before deleting the checkpoint and starting another upload.

Completion is retried on recovery only when it is known not to have happened: the request was not sent or Files.com reported its site disabled. A flush failure prevents the final request; platform durability limits still apply.

Streams

Stream	Requirement for recovery
Upload	Supply identical bytes from the same start, with the same `size` or `spool_limit`. Accepted parts are read and checked again, not resent. Different bytes raise `InvalidRequestError`.
Unknown-size upload without spooling	Cannot resume.
Download	Position the stream after the previously recorded bytes and support `tell()`. If more bytes were written than recorded, truncate to the size named by the error before continuing.

These rules apply to supported version-bound ranged recovery, not continuation within a partial whole response.

Continuing a Download Stream

import files_sdk

try:
  with open("report.csv", "ab") as output:
    files_sdk.download_stream("reports/report.csv", output, checkpoint="report.checkpoint")
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

Crashes and Power Loss

Checkpoints are saved at most once a second during transfer and when it stops. Each save replaces a complete, flushed file and flushes its directory where supported. Download data is flushed before the checkpoint records it. On storage honoring flushes, recent unrecorded progress may be transferred again rather than falsely marked done. The SDK flushes caller-owned streams, but persisting their data is the caller's responsibility.

An upload cannot send its final request until the checkpoint save and flush succeed. Windows and filesystems unable to flush directories persist the checkpoint file but not its rename; a power loss can undo the latest save, including the completion-attempt record.

A complete stage after a crash is not reusable solely because its length matches: checkpoint commitment, private file identity and source-version confirmation must also pass. Partial whole-response data does not gain a resumable span. A complete, saved, version-bound local stage may recover under the conditions above.

Supported partial ranged transfers retain a private stage beside the destination, named .files_sdk-download inside a .files_sdk- directory with 32 hexadecimal digits. A download stopped before writing anything keeps no checkpoint or stage. If you abandon a transfer by deleting its checkpoint, remove its retained private directory too.