Skip to content

Update API reference to render sync clients - #149

Merged
arandito merged 2 commits into
developfrom
api-ref-sync-clients
Nov 18, 2026
Merged

arandito merged 2 commits into
developfrom
api-ref-sync-clients

Conversation

@arandito

@arandito arandito commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Description

The API reference currently only documents the async clients. This change documents the client modes side by side. They share the same models, so each service still has a single page.

  • Sync/Async tabs. Service pages (client and configuration) and operation pages have linked Sync/Async tabs, and the reader's choice carries across pages. Operations that use event streams are async-only, so they get an "Async only" badge and note instead of tabs.
  • Operation signatures. Each operation shows one signature covering every way to pass input: a model or dictionary positionally, or the fields as keyword arguments. Previously it showed two overload signatures. The Parameters table now documents request, plugins, and **kwargs. The Input section shows the dictionary and model in Dictionary/Model tabs, and says which dictionaries only the async client accepts.
  • Client and config signatures. Clients now show their constructor signature. Configs no longer show a constructor, because they're created with resolve().
  • Bidirectional streaming. Clients with bidirectional streams get an install step for the awscrt extra and the AWSCRTHTTPClient transport.
  • Breadcrumbs. Operation and model pages aren't in the nav, so their breadcrumbs are custom generated. They now use the theme's own breadcrumb markup and look like the native ones.
  • Overview. The Overview page covers both client modes, with a Sync/Async DynamoDB example.

LINK FOR RENDERED PREVIEW: https://arandito.github.io/aws-sdk-python/

Testing

  • Added 9 docs tests (21 total) and extended the existing ones.
  • Built the reference for all clients successfully.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

jonathan343
jonathan343 previously approved these changes Nov 18, 2026

@jonathan343 jonathan343 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These changes look great! I have some minor feedback based on reading through the docs:

  • We should spell out the full CRT name AWS Common Runtime (CRT) and link to its docs/marketing page if one exists. People probably don't know what it is.
  • Now that we document two clients, we should change the sub-heading to Clients from Client
  • I know this PR didn't add it. But I think the announcmenent banner can be improved to:

Developer Preview: This SDK is for evaluation and testing only. APIs might change before general availability, so pin your package versions. For production workloads, use Boto3.

If it's too long, we can cut the "APIs might change before general availability, so pin your package versions." piece for now. Tbh the ; looks weird to me for some reason.

@arandito
arandito marked this pull request as ready for review November 18, 2026 14:11
@arandito
arandito requested a review from a team as a code owner November 18, 2026 14:11
kuhe
kuhe previously approved these changes Nov 18, 2026
@arandito
arandito dismissed stale reviews from kuhe and jonathan343 via 183f4b8 November 18, 2026 17:26
@arandito

Copy link
Copy Markdown
Contributor Author

@jonathan343 Addressed your feedback in latest commit. Had to shorten your recommendation in the banner but I kept it in the overview warning.

@jonathan343 jonathan343 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚀

@arandito
arandito merged commit 3e1ab75 into develop Nov 18, 2026
5 of 6 checks passed
@arandito
arandito deleted the api-ref-sync-clients branch November 18, 2026 21:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants