Rewrite README as a lean, capability-organized quickstart - #197
Merged
Conversation
Replace the ~1150-line comprehensive README with a ~240-line quickstart organized by capability, deferring exhaustive depth to Microsoft Learn and examples/. - Usage organized by capability (CRUD, Query, Schema, Bulk, Async, Errors), ordered by production operation usage (queries and metadata reads dominate). - Each section teaches its concept inline and deep-links the matching Learn article plus runnable sample; removed the flat Learn mirror that duplicated those inline links. - Example code verified against source (single create -> str, retrieve -> None on 404, tables.create typed-column dict, create_lookup_field, 5-class error hierarchy incl. SQLParseError). - Absolute https links throughout for PyPI safety; ASCII-only. - Client constructed once, as a context manager. - Contributing / CLA / Trademarks preserved verbatim.
Suyash Kshirsagar (suyask-msft)
requested a review
from a team
as a code owner
September 4, 2026 06:06
Copilot started reviewing on behalf of
Suyash Kshirsagar (suyask-msft)
September 4, 2026 06:06
View session
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
A couple of README examples are misleading/unsafe as written (BulkDelete async job semantics and async credential lifecycle) and should be corrected before merge.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR rewrites README.md into a shorter, capability-organized quickstart intended for PyPI and agent in-context usage, with deeper documentation routed to Microsoft Learn and examples/.
Changes:
- Restructures usage guidance by capability (CRUD, querying, schema, bulk, async, errors) with shorter runnable snippets.
- Replaces the long table-of-contents style README with a leaner quickstart and curated deep links to Learn + samples.
- Updates contributing section link(s) to be PyPI-safe (absolute GitHub URLs).
File summaries
| File | Description |
|---|---|
| README.md | Replaces the comprehensive README with a lean quickstart organized by common SDK capabilities and pointers to Learn/examples. |
Review details
Suppressed comments (1)
README.md:142
client.records.delete("account", ids)returns the BulkDelete async job id by default. The snippet currently discards that value and reads like the records are deleted synchronously, which isn't accurate for BulkDelete.
# Apply the same change to every record, then delete them all
client.records.update("account", ids, {"industrycode": 1})
client.records.delete("account", ids)
- Files reviewed: 1/1 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
added 5 commits
September 4, 2026 15:31
- Remove SQLParseError from the error example; it is exported but never raised (0 raise sites in the shipped package). Unsupported SQL surfaces as ValidationError.
- Add HTTP 502 to the is_transient list; TRANSIENT_STATUS is {429, 502, 503, 504}.
- Add a usage section for files.upload and client.batch, both listed under Key features but previously unexemplified.
- Convert prose -- to em dashes, matching the existing README style. Code blocks left ASCII.
- Drop new_Name from tables.create: the primary name column is created automatically as <prefix>_Name, so listing it submits a duplicate attribute in the same CreateEntities request. No example or test in the repo declares one. - Create new_Task before the lookup that references it, and note that relationship methods take lowercase logical names. - Note that upsert requires an existing alternate key whose index has reached Active, per examples/advanced/alternate_keys_upsert.py.
- Close the async credential. AsyncDataverseClient.aclose() releases only its own session and caches, never the caller's credential, and every async example in the repo closes it explicitly. Use a single 'async with' for both. - Correct BulkDelete docs. delete() takes use_bulk_delete=True by default with no size threshold, so 'for large sets' was wrong; it also returns a job ID and completes in the background. Capture the ID in the snippet, matching the SDK docstring. - Restore a table of contents, nested under Usage so the capability sections read in context. PyPI offers no outline of its own and rewrites in-page anchors so they resolve; all 13 verified against GitHub's markdown renderer.
Cut 27 lines to 15. Drops the changeset code sample and the inline comments; the transactional behaviour is stated in prose and batch.py covers the detail.
abelmilash-msft
approved these changes
Sep 4, 2026
Vikas Rathee (vrathee-msft)
approved these changes
Sep 5, 2026
abelmilash-msft
added a commit
that referenced
this pull request
Sep 8, 2026
Release changelog for v1.0.1. Adds the `[1.0.1]` section covering the single user-facing change since v1.0.0: the preview notice removed in #190. Context on the entry: - v1.0.0 was published as a GA release (`prerelease=false`), but the README shipped inside it still carried an `[!IMPORTANT]` notice saying the library was "currently in **preview**" and "may contain breaking changes". Because README.md is the PyPI long description, that notice is still visible on the package page today. - Nothing about the library's support status changed between 1.0.0 and 1.0.1 — only the incorrect text was removed. It is therefore filed under **Fixed** rather than **Changed**, so the changelog does not imply GA happened in 1.0.1. - The README rewrite (#197) is intentionally excluded per the release guide's "documentation-only updates" rule. Also rebases the `[Unreleased]` compare link from `v1.0.0...HEAD` to `v1.0.1...HEAD` and adds the `[1.0.1]` compare link. No code changes. Co-authored-by: Abel Milash <[email protected]>
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
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.
What
Rewrites the package README as a lean, capability-organized quickstart (~240 lines, down from ~1150). Microsoft Learn and
examples/remain the source of truth for exhaustive depth; the README is the agent- and PyPI-facing quickstart.Why
The README is the PyPI page and the doc surface coding agents keep in-context. The long comprehensive README duplicated Learn (and had drifted from it) and buried the high-value paths. This trims it to a fast, accurate quickstart and routes depth to Learn.
Key changes
[async]install.createreturns a GUIDstr;retrievereturnsNoneon 404;tables.createtakes a typed-column dict;create_lookup_field; the error hierarchy has 5 classes includingSQLParseError(the live error-handling Learn page lists only 3 -- the README follows the code).https://; ASCII-only; no relative links.main(only theoperations/link was made absolute for PyPI).Reviewer action
API Design Guidelinespoints that assume the old comprehensive-README model ("add a README example per public method" and "keep README and SKILL in sync") -- left verbatim; they may want revisiting under the lean-README approach.Verification done
main; the Learn / Microsoft URLs resolve to the correct topic and match the section that links them; PyPI page and badges resolve.src/.../core/errors.py(all 5 classes exported).origin/main.Note: the "preview" banner on the current PyPI page is a stale-snapshot artifact from the 1.0.0 publish; it is already removed on
main, and publishing 1.0.1 clears it. Out of scope here.