v2 Client¶

The v2 client is the actively maintained interface to the Flow API. If there is any functionality you’d like added, please create an issue on the GitHub repo.

Quick Start¶

Create a client, log in, and upload a sample:

from pathlib import Path
from flowbio.v2 import Client, UsernamePasswordCredentials

client = Client()
client.log_in(UsernamePasswordCredentials(
    username="alice", password="s3cret",
))

# See what sample types are available
for st in client.samples.get_types():
    print(f"{st.identifier}: {st.name}")

# Upload a sample
sample = client.samples.upload_sample(
    name="My RNA-Seq Sample",
    sample_type="RNA-Seq",
    data={"reads1": Path("reads_R1.fastq.gz")},
)
print(f"Created sample {sample.id}")

# Upload a generic data file
data = client.data.upload_data(Path("counts.tsv"))
print(f"Uploaded data {data.id}")

class flowbio.v2.Client(base_url='https://app.flow.bio/api', config=None)¶

Client for the Flow REST API.

Provides authentication and access to the Flow platform.

Usage:

from flowbio.v2 import Client
from flowbio.v2.auth import UsernamePasswordCredentials

client = Client()
client.log_in(UsernamePasswordCredentials(
    username="alice", password="s3cret",
))

If you are connecting to a private instance of Flow, you can pass that in the url parameter of the constructor:

client = Client(base_url="https://mycompany.flow.bio/api")

Parameters:

base_url (str) – The base URL of the Flow API. Defaults to "https://app.flow.bio/api".
config (ClientConfig | None) – Optional client configuration. If not provided, defaults are used.

property samples: SampleResource¶: Access sample-related operations (types, metadata, upload).

property data: DataResource¶: Access generic data-file operations (upload).

log_in(credentials)¶

Authenticate with the Flow API.

Delegates to the provided credentials strategy, which performs the authentication flow and stores the access token for subsequent requests.

Parameters:: credentials (Credentials) – The credentials to authenticate with. See flowbio.v2.auth for details.
Raises:: BadRequestError – If the credentials are invalid.
Return type:: None

class flowbio.v2.ClientConfig(chunk_size=1000000, show_progress=True, connection_retries=3, request_timeout=datetime.timedelta(seconds=60), upload_retries=3)¶

Configuration for the Flow API client.

Parameters:

chunk_size (int) – Size of each upload chunk in bytes. Defaults to 1 MB.
show_progress (bool) – Whether to display progress bars during file uploads. Defaults to True.
connection_retries (int) – Number of times to retry on connection failure (e.g. ConnectError, ConnectTimeout). Only retries when the TCP connection was never established, so it is safe for all HTTP methods including POST. Set to 0 to disable. Defaults to 3.
request_timeout (timedelta) – Per-request timeout for read, write, and pool acquisition. Defaults to timedelta(seconds=60). Connect timeout is independent and fixed at 10 s — a slow API response shouldn’t dictate how long we wait for a TCP connection that isn’t coming. Increase request_timeout if uploads against a slow backend are producing ReadTimeout errors.
upload_retries (int) – Number of times to retry a single chunk POST on transient failures (read/write timeout, 502/503/504 from an upstream proxy). Set to 0 to disable. Defaults to 3. The chunk protocol is idempotent on the byte offset, so retrying the same chunk is safe.

Example usage:

from datetime import timedelta
from flowbio.v2 import Client, ClientConfig

client = Client(config=ClientConfig(
    chunk_size=5_000_000,
    show_progress=False,
    request_timeout=timedelta(minutes=2),
))

v2 Reference: