docs: add a Python SDK quick start by dchaudhari7177 · Pull Request #22 · Jackxiaozhiren/datasentry

dchaudhari7177 · 2026-08-29T07:06:03Z

Closes #15

examples/python-sdk/ — quickstart.py is 16 lines of code, and the output in the README was captured from running it, then re-run from a clean state to confirm it reproduces.

from datasentry import DataSentry

client = DataSentry(project=".")
try:
    scan, _detector_runs, issues = client.scan_file("orders.csv")

    score = client.quality_score(scan.id)
    print(f"quality score: {score.overall} / 100" if score else "no score")
    print(f"{scan.fingerprint.row_count} rows, {len(issues)} issues\n")

    for issue in sorted(issues, key=lambda i: -i.priority_score)[:5]:
        print(f"  [{issue.severity.value:<8}] {issue.title}")
        print(f"             {issue.affected_count} affected · {', '.join(issue.columns)}")
finally:
    client.close()

quality score: 95.5 / 100
10 rows, 10 issues

  [medium  ] Numeric outlier in unit_price     3 affected · unit_price
  [high    ] Datetime anomaly in order_date    1 affected · order_date
  [medium  ] Duplicate values in customer_email 1 affected · customer_email
  ...

Constraints

Public methods only — scan_file, quality_score, close, plus export_report in the optional snippet. Nothing reads _store, _registry or any other private attribute
Synthetic local data. make_csv.py writes ten rows; the last four carry one deliberate flaw each — a malformed email, 2026-02-30, a missing price, an exact duplicate — so each finding traces to a visible cause and the numbers are identical on any machine
No new dependencies, no API keys, no external database, no LLM config
.gitignore keeps orders.csv and .datasentry/ out of the repository

The four notes in the README

These are the things I got wrong or had to look up while writing it, so they seemed worth writing down:

scan_file returns a triple, not a scan. The middle element is per-detector timing and status; the example discards it with _detector_runs
Sort by priority_score, not severity. Priority already folds in confidence, affected ratio and detector agreement. In this very output the high datetime issue sits second, because three detectors agreed about unit_price — sorting by severity would misrepresent what the tool actually concluded
close() belongs in a finally. The client holds an open SQLite metadata handle; leaking it is survivable in a script and is not in a long-running process
project="." decides where .datasentry/ lives, which is what makes a second run comparable to the first

Also

The optional report snippet uses client.export_report(scan.id), which returns the JSON report as a dict. HTML export is pointed at the CLI rather than reached for through the client.

Repairs are left out and pointed at examples/demo/, matching the same boundary as #14.

Linked from examples/README.md in the goal table.

Everything the CLI does is on the DataSentry client, but the first SDK experience was undiscoverable. quickstart.py is sixteen lines: open a workspace, scan a synthetic CSV, print the score, print the top issues by priority, close the client in a finally. Public methods only -- scan_file, quality_score, close -- and no new dependencies. make_csv.py plants one flaw per row rather than corrupting randomly, so the documented output reproduces on any machine. The README states the four things that are not obvious from the signature: scan_file returns a triple, priority_score is the right sort key rather than severity, close() belongs in a finally because the client holds an open SQLite handle, and project= decides where scan history lives. Repairs are left to examples/demo/.