Remote Files and Folders

Use files_sdk.open(path, mode) to read or write a remote file with Python's familiar file methods. Use a with block to close it; closing a writer completes its upload.

Mode	Content
`"r"` / `"w"`	Read / write UTF-8 text, preserving line endings.
`"rb"` / `"wb"`	Read / write bytes.

Readers support read(size), readline(), readlines(), line iteration and binary readinto(). At the end they return an empty value. When Files.com binds the file to one version, the reader fetches ranges as needed and holds at most a few MiB. Otherwise its first read caches the whole response in a temporary file, using memory while it is small; closing the reader removes that cache. A changed remote version raises InvalidRequestError instead of mixing content. See Download Identity.

file.size is None until a read fetches the remote file. It then reports the verified total size: the bound version's size for ranges, or an unencoded whole response's Content-Length. An empty file has size 0. A missing or encoded response length leaves the size None, even when the API record reports a size.

Example Request

import files_sdk

try:
  with files_sdk.open("logs/app.log") as log:
    for line in log:
      if "ERROR" in line:
        print(line, end="")
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)

Writing

A writer sends full parts as they fill and the remaining bytes on close. After successful close, the file object has the uploaded File's attributes.

Method	Behavior
`write()`	Returns the number of bytes or characters accepted.
`writelines()`	Writes each supplied item.
`flush()`	Does not send a short part early; a short middle part would invalidate the upload.
`close()`	Completes once, then releases the writer's resources, including when close fails.

A failed upload sends nothing further. Later writes and close raise InvalidRequestError; an exception leaving a with block remains the primary exception, and the file closes. A type error before sending, such as writing bytes to a text writer, does not end the upload. If an error has remote_outcome_unknown=True, check the destination before uploading again.

A with block closes the writer even when your own code raises an exception, completing the bytes already written. To publish only complete content, prepare a local file or stream first and use upload_file() or upload_stream(). Local-file uploads can send parts in parallel when the destination permits it.

Example Request

import files_sdk

try:
  with files_sdk.open("reports/summary.txt", "w") as report:
    report.write("All jobs finished\n")
  print(report.size)
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 a Remote File Cannot Do

Operation	Result
`seek()`, `tell()`, `truncate()`, `fileno()`	Raise `io.UnsupportedOperation`; `seekable()` is `False`.
Modes `"a"`, `"x"`, or `"+"`	Raise `io.UnsupportedOperation` before sending a request.
An unrecognized mode	Raises `ValueError` before sending a request.
Reading a writer, writing a reader, or using a closed file	Raises `io.UnsupportedOperation`.

io.UnsupportedOperation inherits from both ValueError and OSError, preserving the exception compatibility of Python's files and version 1 of the SDK.

Walking Folders

folder.walk(path) yields each folder's path, child folders and files as File objects, from the top down. It lists folders lazily, one page at a time. Remove entries from the yielded folders list to skip their subtrees. One operation covers the walk, so cancel_token and deadline apply to the entire traversal.

Example Request

import files_sdk

try:
  for folder, folders, files in files_sdk.folder.walk("projects"):
    folders[:] = [f for f in folders if not f.path.endswith("/archive")]
    for file in files:
      print(file.path, file.size)
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)

Waiting for Copies, Moves and Deletions

copy() and move() can return a pending FileAction before the server finishes. Use a waiting method when subsequent work depends on completion.

Method	Completion
`copy_and_wait()`, `move_and_wait()`, or `FileAction.wait()`	Poll the `FileMigration` every second by default (`interval`), call `progress` when supplied, and return the completed migration or `None` for an immediately finished action.
`delete_and_wait()`	Waits until the path no longer exists, allowing a replacement upload.

A failed or cancelled migration raises files_sdk.error.FileMigrationError; its migration attribute holds the result. Bound waiting with the operation's cancel_token, request_timeout or deadline options.

Example Request

import files_sdk

try:
  migration = files_sdk.file.copy_and_wait(
    "projects/2026", {"destination": "archive/2026"},
    {"request_timeout": 600},
  )
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)