Clients

HTTP clients for the CleanCSV API. Implementation module: cleancsv.client.

class cleancsv.client.CleanCSVClient(base_url, *, timeout=120.0, client=None)

Bases: object

Synchronous HTTP client for CleanCSV clean and suggest endpoints.

Pass the deployment origin only (no path): paths such as /api/v1/clean and /api/v1/suggest are appended by each method. Use cleancsv.DEFAULT_BASE_URL for the public app.

Use as a context manager to ensure the underlying connection is closed:

with CleanCSVClient(base_url) as client:
    result = client.clean(path_to_csv)

Raises:

• cleancsv.errors.CleanCSVError – On HTTP error responses from the API.

• cleancsv.errors.RateLimitError – On HTTP 429 when rate limits apply.

close()

Close the underlying HTTP client if this instance owns it.

__enter__()

Enter context: return self.

__exit__(*args)

Exit context: call close().

clean(file, *, config=None, filename='upload.csv', version='v1', query=None)

Upload a CSV via multipart POST to /api/{version}/clean.

Sends the file as form field file and optional config as a JSON string when config is set. URL query parameters such as format, dedup_by, or strategy can be supplied via query (merged with any existing query).

Parameters:

• file (Path | bytes | bytearray | BinaryIO) – CSV payload: path, bytes, or binary stream.

• config (CleanConfig | str | None) – Cleaning options as CleanConfig, a JSON string, or None to omit the config field.

• filename (str) – Filename sent in the multipart part (default upload.csv).

• version (Literal['v1', 'demo']) – API segment: "v1" or "demo".

• query (dict[str, str] | None) – Optional query parameters merged into the request URL.

Returns:

CleanResult with status, headers, raw body bytes, and Content-Type.

Raises:

• cleancsv.errors.CleanCSVError – On non-success HTTP status (except 429).

• cleancsv.errors.RateLimitError – On HTTP 429.

• TypeError – If file cannot be read as bytes.

Return type:

CleanResult

clean_raw_body(body, *, content_type='text/csv', version='v1', query=None)

POST raw CSV bytes to /api/{version}/clean without multipart encoding.

Use when the server accepts a raw request body. Query parameters can still be passed via query. This path does not send a multipart config field; configure via URL query if the API supports it.

Parameters:

• body (bytes) – Raw CSV file bytes.

• content_type (str) – Content-Type header value (default text/csv).

• version (Literal['v1', 'demo']) – "v1" or "demo".

• query (dict[str, str] | None) – Optional query parameters merged into the request URL.

Returns:

CleanResult with response metadata and body.

Raises:

• cleancsv.errors.CleanCSVError – On non-success HTTP status (except 429).

• cleancsv.errors.RateLimitError – On HTTP 429.

Return type:

CleanResult

suggest(file, *, filename='upload.csv', version='v1')

Upload a CSV via multipart POST to /api/{version}/suggest.

Returns parsed JSON describing suggested deduplication rules and column stats.

Parameters:

• file (Path | bytes | bytearray | BinaryIO) – CSV payload: path, bytes, or binary stream.

• filename (str) – Filename for the multipart part (default upload.csv).

• version (Literal['v1', 'demo']) – "v1" or "demo".

Returns:

SuggestResponse parsed from the JSON body.

Raises:

• cleancsv.errors.CleanCSVError – On non-success HTTP status, invalid JSON, or a non-object JSON body.

• cleancsv.errors.RateLimitError – On HTTP 429.

• TypeError – If file cannot be read as bytes.

Return type:

SuggestResponse

suggest_raw_body(body, *, content_type='text/csv', version='v1')

POST raw CSV bytes to /api/{version}/suggest without multipart encoding.

Parameters:

• body (bytes) – Raw CSV file bytes.

• content_type (str) – Content-Type header (default text/csv).

• version (Literal['v1', 'demo']) – "v1" or "demo".

Returns:

SuggestResponse parsed from the JSON body.

Raises:

• cleancsv.errors.CleanCSVError – On HTTP errors or malformed JSON response.

• cleancsv.errors.RateLimitError – On HTTP 429.

Return type:

SuggestResponse

class cleancsv.client.AsyncCleanCSVClient(base_url, *, timeout=120.0, client=None)

Bases: object

Asynchronous HTTP client for CleanCSV; mirrors CleanCSVClient with async I/O.

Use async with to close the underlying client when it was created internally:

async with AsyncCleanCSVClient(base_url) as client:
    result = await client.clean(path_to_csv)

Raises:

• cleancsv.errors.CleanCSVError – On HTTP error responses from the API.

• cleancsv.errors.RateLimitError – On HTTP 429 when rate limits apply.

async aclose()

Close the underlying async HTTP client if this instance owns it.

async __aenter__()

Enter async context: return self.

async __aexit__(*args)

Exit async context: await aclose().

async clean(file, *, config=None, filename='upload.csv', version='v1', query=None)

Async version of CleanCSVClient.clean().

Parameters:

• file (Path | bytes | bytearray | BinaryIO) – CSV payload: path, bytes, or binary stream.

• config (CleanConfig | str | None) – CleanConfig, JSON string, or None.

• filename (str) – Multipart filename (default upload.csv).

• version (Literal['v1', 'demo']) – "v1" or "demo".

• query (dict[str, str] | None) – URL query parameters to merge.

Returns:

CleanResult with raw response body and metadata.

Raises:

• cleancsv.errors.CleanCSVError – On HTTP errors (except 429).

• cleancsv.errors.RateLimitError – On HTTP 429.

• TypeError – If file cannot be read as bytes.

Return type:

CleanResult

async clean_raw_body(body, *, content_type='text/csv', version='v1', query=None)

Async version of CleanCSVClient.clean_raw_body().

Parameters:

• body (bytes) – Raw CSV bytes.

• content_type (str) – Request Content-Type.

• version (Literal['v1', 'demo']) – "v1" or "demo".

• query (dict[str, str] | None) – URL query parameters to merge.

Returns:

CleanResult.

Raises:

• cleancsv.errors.CleanCSVError – On HTTP errors (except 429).

• cleancsv.errors.RateLimitError – On HTTP 429.

Return type:

CleanResult

async suggest(file, *, filename='upload.csv', version='v1')

Async version of CleanCSVClient.suggest().

Parameters:

• file (Path | bytes | bytearray | BinaryIO) – CSV payload: path, bytes, or binary stream.

• filename (str) – Multipart filename (default upload.csv).

• version (Literal['v1', 'demo']) – "v1" or "demo".

Returns:

SuggestResponse.

Raises:

• cleancsv.errors.CleanCSVError – On HTTP errors or invalid JSON.

• cleancsv.errors.RateLimitError – On HTTP 429.

• TypeError – If file cannot be read as bytes.

Return type:

SuggestResponse

async suggest_raw_body(body, *, content_type='text/csv', version='v1')

Async version of CleanCSVClient.suggest_raw_body().

Parameters:

• body (bytes) – Raw CSV bytes.

• content_type (str) – Request Content-Type.

• version (Literal['v1', 'demo']) – "v1" or "demo".

Returns:

SuggestResponse.

Raises:

• cleancsv.errors.CleanCSVError – On HTTP errors or malformed JSON.

• cleancsv.errors.RateLimitError – On HTTP 429.

Return type:

SuggestResponse