Document Bedrock helpers

Author: jim-openai

src/openai/lib/bedrock.py

@@ -85,6 +85,7 @@ class _BedrockCapabilities:
 
 
 def _normalize_bedrock_base_url(base_url: str | httpx.URL) -> httpx.URL:
+    """Normalize a Bedrock Responses URL variant back to the provider API root."""
     url = httpx.URL(base_url)
     path = url.path.rstrip("/")
     responses_match = re.search(r"/responses(?:/.*)?$", path)
@@ -95,6 +96,7 @@ def _normalize_bedrock_base_url(base_url: str | httpx.URL) -> httpx.URL:
 
 
 def _resolve_bedrock_base_url(base_url: str | httpx.URL | None, aws_region: str | None) -> httpx.URL:
+    """Resolve Bedrock base URL precedence from explicit, env, then region config."""
     if isinstance(base_url, str) and not base_url.strip():
         base_url = None
 
@@ -143,6 +145,7 @@ def _iter_values(value: object) -> Iterable[object]:
 
 
 def _validate_tool_like(value: object) -> None:
+    """Reject denylisted Responses tool definitions and tool choices."""
     tool_type = _mapping_type(value)
     if tool_type in _BEDROCK_CAPABILITIES.unsupported_tool_types:
         _unsupported_feature(f"responses tools of type `{tool_type}`")
@@ -153,6 +156,7 @@ def _validate_tool_like(value: object) -> None:
 
 
 def _validate_input_value(value: object) -> None:
+    """Walk nested Responses input values and reject denylisted item types."""
     item_type = _mapping_type(value)
     if item_type in _BEDROCK_CAPABILITIES.unsupported_input_item_types:
         _unsupported_feature(f"responses input items of type `{item_type}`")
@@ -171,6 +175,7 @@ def _validate_include(include: object) -> None:
 
 
 def _merge_response_body(values: Mapping[str, object], extra_body: Body | None = None) -> dict[str, object]:
+    """Reconstruct a generated Responses body for Bedrock capability validation."""
     body = {
         key: value
         for key, value in values.items()
@@ -183,6 +188,7 @@ def _merge_response_body(values: Mapping[str, object], extra_body: Body | None =
 
 
 def _validate_response_create_body(body: Mapping[str, object]) -> None:
+    """Fail early only for Bedrock Responses features known to be unsupported."""
     for tool in _iter_values(body.get("tools", ())):
         _validate_tool_like(tool)
 
@@ -200,6 +206,7 @@ def _validate_response_create_body(body: Mapping[str, object]) -> None:
 
 
 def _bedrock_token_provider(provider: BedrockTokenProvider) -> BedrockTokenProvider:
+    """Adapt a sync Bedrock token provider to the base client's api_key callback."""
     def get_token() -> str:
         token = cast(object, provider())
         if not isinstance(token, str) or not token:
@@ -211,6 +218,7 @@ def get_token() -> str:
 
 
 def _async_bedrock_token_provider(provider: AsyncBedrockTokenProvider) -> Callable[[], Awaitable[str]]:
+    """Adapt a sync or async Bedrock token provider to the async api_key callback."""
     async def get_token() -> str:
         token = cast(object, provider())
         if inspect.isawaitable(token):
@@ -225,6 +233,7 @@ async def get_token() -> str:
 
 
 def _guard_responses(responses: Responses) -> Responses:
+    """Wrap generated Responses helpers with Bedrock-specific early validation."""
     create = responses.create
     compact = responses.compact
     parse = responses.parse
@@ -284,6 +293,7 @@ def guarded_connect(*args: Any, **kwargs: Any) -> Any:
 
 
 def _guard_async_responses(responses: AsyncResponses) -> AsyncResponses:
+    """Wrap generated async Responses helpers with Bedrock-specific early validation."""
     create = responses.create
     compact = responses.compact
     parse = responses.parse
@@ -347,9 +357,12 @@ def _unsupported_resource_property(resource_name: str) -> property:
 
 
 class BaseBedrockClient:
+    """Shared Responses-only surface restrictions for Bedrock client wrappers."""
+
     aws_region: str | None
 
 
+# Bedrock v1 intentionally exposes Responses only; raw/streaming wrappers inherit these guards.
 for _resource_name in (
     "admin",
     "audio",