What

Makes the Python SDK actually work and brings it in line with the reference sdk-ts. Julius ported the TS SDK but a few things were left incomplete/broken: 4 unit tests failing on main, batch unusable, package not type-marked, CI not running tests, and the publish workflow misconfigured. All fixes below were cross-checked against Decodo/sdk-ts as the ground truth.

Fixes

Correctness (were failing tests / broken features)

• Request-schema validation wired into scrape / scrape_async. Ported from sdk-ts web-scraping-api.ts validate() — the Python port had stored self._schema but never used it. Now accepts a typed *Params model or a plain dict, validates against the target's JSON schema via jsonschema, raises ValidationError before the HTTP call. scrape_batch does not validate (matches TS). Fixes 3 tests.
• target_meta emitted as plain dicts, not a Pydantic model. Codegen was generating a TargetMeta(BaseModel) that collided with the TargetMeta TypedDict in schema/types.py and broke meta["group"] subscripting. TS emits plain objects — codegen now matches. Fixes 1 test.
• Real BatchRequest. Was aliased BatchRequest = ScrapeRequest, so query/url stayed str and batch rejected list input client-side. Codegen now generates per-target *BatchParams (query/url as list[str]) and a proper discriminated BatchRequest, mirroring the TS mapped type. The bundled batch example now runs.
• __init__.__all__: removed phantom TargetTargetParams (ImportError), exported the 52 *BatchParams + BatchRequest.

Packaging / release

• py.typed marker added + shipped via package-data (SDK was untyped to consumers despite full annotations).
• jsonschema>=4.0 promoted to a runtime dependency (validation needs it); types-jsonschema added to dev.
• Publish workflow: added contents: read to worklfow.yml. This is the confirmed root cause of the failed PyPI publish — on a private repo, declaring only id-token: write zeroes contents, so actions/checkout fails with "Repository not found". (Filename typo left as-is to avoid breaking the future Trusted Publisher binding.)
• Removed the decodo-codegen console script — it had no argparse and would silently run a full codegen (network + overwrite generated files, into site-packages when installed) on any invocation incl. --help. Codegen stays runnable via python -m decodo.codegen.codegen for maintainers.

Tooling / docs

• CI now runs pytest (test.yml) on push + PR — the gap that let the failing tests ship unnoticed.
• README fixed: constructor snippets used a signature that doesn't exist (DecodoClient(web_scraping_api={...}) → DecodoConfig(...)), scrape snippets now use typed params, removed a stray git merge-conflict marker, documented that token is the base64 user:pass basic-auth token, added a git-install fallback while the package isn't on PyPI.

Verification

• pytest: 21 passed (was 4 failed / 17 passed)
• ruff check: clean · mypy (strict, repo config): clean
• Wheel build: py.typed present in artifact
• Batch: GoogleSearchBatchParams(query=[...]) accepted; GoogleSearchParams(query=[...]) still correctly rejected
• Every __all__ entry importable

Deliberately NOT changed (flagging for a call, not silently altering)

• TimeoutError does not inherit DecodoError, and AuthenticationError/ValidationError hardcode 401/422 even for 403/400 responses. Both are faithful to sdk-ts so I left them, but they're real usability sharp edges in both SDKs — worth deciding cross-SDK (a TimeoutError that escapes except DecodoError will surprise users).
• requires-python >=3.12: no 3.12-only syntax in the code; deps allow older. Could relax to >=3.10 to widen adoption — left as-is pending a support-policy decision.

Still needed outside this PR

• PyPI Trusted Publisher must be configured on pypi.org for this repo/workflow before publish succeeds — the contents: read fix unblocks checkout, but the project also doesn't exist on PyPI yet. This is a PyPI-side action, not a code change.

🤖 Generated with Claude Code