Usage

cleancsv.DEFAULT_BASE_URL = 'https://www.clean-csv.app'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Overview

The client targets the CleanCSV clean and suggest JSON/HTTP API. Paths are composed as {base_url}/api/{version}/clean and .../suggest, with version defaulting to "v1". Use "demo" only when your deployment exposes demo routes.

Base URL

The public service origin is DEFAULT_BASE_URL. Pass only the scheme, host, and optional port; do not append /api/... yourself.

Tip

For a self-hosted or local server, point base_url at that origin (for example http://127.0.0.1:3000). Shell examples in the repository often use CLEAN_CSV_BASE_URL for the same value.

Synchronous client

from pathlib import Path

from cleancsv import CleanCSVClient, CleanConfig, DedupConfig, DEFAULT_BASE_URL

with CleanCSVClient(DEFAULT_BASE_URL) as client:
    cfg = CleanConfig(
        format="json",
        dedup=DedupConfig(columns=["email"], strategy="most_complete"),
    )
    result = client.clean(Path("data.csv"), config=cfg)
    payload = result.parse_json()
    print(payload.meta.get("rows"), len(payload.data))

    suggest = client.suggest(Path("data.csv"))
    print(suggest.suggested_rules)

CSV payload may be a pathlib.Path, bytes / bytearray, or a binary file-like object whose read() returns bytes.

Async client

import asyncio

from cleancsv import AsyncCleanCSVClient, CleanConfig, DEFAULT_BASE_URL

async def main() -> None:
    async with AsyncCleanCSVClient(DEFAULT_BASE_URL) as client:
        result = await client.clean(b"id,name\n1,a\n", config=CleanConfig())
        print(result.parse_json().meta)

asyncio.run(main())

Client methods

Method	Role
clean(...)	Multipart POST with CSV file field; optional JSON config in a second field.
clean_raw_body(...)	POST raw CSV bytes (no multipart). Optional URL query is merged when the server supports it.
suggest(...) / suggest_raw_body(...)	Suggest deduplication rules; returns cleancsv.types.SuggestResponse.

The version argument is "v1" (default) or "demo". For clean / clean_raw_body, query is merged into the request URL.

Custom httpx client

You may pass a shared httpx.Client or httpx.AsyncClient (timeouts, proxies, default headers, authentication):

import httpx
from cleancsv import CleanCSVClient, DEFAULT_BASE_URL

with httpx.Client(timeout=60.0, headers={"Authorization": "Bearer ..."}) as http:
    with CleanCSVClient(DEFAULT_BASE_URL, client=http) as client:
        ...

Caution

Injected clients are not closed by cleancsv.client.CleanCSVClient or cleancsv.client.AsyncCleanCSVClient. Own the httpx client lifecycle (typically with a context manager as above).

Responses and errors

Successful clean calls return cleancsv.types.CleanResult (status_code, content_type, body, headers). For JSON responses, use cleancsv.types.CleanResult.parse_json() to obtain cleancsv.types.CleanResponse.

Suggest returns cleancsv.types.SuggestResponse.

Failures raise cleancsv.errors.CleanCSVError with a message and, when applicable, status_code and body. HTTP 429 uses cleancsv.errors.RateLimitError, which may include remaining, reset_ms, and retry_after_s when the server sends them.

Configuration

Use cleancsv.types.CleanConfig and nested dataclasses (DedupConfig, EncodingConfig, NullHandlingConfig, …) to match the API. To build config from JSON or a plain dict, use cleancsv.types.config_from_mapping(). Field-level reference: Types and configuration.

Concurrency and timeouts

• Threading: httpx.Client is not documented as thread-safe; prefer one client per thread or external synchronization.

• Async: use AsyncCleanCSVClient under asyncio and one async client per logical scope unless you know httpx’s async sharing rules for your workload.

• Timeouts: configure them on the httpx client when you construct or inject it.

Examples

Runnable scripts live under examples/ in the GitHub repository (see the README for commands).