Clients

A files_sdk.Client has its own credentials, settings and connections. Each of its resources, such as client.user or client.file, has the operations of the module of the same name, and every object and list they return keeps using that client. A client never reads the module-level settings, such as files_sdk.set_api_key(), so several clients, for different sites or users, can work side by side.

Use a client as a context manager, or call close() when you are done with it. Closing stops its operations in progress and closes its connections. The objects it returned keep their data, but can no longer send requests. Closing a client never logs out a session.

client.user.new(attributes) makes an unsaved object whose save() uses the client.

A record's update() and save() change that object in place and return None. Read the updated attributes from the same object. The client's resource methods, such as client.user.update(id, params), return the updated record.

Example Request

import files_sdk

try:
  with files_sdk.Client(api_key="YOUR_API_KEY") as client:
    user = client.user.find(1234)
    user.update({"name": "Pat"})  # Also through this client.
    for item in client.folder.list_for("reports").auto_paging_iter():
      print(item.path)
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)

Options for One Call

Every operation takes an options dictionary after its parameters, described by files_sdk.RequestOptions. Options apply to that call and to the objects it returns. An option that is left out, or set to None, is inherited from the client. Set it to files_sdk.CLEAR to remove the inherited value instead, such as a client's workspace. 0 and False are real values. An unknown option raises InvalidParameterError before anything is sent.

Option	Meaning
`api_key`, `session_id`, `session`	The credential to use. `session` is a logged-in `files_sdk.Session`.
`workspace_id`, `language`	Sent with each API request.
`headers`	Extra headers for API requests, merged with the client's.
`source_ip`	The local address to send from.
`open_timeout`, `read_timeout`, `max_network_retries`	See Retries and Timeouts.
`request_timeout`, `deadline`, `cancel_token`	See Cancellation and Deadlines.
`region_policy`	`"automatic"` or `"disabled"`. See Regional Relocation.
`client`	For a module-level function, the client to run it with.

An API key given for a call is used instead of an inherited session, and a session instead of an inherited API key. When a client or the module settings have both, the API key is used, unless the call clears it with CLEAR. An empty string for api_key or session_id is treated as left out.

Example Request

import files_sdk

try:
  client = files_sdk.Client(api_key="YOUR_API_KEY", workspace_id=5)
  session = client.session.create({"username": "USERNAME", "password": "PASSWORD"})
  
  # As that session, in no workspace.
  client.folder.list_for("", {}, {
    "session": session,
    "workspace_id": files_sdk.CLEAR,
  })
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)

Module-Level Functions

The module-level functions, such as files_sdk.user.find(), use the module settings as they are when each call starts, and the objects they return keep those settings. Changing a setting later affects only later calls. files_sdk.close() closes the connections the module-level functions share. Their objects can no longer send requests, and the next call opens new connections.

Your Own Requests Session

Pass a requests.Session as http_session to send every request through it, API and file transfers alike, with its adapters, proxies, certificates and hooks. The client never closes it or changes its adapters. Configure proxies, TLS and source addresses on the session itself; the client refuses its own verify, cert, proxies, trust_env and source_ip settings with one.

Requests keeps the session's cookie jar up to date as it would for any request. A session the client creates for itself keeps no cookies that servers set, so nothing from one request's credentials carries over to the next. Requests does not promise that a session is safe to share between threads.

Only the connections a client creates itself can be interrupted, so with your own session a cancelled or timed-out operation stops when its request returns or times out.

The SDK never sends a request that may have changed something again once it may have reached Files.com, but an adapter that retries by itself (a max_retries other than 0) can, without the SDK knowing. Uploads refuse to start through such an adapter, since it could complete an upload twice; for other requests, mount one only if its retries suit them.

Example Request

import requests
import files_sdk

try:
  session = requests.Session()
  session.proxies = {"https": "http://proxy.example.com:3128"}
  client = files_sdk.Client(api_key="YOUR_API_KEY", http_session=session)
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)

Threads

A client can be used from several threads at once. Each request uses its own connection from the client's pool, and connections are reused across calls.

Calling close() from inside one of the client's own requests, such as from the stream a download writes to, raises RuntimeError instead of waiting for itself.