Client Configuration

flywheel.Client is the entry point for all SDK operations. When you initialize it, you control how the client connects, authenticates, and behaves at runtime.

See Getting Started for installation and basic authentication patterns.

Constructor Parameters

import flywheel

fw = flywheel.Client(
    api_key="your-api-key",
    request_timeout=120,
    connect_timeout=30,
    exhaustive=True,
)

Timeouts

The client applies two independent timeouts to every HTTP request:

• Connect timeout (connect_timeout): How long to wait when opening a TCP connection. Default is 10 seconds.
• Request timeout (request_timeout): How long to wait for the server to send a complete response after connecting. Default is 60 seconds.

Both can also be set with environment variables — useful in environments where you cannot pass arguments directly to the constructor, such as inside a Flywheel gear.

export FLYWHEEL_SDK_CONNECT_TIMEOUT=30
export FLYWHEEL_SDK_REQUEST_TIMEOUT=120

Constructor arguments take precedence over environment variables. When neither is set, the defaults (10 and 60) apply.

Per-request timeout override

You can override the timeout for a single call by passing _request_timeout as a (connect_timeout, request_timeout) tuple in seconds:

sessions = fw.get_all_sessions(_request_timeout=(30, 300))

Retries

The SDK automatically retries requests that fail due to transient errors. By default, up to 7 retries are attempted with exponential backoff.

Retried status codes

Retries apply to idempotent HTTP methods: GET, HEAD, PUT, DELETE, OPTIONS, TRACE, and PATCH. POST requests are not retried automatically.

Default retry schedule

The first retry is immediate. Each subsequent retry waits progressively longer before the next attempt:

Adjusting retry behavior

Retry behavior is controlled by environment variables. Set them before your process starts or before importing the SDK.

export FLYWHEEL_SDK_TOTAL_RETRIES=3
export FLYWHEEL_SDK_BACKOFF_FACTOR=0.5

Exhaustive Mode (Site Admin only)

By default, listing endpoints return only the containers the authenticated user has permission to see. With exhaustive=True, the server returns all matching containers across the instance, regardless of per-user permissions.

fw = flywheel.Client(api_key="your-api-key", exhaustive=True)

# Returns all projects site-wide, 
# regardless of group/project permissions for the API key user
all_projects = fw.projects.find()

This mode is intended for site administrators building scripts that must operate across the full instance — for example, audit scripts, bulk migrations, or reporting tools.

Debug Mode

Debug mode logs the full HTTP wire traffic — request headers, request body, and response — using Python's standard logging infrastructure at DEBUG level. It also activates low-level logging via http.client.

Enabling debug mode

Call fw.enable_debug() on an initialized client:

import logging
logging.basicConfig(level=logging.DEBUG)

fw = flywheel.Client(api_key="your-api-key")
fw.enable_debug()

# Subsequent requests log full HTTP traffic
fw.get_current_user()

Configure logging.basicConfig (or your own log handler) before making requests, otherwise the DEBUG-level output will not appear.

Truncating large messages

Upload bodies and bulk list responses can produce very large log entries. Pass message_cutoff to limit how many characters appear in each log message:

fw.enable_debug(message_cutoff=2048)

When a message exceeds message_cutoff, the log shows the first and last cutoff // 2 characters separated by a ...[N bytes total]... summary.

Disabling debug mode

fw.disable_debug()

Releasing Resources

The client maintains a connection pool and a thread pool internally. Both are released automatically when the Client object is garbage-collected. To release them explicitly — for example, at the end of a long-running script — call:

fw.shutdown()