SK-2707: Improve Python SDK onboarding — docs, samples, and correctness fixes#263
Open
Devesh-Skyflow wants to merge 9 commits into
Open
SK-2707: Improve Python SDK onboarding — docs, samples, and correctness fixes#263Devesh-Skyflow wants to merge 9 commits into
Devesh-Skyflow wants to merge 9 commits into
Conversation
- Add top-level skyflow/py.typed (PEP 561) so type checkers see the SDK's types; include it (and the generated rest marker) via package_data. - Align setuptools floor in requirements.txt with setup.py (>= 75.3.3). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Rename deidentify_file_async.py -> deidentify_file_concurrent.py and clarify it uses thread-based concurrency, not asyncio (SDK is sync-only). - Add samples/README.md (prerequisites, how to run, per-sample index) and samples/.env.example for collecting vault values. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Fix Python requirement (3.8 -> 3.9) to match setup.py and CI. - Remove PATCH from connection methods (not a RequestMethod member). - Add docs/api_reference.md documenting response objects, request params, enums, client-management methods, Detect helpers, and service-account functions (all verified against source); link it from the README. - Add README sections: Before you begin, Using the client in production, and Troubleshooting; add status badges. - Add docs/onboarding-backlog.md consolidating the onboarding and API-coverage audits into a prioritized backlog. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The README listed PATCH as a supported connection method but RequestMethod had no PATCH member, so RequestMethod.PATCH raised AttributeError. The SDK passes request.method.value straight through to the connection (it does not restrict to a fixed set), so PATCH is a real capability that was simply missing from the enum. Add PATCH = "PATCH" and restore it in the README and API reference (reversing the earlier doc-only removal). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove samples/.env.example and the dotenv/.env loading guidance from samples/README.md. The samples are run by replacing the inline <PLACEHOLDER> values directly. Update the OB-11 backlog entry to match. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Each vault, token, connection, and Detect operation now shows an "Example response" block with the printed response object, so the response shape is visible at the point of use instead of only via the API reference link. Shapes verified against the response parsers and existing tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add per-class anchors to the response-objects table in docs/api_reference.md and turn each "Returns a <X>Response" mention in the README into a link to its anchor, so readers can jump straight to the full attribute reference for that response. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ions) Replace the flat "Attributes" column with a per-response subsection that documents each attribute's type and meaning, marks optional attributes with `| None`, and explains the shared `errors` shape once. Response anchors now come from the subsection headings (README deep-links still resolve). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Document all request classes in docs/api_reference.md, adding the previously-missing ones (Detokenize, Tokenize, Delete, Query, ReidentifyText, GetDetectRun, InvokeConnection) with parameter tables. - Make request headings anchor-friendly and link each request-class mention in the README to its parameter reference, so request options are discoverable at the point of use (mirrors the response-object links). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improves the onboarding experience for the Python SDK by fixing doc/code correctness drift, documenting the previously-undocumented public API surface, and lowering the time-to-first-success. Based on a consolidated backlog merging an onboarding/first-run audit with the API-coverage audit (Confluence: SDK1/Python).
Why
PATCHas a connection method that doesn't exist inRequestMethod).vault_id/cluster_id/credentials), no response-shape documentation, no troubleshooting guidance, and no type-checker support (py.typedmissing at the package root).Goal
setup.py+ CI); removed non-existentPATCHconnection method; alignedsetuptoolsfloor betweenrequirements.txtandsetup.py; renamed misleadingdeidentify_file_async.py→deidentify_file_concurrent.py(it uses thread-based concurrency, not asyncio).skyflow/py.typed(PEP 561) and shipped it viapackage_dataso mypy/pyright see the SDK's types.docs/api_reference.md(response objects, request params, enums, client-management methods, service-account functions, Detect helpers — all verified against source) linked from the README; new README sections "Before you begin", "Using the client in production", and "Troubleshooting"; status badges.samples/README.md(prerequisites, how to run, per-sample index) andsamples/.env.example.docs/onboarding-backlog.mdconsolidating both audits into a prioritized backlog.UploadFileRequestempty-stub cleanup is intentionally deferred (potential breaking change, to be gated on a version bump).Testing
skyflow/py.typedandskyflow/generated/rest/py.typed.RequestMethod.PATCHdoes not exist (hasattr(RequestMethod, 'PATCH') == False), backing the README fix.docs/api_reference.mdwas cross-checked against the source constructors/enums; thesamples/README.mdindex was cross-checked against the actual sample files.Tech debt
docs/onboarding-backlog.md.