diff --git a/docs/index.md b/docs/index.md index a53f0706..e891e80c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,28 +1,29 @@ # AWS SDK for Python v4 -The AWS SDK for Python v4 provides asynchronous clients for supported AWS services. -Each service has its own package. +The AWS SDK for Python v4 provides synchronous and asynchronous clients for +supported AWS services. Each service has its own package. !!! warning "Developer Preview" - The AWS SDK for Python v4 is intended for evaluation and testing only. Do - not use it for production workloads; use - [Boto3](https://docs.aws.amazon.com/boto3/latest/) - instead. + This SDK is for evaluation and testing only. APIs might change before + general availability, so we recommend pinning the versions of the packages + you install. For production workloads, use + [Boto3](https://aws.amazon.com/sdk-for-python/). [Browse clients](clients/index.md){ .md-button .md-button--primary } [View source](https://github.com/aws/aws-sdk-python){ .md-button } ## Features -- **Async operations.** Every service operation is an `async` method that works - with `asyncio`. +- **Sync and async clients.** Each package includes a synchronous client and an + asynchronous client that works with `asyncio`. Both clients use the same + models. - **Per-service packages.** Install only the clients your application uses. -- **Type annotations.** Operations, input models, and response models include - type annotations, so editors and type checkers do not need separate stub - packages. -- **Streaming support.** Clients for streaming services support event streams - and bidirectional streaming. +- **Generated types.** Each client and its data types are generated from the + service's Smithy model. Operations take keyword arguments and return typed + objects instead of dictionaries. +- **Streaming support.** The asynchronous clients for streaming services + support event streams and bidirectional streaming. The code generator builds each client from its service's [Smithy](https://smithy.io/) model. @@ -80,25 +81,40 @@ credentials provider are not yet supported. Use the [Amazon DynamoDB client](clients/dynamodb/index.md) to list up to ten tables in `us-east-1`: -```python -import asyncio +=== "Sync" -from aws_sdk_dynamodb import AsyncDynamoDBClient, AsyncDynamoDBConfig + ```python + from aws_sdk_dynamodb import DynamoDBClient, DynamoDBConfig + config = DynamoDBConfig.resolve(region="us-east-1") -async def main(): - config = await AsyncDynamoDBConfig.resolve(region="us-east-1") - - async with AsyncDynamoDBClient(config=config) as client: - response = await client.list_tables(limit=10) + with DynamoDBClient(config=config) as client: + response = client.list_tables(limit=10) for table in response.table_names or []: print(table) + ``` +=== "Async" -asyncio.run(main()) -``` + ```python + import asyncio + + from aws_sdk_dynamodb import AsyncDynamoDBClient, AsyncDynamoDBConfig + + + async def main(): + config = await AsyncDynamoDBConfig.resolve(region="us-east-1") + + async with AsyncDynamoDBClient(config=config) as client: + response = await client.list_tables(limit=10) + for table in response.table_names or []: + print(table) + + + asyncio.run(main()) + ``` -`AsyncDynamoDBConfig.resolve()` loads shared settings such as retry +The config's `resolve()` method loads shared settings such as retry configuration. Here, the `region` argument overrides a region set in the environment or shared config. The client resolves credentials through the default chain when it sends the request. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 0e4611a7..f26627ec 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,11 +1,26 @@ -/* Custom breadcrumb styling */ -.breadcrumb { - font-size: 0.85em; - color: var(--md-default-fg-color--light); -} +/* Symbol page breadcrumbs reuse the theme's path inside the article; undo article styles. */ +.md-typeset .md-path { + padding-top: 0; + margin: 0.25rem 0 0.95rem; +} + +.md-typeset .md-path .md-path__list { + display: flex; + margin: 0; + list-style: none; +} + +.md-typeset .md-path .md-path__item { + margin: 0; +} -p:has(span.breadcrumb) { - margin-top: 0; +.md-typeset .md-path .md-path__link { + color: var(--md-default-fg-color--light); + text-decoration: none; +} + +.md-typeset .md-path .md-path__link:is(:focus, :hover) { + color: var(--md-accent-fg-color); } /* Light mode - use dark logo */ @@ -38,3 +53,17 @@ p:has(span.breadcrumb) { text-decoration: underline; text-underline-offset: 0.1em; } + +/* Marks operations that only the asynchronous client supports. */ +.mode-badge { + display: inline-block; + margin-left: 0.4em; + padding: 0 0.45em; + border: 0.05rem solid var(--md-default-fg-color--lighter); + border-radius: 0.2rem; + color: var(--md-default-fg-color--light); + font-size: 0.7em; + font-weight: 700; + line-height: 1.6; + vertical-align: middle; +} diff --git a/overrides/main.html b/overrides/main.html index a46eacfa..2425f5cc 100644 --- a/overrides/main.html +++ b/overrides/main.html @@ -2,8 +2,7 @@ {% block announce %} Developer Preview: - This SDK is intended for evaluation and testing only. Do not use it for - production workloads; use - Boto3 - instead. + This SDK is for evaluation and testing only. APIs might change before general + availability. For production workloads, use + Boto3. {% endblock %} diff --git a/scripts/docs/generate_doc_stubs.py b/scripts/docs/generate_doc_stubs.py index 5393a38c..202e495e 100644 --- a/scripts/docs/generate_doc_stubs.py +++ b/scripts/docs/generate_doc_stubs.py @@ -10,6 +10,7 @@ import logging import re import sys +import tomllib from collections.abc import Sequence from dataclasses import dataclass from enum import Enum @@ -42,6 +43,23 @@ ERROR_BASE_CLASSES = ("ServiceError", "ModeledError") CLIENT_METHOD_NAMES = ("close",) +# Content tab labels. Zensical links tabs that share a label, so a reader's +# choice of mode carries across every page. +SYNC_LABEL = "Sync" +ASYNC_LABEL = "Async" + +# Badge and admonition title for operations that only the async client has. +ASYNC_ONLY_LABEL = f"{ASYNC_LABEL} only" + +# Content tab labels for an operation's input, linked across pages like the modes. +DICTIONARY_LABEL = "Dictionary" +MODEL_LABEL = "Model" + +# The package extra that installs the AWS Common Runtime (CRT) HTTP client, which +# bidirectional event streams require. +CRT_EXTRA = "awscrt" +CRT_DOCS_URL = "https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html" + class StreamType(Enum): """Type of event stream for operations.""" @@ -83,9 +101,11 @@ class OperationInfo: """Information about a client operation.""" name: str - module_path: str + module_path: str # The asynchronous client's method + sync_module_path: str | None # None when only the async client has it input: TypeInfo - input_dicts: list[TypeInfo] + input_dicts: list[TypeInfo] # Every dictionary the async client accepts + async_only_input_dicts: list[TypeInfo] # Ones the sync client does not accept output: TypeInfo stream_type: StreamType | None event_input_type: str | None # For input/duplex streams @@ -112,19 +132,31 @@ class ModelsInfo: @dataclass -class ClientInfo: - """Complete information about a client package.""" +class ClientModeInfo: + """The client, config, and plugin for one client mode (sync or async).""" - name: str # e.g., "AsyncBedrockRuntimeClient" - # e.g., "aws_sdk_bedrock_runtime.aio.client.AsyncBedrockRuntimeClient" - module_path: str - package_name: str # e.g., "aws_sdk_bedrock_runtime" + label: str # e.g., "Async" + client: TypeInfo # e.g., AsyncBedrockRuntimeClient config: TypeInfo plugin: TypeInfo client_methods: list[ClientMethodInfo] + + +@dataclass +class ClientInfo: + """Complete information about a client package.""" + + package_name: str # e.g., "aws_sdk_bedrock_runtime" + sync: ClientModeInfo + async_: ClientModeInfo operations: list[OperationInfo] models: ModelsInfo + @property + def modes(self) -> list[ClientModeInfo]: + """Both client modes, in content tab order.""" + return [self.sync, self.async_] + class DocStubGenerator: """Generate markdown API Reference stubs for AWS SDK for Python v4 clients.""" @@ -196,59 +228,80 @@ def _analyze_client_package(self, package_name: str) -> ClientInfo: logger.info(f"Analyzing package: {package_name}") package = griffe.load(package_name, search_paths=[self.client_dir.parent]) - required = ("aio.client", "aio.config", "models") + required = ("client", "config", "aio.client", "aio.config", "models") missing = [name for name in required if not self._has_module(package, name)] if missing: raise ValueError( f"Missing required modules in {package_name}: {', '.join(missing)}" ) - client_module = package["aio.client"] - config_module = package["aio.config"] - models_module = package["models"] + sync_mode, sync_class = self._analyze_mode(package, "", SYNC_LABEL) + async_mode, async_class = self._analyze_mode(package, "aio.", ASYNC_LABEL) - client_class = self._find_class_with_suffix(client_module, "Client") - if not client_class: - raise ValueError( - f"No class ending with 'Client' found in {package_name}.aio.client" - ) - - config_class = self._find_class_with_suffix(config_module, "Config") - if not config_class: + # Event streams are only available on the async client, so its + # operations are a superset of the sync client's. + sync_operations = {op.name: op for op in self._operation_methods(sync_class)} + operations = [ + self._analyze_operation(op, sync_operations.pop(op.name, None)) + for op in self._operation_methods(async_class) + ] + if sync_operations: raise ValueError( - f"No class ending with 'Config' found in {package_name}.aio.config" + f"Operations missing from {async_class.name}: " + f"{', '.join(sorted(sync_operations))}" ) - - plugin_alias = config_module.members.get("Plugin") - if not plugin_alias: - raise ValueError(f"Missing Plugin in {package_name}.aio.config") - - config = TypeInfo(name=config_class.name, module_path=config_class.path) - plugin = TypeInfo(name=plugin_alias.name, module_path=plugin_alias.path) - - client_methods = self._extract_client_methods(client_class) - operations = self._extract_operations(client_class) - models = self._extract_models(models_module, operations) + models = self._extract_models(package["models"], operations) logger.info( - f"Analyzed {client_class.name}: {len(client_methods)} client methods, " - f"{len(operations)} operations, " + f"Analyzed {async_class.name}: " + f"{len(async_mode.client_methods)} client methods, " + f"{len(operations)} operations " + f"({sum(op.sync_module_path is None for op in operations)} async only), " f"{len(models.structures)} structures, {len(models.errors)} errors, " f"{len(models.dictionaries)} dictionaries, " f"{len(models.unions)} unions, {len(models.enums)} enums" ) return ClientInfo( - name=client_class.name, - module_path=client_class.path, package_name=package_name, - config=config, - plugin=plugin, - client_methods=client_methods, + sync=sync_mode, + async_=async_mode, operations=operations, models=models, ) + def _analyze_mode( + self, package: Object | Alias, prefix: str, label: str + ) -> tuple[ClientModeInfo, Class]: + """Find the client, config, and plugin under a mode's module prefix.""" + client_module = package[f"{prefix}client"] + config_module = package[f"{prefix}config"] + + client_class = self._find_class_with_suffix(client_module, "Client") + if not client_class: + raise ValueError( + f"No class ending with 'Client' found in {client_module.path}" + ) + + config_class = self._find_class_with_suffix(config_module, "Config") + if not config_class: + raise ValueError( + f"No class ending with 'Config' found in {config_module.path}" + ) + + plugin_alias = config_module.members.get("Plugin") + if not plugin_alias: + raise ValueError(f"Missing Plugin in {config_module.path}") + + mode = ClientModeInfo( + label=label, + client=TypeInfo(name=client_class.name, module_path=client_class.path), + config=TypeInfo(name=config_class.name, module_path=config_class.path), + plugin=TypeInfo(name=plugin_alias.name, module_path=plugin_alias.path), + client_methods=self._extract_client_methods(client_class), + ) + return mode, client_class + def _has_module(self, package: Object | Alias, dotted_name: str) -> bool: try: return isinstance(package[dotted_name], Module) @@ -266,19 +319,18 @@ def _find_class_with_suffix(self, module: Module, suffix: str) -> Class | None: return cls return None - def _extract_operations(self, client_class: Class) -> list[OperationInfo]: - """Extract operation information from client class.""" - operations = [] - for op in client_class.functions.values(): - if ( + def _operation_methods(self, client_class: Class) -> list[Function]: + """Return the client methods that are service operations.""" + return [ + op + for op in client_class.functions.values() + if not ( op.is_private or op.is_init_method or op.is_special or op.name in CLIENT_METHOD_NAMES - ): - continue - operations.append(self._analyze_operation(op)) - return operations + ) + ] def _extract_client_methods(self, client_class: Class) -> list[ClientMethodInfo]: """Extract public client methods that are not service operations.""" @@ -288,47 +340,37 @@ def _extract_client_methods(self, client_class: Class) -> list[ClientMethodInfo] if not method.is_private and method.name in CLIENT_METHOD_NAMES ] - def _analyze_operation(self, operation: Function) -> OperationInfo: - """Analyze an operation method to extract information.""" + def _analyze_operation( + self, operation: Function, sync_operation: Function | None + ) -> OperationInfo: + """Analyze an async operation method and its sync counterpart, if any.""" stream_type = None event_input_type = None event_output_type = None - # Public request types live on the overloads; the implementation accepts - # *args/**kwargs and does not expose the input shape. - request_signature = next( - ( - overload - for overload in operation.overloads or [] - if "request" in overload.parameters - ), - None, - ) - if request_signature: - input_annotation = request_signature.parameters["request"].annotation - else: - input_annotation = operation.parameters["input"].annotation - input_types = self._get_union_elements( - self._get_expr(input_annotation, f"'{operation.name}' input annotation") - ) - model_types = [ - expr for expr in input_types if not expr.canonical_name.endswith("Dict") - ] - dict_types = [ - expr for expr in input_types if expr.canonical_name.endswith("Dict") - ] - if len(model_types) != 1: - raise ValueError(f"'{operation.name}': expected one input model") - input_info = TypeInfo( - name=model_types[0].canonical_name, - module_path=model_types[0].canonical_path, - ) - input_dicts = [ - TypeInfo(name=expr.canonical_name, module_path=expr.canonical_path) - for expr in dict_types - ] - + input_info, input_dicts = self._input_types(operation) returns = self._get_expr(operation.returns, f"'{operation.name}' return type") + async_only_input_dicts = [] + if sync_operation: + # The page documents one input and output for both clients, so the + # sync method may differ only by accepting fewer dictionaries. + sync_input, sync_dicts = self._input_types(sync_operation) + if sync_input != input_info or any( + d not in input_dicts for d in sync_dicts + ): + raise ValueError( + f"'{operation.name}': sync input types are not a subset of " + "the async input types" + ) + sync_returns = self._get_expr( + sync_operation.returns, f"'{operation.name}' return type" + ) + if sync_returns.canonical_path != returns.canonical_path: + raise ValueError( + f"'{operation.name}': sync and async return types differ" + ) + async_only_input_dicts = [d for d in input_dicts if d not in sync_dicts] + output_type = returns.canonical_name stream_type_map = {s.value: s for s in StreamType} @@ -354,14 +396,43 @@ def _analyze_operation(self, operation: Function) -> OperationInfo: return OperationInfo( name=operation.name, module_path=operation.path, + sync_module_path=sync_operation.path if sync_operation else None, input=input_info, input_dicts=input_dicts, + async_only_input_dicts=async_only_input_dicts, output=output_info, stream_type=stream_type, event_input_type=event_input_type, event_output_type=event_output_type, ) + def _input_types(self, operation: Function) -> tuple[TypeInfo, list[TypeInfo]]: + """Return an operation's input model and the dictionaries it accepts.""" + # Public request types live on the overloads; the implementation accepts + # *args/**kwargs and does not expose the input shape. + request_signature = next( + ( + overload + for overload in operation.overloads or [] + if "request" in overload.parameters + ), + None, + ) + if request_signature: + input_annotation = request_signature.parameters["request"].annotation + else: + input_annotation = operation.parameters["input"].annotation + input_types = [ + TypeInfo(name=expr.canonical_name, module_path=expr.canonical_path) + for expr in self._get_union_elements( + self._get_expr(input_annotation, f"'{operation.name}' input annotation") + ) + ] + models = [t for t in input_types if not t.name.endswith("Dict")] + if len(models) != 1: + raise ValueError(f"'{operation.name}': expected one input model") + return models[0], [t for t in input_types if t.name.endswith("Dict")] + def _get_expr(self, annotation: str | Expr | None, context: str) -> Expr: """Extract and validate an Expr from an annotation.""" if not isinstance(annotation, Expr): @@ -550,6 +621,8 @@ def _generate_client_docs(self, client_info: ClientInfo) -> bool: def _generate_index(self, client_info: ClientInfo) -> None: """Generate the main index.md file.""" + sync, async_ = client_info.sync, client_info.async_ + distribution = client_info.package_name.replace("_", "-") lines = [ f"# {self.service_name}", "", @@ -558,31 +631,43 @@ def _generate_index(self, client_info: ClientInfo) -> None: f"To install the {self.service_name} client:", "", "```bash", - f"python -m pip install {client_info.package_name.replace('_', '-')}", + f"python -m pip install {distribution}", "```", "", - "## Client", + *self._bidirectional_streaming_setup(client_info, distribution), + "## Clients", "", - *self._mkdocs_directive( - client_info.module_path, - members=False, - merge_init_into_class=True, - ignore_init_summary=True, - ), + f"The package provides a synchronous client, `{sync.client.name}`, and " + f"an asynchronous client, `{async_.client.name}`. Both clients use " + "the same models.", "", ] - - for method in sorted(client_info.client_methods, key=lambda x: x.name): + if any(op.sync_module_path is None for op in client_info.operations): lines.extend( - [*self._mkdocs_directive(method.module_path, heading_level=4), ""] + [ + "Operations that use event streams are available only on " + f"`{async_.client.name}`. They are marked **{ASYNC_ONLY_LABEL}** " + "under [Operations](#operations).", + "", + ] ) + lines.extend( + self._tabs( + {mode.label: self._client_tab(mode) for mode in client_info.modes} + ) + ) # Operations section if client_info.operations: lines.append("## Operations") lines.append("") for op in sorted(client_info.operations, key=lambda x: x.name): - lines.append(f"- [`{op.name}`](operations/{op.name}.md)") + badge = ( + "" + if op.sync_module_path + else f' {ASYNC_ONLY_LABEL}' + ) + lines.append(f"- [`{op.name}`](operations/{op.name}.md){badge}") lines.append("") # Configuration section @@ -590,13 +675,9 @@ def _generate_index(self, client_info: ClientInfo) -> None: [ "## Configuration", "", - *self._mkdocs_directive( - client_info.config.module_path, - merge_init_into_class=True, - ignore_init_summary=True, + *self._tabs( + {mode.label: self._config_tab(mode) for mode in client_info.modes} ), - "", - *self._mkdocs_directive(client_info.plugin.module_path), ] ) @@ -628,38 +709,57 @@ def _generate_index(self, client_info: ClientInfo) -> None: def _generate_operation_stubs(self, operations: list[OperationInfo]) -> None: """Generate operation documentation files.""" for op in operations: - lines = [ - f"# {op.name}", - "", - "## Operation", - "", - *self._mkdocs_directive(op.module_path), - "", - "## Input", - "", - ] - if op.input_dicts: + lines = [f"# {op.name}", "", "## Operation", ""] + if op.sync_module_path: + lines.extend( + self._tabs( + { + SYNC_LABEL: self._mkdocs_directive( + op.sync_module_path, toc_label=SYNC_LABEL + ), + ASYNC_LABEL: self._mkdocs_directive( + op.module_path, toc_label=ASYNC_LABEL + ), + } + ) + ) + else: lines.extend( [ - "Pass the input fields as keyword arguments, or pass a model or dictionary " - "as the first positional argument. Pass `plugins` separately as a keyword argument.", + f'!!! info "{ASYNC_ONLY_LABEL}"', "", - "### Model", + " This operation uses an event stream, so only the " + "asynchronous client supports it.", "", - *self._mkdocs_directive(op.input.module_path, heading_level=4), + *self._mkdocs_directive(op.module_path, toc_label=ASYNC_LABEL), "", - "### Dictionaries", ] ) + lines.extend(["## Input", ""]) + if op.input_dicts: + lines.extend( + [ + "Pass the input as keyword arguments, a positional dictionary, or a " + "positional model object. Pass `plugins` separately as a keyword argument.", + "", + ] + ) + # The dictionaries and the model have the same fields, so show one + # at a time. Dictionaries come first: keyword arguments, the most + # common way to call an operation, follow their fields. + dictionaries = self._async_only_dicts_note(op) for dictionary in op.input_dicts: - lines.extend( - [ - "", - *self._mkdocs_directive( - dictionary.module_path, heading_level=4 - ), - ] + if dictionaries: + dictionaries.append("") + dictionaries.extend(self._mkdocs_directive(dictionary.module_path)) + lines.extend( + self._tabs( + { + DICTIONARY_LABEL: dictionaries, + MODEL_LABEL: self._mkdocs_directive(op.input.module_path), + } ) + ) else: lines.extend(self._mkdocs_directive(op.input.module_path)) lines.extend(["", "## Output", ""]) @@ -705,9 +805,7 @@ def _generate_operation_stubs(self, operations: list[OperationInfo]) -> None: output_path = self.output_dir / "operations" / f"{op.name}.md" output_path.parent.mkdir(parents=True, exist_ok=True) - output_path.write_text( - self._breadcrumb("Operations", op.name) + "\n".join(lines) - ) + output_path.write_text(self._breadcrumb("Operations") + "\n".join(lines)) logger.info(f"Wrote {len(operations)} operation file(s)") @@ -730,7 +828,7 @@ def _generate_type_stubs( output_path = self.output_dir / category / f"{item.name}.md" output_path.parent.mkdir(parents=True, exist_ok=True) output_path.write_text( - self._breadcrumb(category.title(), item.name) + "\n".join(lines) + self._breadcrumb(category.title()) + "\n".join(lines) ) logger.info(f"Wrote {len(items)} {category} file(s)") @@ -755,12 +853,95 @@ def _generate_union_stubs(self, unions: list[UnionInfo]) -> None: output_path = self.output_dir / "unions" / f"{union.name}.md" output_path.parent.mkdir(parents=True, exist_ok=True) - output_path.write_text( - self._breadcrumb("Unions", union.name) + "\n".join(lines) - ) + output_path.write_text(self._breadcrumb("Unions") + "\n".join(lines)) logger.info(f"Wrote {len(unions)} union file(s)") + def _bidirectional_streaming_setup( + self, client_info: ClientInfo, distribution: str + ) -> list[str]: + """Generate the CRT install step, for clients with bidirectional streams.""" + if not any( + op.stream_type is StreamType.DUPLEX for op in client_info.operations + ): + return [] + pyproject = tomllib.loads( + (self.client_dir.parent.parent / "pyproject.toml").read_text() + ) + if CRT_EXTRA not in pyproject["project"].get("optional-dependencies", {}): + raise ValueError( + f"{distribution} has bidirectional streams but no '{CRT_EXTRA}' extra" + ) + return [ + "### Bidirectional streaming", + "", + "This client supports bidirectional event streams, which require the HTTP " + f"client from the [AWS Common Runtime (CRT)]({CRT_DOCS_URL}). To use this " + f"feature, install the package with the `{CRT_EXTRA}` extra:", + "", + "```bash", + f'python -m pip install "{distribution}[{CRT_EXTRA}]"', + "```", + "", + "Then pass an `AWSCRTHTTPClient` instance as the transport when you resolve the " + "config.", + "", + ] + + def _client_tab(self, mode: ClientModeInfo) -> list[str]: + """Generate a mode's Client tab: the client class and non-operation methods.""" + lines = self._mkdocs_directive( + mode.client.module_path, + members=False, + merge_init_into_class=True, + ignore_init_summary=True, + ) + for method in sorted(mode.client_methods, key=lambda x: x.name): + lines.extend( + ["", *self._mkdocs_directive(method.module_path, heading_level=4)] + ) + return lines + + def _config_tab(self, mode: ClientModeInfo) -> list[str]: + """Generate a mode's Configuration tab: the config and Plugin types.""" + return [ + # No constructor signature: configs are built with resolve(), and + # calling the class directly raises. + *self._mkdocs_directive(mode.config.module_path), + "", + # Both modes define a Plugin, so the table of contents label tells + # them apart. + *self._mkdocs_directive( + mode.plugin.module_path, + toc_label=f"{mode.plugin.name} ({mode.label})", + ), + ] + + def _async_only_dicts_note(self, op: OperationInfo) -> list[str]: + """Generate a note naming input dictionaries only the async client accepts.""" + if not (op.sync_module_path and op.async_only_input_dicts): + return [] + + def names(dicts: list[TypeInfo]) -> str: + return ", ".join(f"`{d.name}`" for d in dicts) + + shared = [d for d in op.input_dicts if d not in op.async_only_input_dicts] + note = ( + f"Only the asynchronous client accepts {names(op.async_only_input_dicts)}." + ) + if shared: + note = f"Both clients accept {names(shared)}. {note}" + return [note] + + def _tabs(self, tabs: dict[str, list[str]]) -> list[str]: + """Wrap each label's lines in a content tab, ending with a blank line.""" + lines = [] + for label, body in tabs.items(): + lines.extend([f'=== "{label}"', ""]) + lines.extend(f" {line}" if line else "" for line in body) + lines.append("") + return lines + def _mkdocs_directive( self, module_path: str, @@ -768,6 +949,7 @@ def _mkdocs_directive( members: bool | None = None, merge_init_into_class: bool = False, ignore_init_summary: bool = False, + toc_label: str | None = None, ) -> list[str]: """Generate mkdocstrings directive lines for a module path. @@ -777,6 +959,8 @@ def _mkdocs_directive( members: Whether to show members (None omits the option). merge_init_into_class: Whether to merge __init__ docstring into class docs. ignore_init_summary: Whether to ignore init summary in docstrings. + toc_label: The object's label in the page's table of contents + (None uses its name). Returns: List of strings representing the mkdocstrings directive. @@ -790,18 +974,32 @@ def _mkdocs_directive( lines.append(f" members: {'true' if members else 'false'}") if merge_init_into_class: lines.append(" merge_init_into_class: true") + if toc_label: + lines.append(f' toc_label: "{toc_label}"') if ignore_init_summary: lines.append(" docstring_options:") lines.append(" ignore_init_summary: true") return lines - def _breadcrumb(self, category: str, name: str) -> str: - """Generate a breadcrumb navigation element.""" - separator = "  >  " - home = f"[{self.service_name}](../index.md)" - section = f"[{category}](../index.md#{category.lower()})" - return f'{home}{separator}{section}{separator}{name}\n' + def _breadcrumb(self, category: str) -> str: + """Generate a breadcrumb trail in the theme's navigation path markup. + + Symbol pages are left out of the navigation to keep the sidebar small, so + the theme renders no path for them. Like its path, this lists ancestors only. + """ + items = "\n".join( + f'
  • [{title}]' + f"({href}){{ .md-path__link }}
  • " + for title, href in [ + (self.service_name, "../index.md"), + (category, f"../index.md#{category.lower()}"), + ] + ) + return ( + '\n\n' + ) def main() -> int: diff --git a/scripts/docs/griffe_extensions.py b/scripts/docs/griffe_extensions.py index bce2915d..94ac583b 100644 --- a/scripts/docs/griffe_extensions.py +++ b/scripts/docs/griffe_extensions.py @@ -1,8 +1,23 @@ -"""Preserve operation descriptions stored on generated overloads.""" +"""Adapt generated clients and their operations for the API reference.""" +import ast from typing import Any -from griffe import Docstring, Extension, Function +from griffe import ( + Class, + Docstring, + ExprBinOp, + ExprSubscript, + Extension, + Function, + Parameter, + ParameterKind, + Parameters, + get_expression, +) + +# Generated clients subclass these and inherit their constructor. +CLIENT_BASES = ("smithy_core.client.Client", "smithy_core.aio.client.AsyncClient") class OverloadDocstrings(Extension): @@ -22,3 +37,135 @@ def on_function(self, *, func: Function, **kwargs: Any) -> None: parser_options=docstring.parser_options, ) break + + +class MergedOperationSignature(Extension): + """Show each operation with one signature covering every way to pass input. + + Generated operations have two overloads: the request (a model or dictionary) + passed positionally, and its fields as keyword arguments. Rendering both looks + like a duplicate and neither covers every form, so this merges them and + documents ``request`` and ``**kwargs`` alongside ``plugins``. + """ + + def on_function(self, *, func: Function, **kwargs: Any) -> None: + overloads = func.overloads or [] + request = [o for o in overloads if "request" in o.parameters] + keyword = [ + o + for o in overloads + if any(p.kind is ParameterKind.var_keyword for p in o.parameters) + ] + if len(overloads) != 2 or len(request) != 1 or len(keyword) != 1: + return + [request_overload], [keyword_overload] = request, keyword + request_annotation = request_overload.parameters["request"].annotation + if request_overload is keyword_overload or request_annotation is None: + return + + parameters = list(keyword_overload.parameters) + parameters.insert( + 1 if parameters and parameters[0].name == "self" else 0, + Parameter( + "request", + annotation=ExprBinOp(request_annotation, "|", "None"), + kind=ParameterKind.positional_only, + default="None", + ), + ) + func.parameters = Parameters(*parameters) + func.returns = keyword_overload.returns + func.overloads = None + + if docstring := func.docstring: + func.docstring = Docstring( + _document_input_arguments(docstring.value), + lineno=docstring.lineno, + endlineno=docstring.endlineno, + parent=func, + parser=docstring.parser, + parser_options=docstring.parser_options, + ) + + +def _document_input_arguments(docstring: str) -> str: + """Document ``request`` first and ``**kwargs`` last in the Args section. + + A docstring without an Args section gets one before its Returns section. + """ + request_entry = [ + " request:", + " The input as a model or dictionary. Pass this or keyword", + " arguments, not both.", + ] + kwargs_entry = [" **kwargs:", " The input fields as keyword arguments."] + lines = docstring.splitlines() + if "Args:" not in lines: + at = lines.index("Returns:") if "Returns:" in lines else len(lines) + section = ["Args:", *request_entry, *kwargs_entry, ""] + return "\n".join([*lines[:at], *section, *lines[at:]]) + + # The section's entries are indented, so it ends at the next unindented + # line. Blank lines before that line stay after the new last entry. + start = lines.index("Args:") + 1 + end = next( + (i for i in range(start, len(lines)) if lines[i] and not lines[i][0].isspace()), + len(lines), + ) + while end > start and not lines[end - 1].strip(): + end -= 1 + return "\n".join( + [*lines[:start], *request_entry, *lines[start:end], *kwargs_entry, *lines[end:]] + ) + + +class ClientConstructors(Extension): + """Give generated clients the constructor signature they inherit. + + Clients inherit a generic ``__init__(config, plugins)`` from smithy-core, + which the API reference doesn't load, so this adds one typed with the + client's own config and ``Plugin``. + """ + + def on_class_members(self, *, cls: Class, **kwargs: Any) -> None: + if "__init__" in cls.members or "Plugin" not in cls.module.members: + return + base = next( + ( + base + for base in cls.bases + if isinstance(base, ExprSubscript) + and getattr(base.left, "canonical_path", None) in CLIENT_BASES + ), + None, + ) + if base is None: + return + + def annotation(source: str) -> Any: + return get_expression(ast.parse(source, mode="eval").body, parent=cls) + + cls.set_member( + "__init__", + Function( + "__init__", + lineno=cls.lineno, + endlineno=cls.lineno, + parameters=Parameters( + Parameter("self", kind=ParameterKind.positional_or_keyword), + Parameter( + "config", + annotation=annotation(f"{base.slice} | None"), + kind=ParameterKind.positional_or_keyword, + default="None", + ), + Parameter( + "plugins", + annotation=annotation("list[Plugin] | None"), + kind=ParameterKind.positional_or_keyword, + default="None", + ), + ), + returns="None", + ), + ) diff --git a/scripts/docs/tests/test_api_reference.py b/scripts/docs/tests/test_api_reference.py index 8b3312c4..6305ea1e 100644 --- a/scripts/docs/tests/test_api_reference.py +++ b/scripts/docs/tests/test_api_reference.py @@ -2,15 +2,18 @@ import re import tomllib +from collections.abc import Callable, Iterator +from html import unescape from pathlib import Path import griffe import pytest +from griffe import ParameterKind from markdown import Markdown from mkdocstrings_handlers.python import PythonConfig, PythonHandler from scripts.docs.generate_doc_stubs import DocStubGenerator, StreamType -from scripts.docs.griffe_extensions import OverloadDocstrings +from scripts.docs.griffe_extensions import MergedOperationSignature, OverloadDocstrings REPO_ROOT = Path(__file__).resolve().parents[3] @@ -25,6 +28,53 @@ def client_dir(service: str) -> Path: ) +def text_of(html: str) -> str: + """Return rendered HTML as plain text, without highlight markup.""" + return unescape(re.sub(r"<[^>]+>", "", html)) + + +def rendered_signatures(html: str, name: str) -> list[str]: + """Return the signatures rendered for a function.""" + signatures = re.findall(rf"{name}\(.*?\) ->", text_of(html), re.S) + return [re.sub(r"\s+", " ", signature) for signature in signatures] + + +def write_client_package(root: Path, sync_client: str, async_client: str) -> Path: + """Write a minimal dual-mode client package with the given client bodies.""" + package = root / "aws_sdk_fake" + (package / "aio").mkdir(parents=True) + (package / "__init__.py").write_text("") + (package / "aio" / "__init__.py").write_text("") + (package / "models.py").write_text( + "from dataclasses import dataclass\n" + "from typing import TypedDict\n" + "@dataclass\n" + "class PingInput: ...\n" + "class PingInputDict(TypedDict): ...\n" + "class OtherInputDict(TypedDict): ...\n" + "@dataclass\n" + "class PingOutput: ...\n" + "@dataclass\n" + "class OtherOutput: ...\n" + ) + config = ( + "from collections.abc import Callable\n" + "from typing import TypeAlias\n" + "class {prefix}FakeConfig: ...\n" + "Plugin: TypeAlias = Callable[[{prefix}FakeConfig], None]\n" + ) + (package / "config.py").write_text(config.format(prefix="")) + (package / "aio" / "config.py").write_text(config.format(prefix="Async")) + models = "PingInput, PingInputDict, OtherInputDict, PingOutput, OtherOutput" + (package / "client.py").write_text( + f"from .models import {models}\nclass FakeClient:\n{sync_client}" + ) + (package / "aio" / "client.py").write_text( + f"from ..models import {models}\nclass AsyncFakeClient:\n{async_client}" + ) + return package + + @pytest.mark.parametrize( ("service", "operation_name", "stream_type", "dictionary_count"), [ @@ -54,15 +104,178 @@ def test_operation_inputs_and_streams( assert operation.stream_type == stream_type generator._generate_operation_stubs([operation]) page = (tmp_path / "operations" / f"{operation_name}.md").read_text() - assert f"::: {operation.input.module_path}" in page + # Symbol pages aren't in the navigation, so they carry the theme's path markup. + assert page.startswith('