Cancellation and Deadlines

Use one of these options to stop an operation. Without one, it has no overall time limit.

Option	Limit
`cancel_token`	A `files_sdk.CancellationToken`; call `cancel()` from another thread.
`request_timeout`	Seconds from the operation's start; a client setting applies to each call.
`deadline`	An absolute `time.monotonic()` value.

If both time limits are set, the earlier one applies.

One operation is one call, with its retries, redirects and any regional relocation. A list's later pages belong to the operation that fetched the first page, so its deadline covers them, and time spent between pages counts. An upload or download is one operation from its first request to its last, and so is a file from open(), through close(); the SDK checks the operation before it replaces a download's destination or reads more of an upload's source. Later operations of the objects an operation returned get their own limits.

Example Request

import threading
import files_sdk

try:
  token = files_sdk.CancellationToken()
  threading.Timer(10, token.cancel).start()
  
  files_sdk.upload_file("big.iso", "backups/big.iso", {
    "cancel_token": token,
    "request_timeout": 3600,
  })
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)

What Stops at Once

A request waiting for the network on a connection the client created stops at once: while setting up TLS or a proxy tunnel, sending a request or file part, or waiting for or reading a response, even one that trickles in slowly. Its connection is closed rather than reused. Waits between retries stop at once too.

Some waits cannot be interrupted, and the operation stops when they end:

Looking up a host name.
Opening a TCP connection, which waits up to open_timeout for each address the host name resolves to, so a host with several unreachable addresses can take longer in all.
Your own code, such as a stream an upload reads from or a download writes to.
Requests through a session you passed as http_session, or through a SOCKS proxy, which stop when their own timeouts, shortened to the deadline, return.

Errors

A cancelled operation raises files_sdk.error.OperationCancelledError. Its subclass ClientClosedError means the client was closed, before or during the operation. An operation that runs out of time raises DeadlineExceededError, an APIConnectionError.

Their phase says what the operation was doing, such as "response" while waiting for a response or "retry wait". remote_outcome_unknown is True when the request may already have reached Files.com, so what it asked for may have happened. Cancelling does not undo work Files.com has already done. If a request through your own http_session finishes after the operation was cancelled, the operation still raises, with the unused response in the error's response.

Example Request

import files_sdk
from files_sdk.error import OperationCancelledError

try:
  files_sdk.file.download_file("reports/q3.csv", "q3.csv", {"request_timeout": 60})
except files_sdk.error.DeadlineExceededError as error:
  print("Timed out while", error.phase)
except OperationCancelledError:
  print("Cancelled")