Merge branch 'main' into claude/python-sdk-audit-o2iid9-13-null-data-validation

Author: razor-x

README.rst

@@ -682,6 +682,31 @@ and its ``Retry`` class is re-exported from ``seam`` for convenience:
         retries=Retry(total=3, backoff_factor=0.5, status_forcelist=[503]),
     )
 
+Bringing your own transport
++++++++++++++++++++++++++++
+
+A custom ``transport`` or ``mounts`` passed through ``httpx_options`` replaces
+the transport the SDK builds, so it takes full responsibility for retries:
+requests through it are not retried unless you wrap it yourself. Combining
+either with the ``retries`` option raises a ``SeamInvalidOptionsError``. To
+retry through your own transport, wrap it with ``RetryTransport``:
+
+.. code-block:: python
+
+    from httpx_retries import RetryTransport
+
+    from seam import Seam, Retry
+
+    seam = Seam(
+        api_key="your-api-key",
+        httpx_options={
+            "transport": RetryTransport(
+                transport=MyCustomTransport(),
+                retry=Retry(total=2, status_forcelist=[429, 503]),
+            ),
+        },
+    )
+
 Configuring the httpx client
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

codegen/layouts/partials/method-docstring.hbs

@@ -4,7 +4,7 @@
 
         :param wait_for_action_attempt: Whether, and for how long, to wait for the action attempt to finish.{{/if}}{{#unless (eq returnType "None")}}
 
-        :returns: {{{indent (pythonDoc responseDescription) 8}}}{{/unless}}{{#if hasRequiredParameters}}
+        :returns: {{{indent (pythonDoc responseDescription) 8}}}{{/unless}}{{#if requiresAtLeastOneParameter}}
 
         :raises ValueError: At least one parameter must be provided.{{/if}}{{#if isDeprecated}}
 

codegen/layouts/partials/route-method.hbs

@@ -1,4 +1,4 @@
-    @route_metadata(path="{{path}}", has_required_parameters={{#if hasRequiredParameters}}True{{else}}False{{/if}}, has_pagination={{#if hasPagination}}True{{else}}False{{/if}})
+    @route_metadata(path="{{path}}", at_least_one_parameter_names=({{#each atLeastOneParameterNames}}"{{this}}",{{#unless @last}} {{/unless}}{{/each}}), has_pagination={{#if hasPagination}}True{{else}}False{{/if}})
     {{#if isAsync}}async {{/if}}def {{> method-signature}}:
         """{{> method-docstring}}"""
         {{payloadVar}}: Dict[str, Any] = {}
@@ -7,9 +7,12 @@
         if {{name}} is not None:
             {{../payloadVar}}["{{name}}"] = {{name}}
 {{/each}}
-{{#if hasRequiredParameters}}
+{{#if requiresAtLeastOneParameter}}
 
-        if not {{payloadVar}}:
+        if all(
+            param is None
+            for param in ({{#each atLeastOneParameterNames}}{{this}},{{#unless @last}} {{/unless}}{{/each}})
+        ):
             raise ValueError("At least one parameter is required for {{path}}")
 {{/if}}
 
@@ -24,16 +27,19 @@
 
         return {{#if isAsync}}await resolve_action_attempt_async{{else}}resolve_action_attempt{{/if}}(
             client=self.client,
-            action_attempt=action_attempt_from_dict(res["action_attempt"]),
+            action_attempt=action_attempt_from_dict(unwrap(res, "action_attempt", "{{path}}")),
             wait_for_action_attempt=wait_for_action_attempt
         )
 {{else if (eq returnType "None")}}
 
         return None
 {{else if (isListType returnType)}}
 
-        return [{{fromDict (listItemType returnType)}}(item) for item in res{{#each returnPath}}["{{this}}"]{{/each}}]
+        return {{#if hasPagination}}PaginatedList(
+            [{{fromDict (listItemType returnType)}}(item) for item in unwrap_list(res, "{{returnPath.[0]}}", "{{path}}")],
+            pagination=res.get("pagination"),
+        ){{else}}[{{fromDict (listItemType returnType)}}(item) for item in unwrap_list(res, "{{returnPath.[0]}}", "{{path}}")]{{/if}}
 {{else}}
 
-        return {{fromDict returnType}}(res{{#each returnPath}}["{{this}}"]{{/each}})
+        return {{fromDict returnType}}(unwrap(res, "{{returnPath.[0]}}", "{{path}}"))
 {{/if}}

codegen/layouts/route.hbs

@@ -14,6 +14,15 @@ from .{{module}} import {{abstractClassName}}, {{className}}, {{asyncAbstractCla
 {{#if importResolveActionAttempt}}
 from ..modules.action_attempts import resolve_action_attempt, resolve_action_attempt_async
 {{/if}}
+{{#if importUnwrap}}
+from ..response import unwrap
+{{/if}}
+{{#if importUnwrapList}}
+from ..response import unwrap_list
+{{/if}}
+{{#if importPaginatedList}}
+from ..pagination import PaginatedList
+{{/if}}
 
 
 {{> abstract-route-class abstractClass}}

codegen/lib/layouts/route.ts

@@ -14,7 +14,8 @@ export interface MethodLayoutContext {
   httpVerb: string
   payloadVar: string
   payloadArg: string
-  hasRequiredParameters: boolean
+  requiresAtLeastOneParameter: boolean
+  atLeastOneParameterNames: string[]
   hasPagination: boolean
   description: string
   responseDescription: string
@@ -61,9 +62,22 @@ export interface RouteLayoutContext {
   }>
   importResolveActionAttempt: boolean
   importNull: boolean
+  importUnwrap: boolean
+  importUnwrapList: boolean
+  importPaginatedList: boolean
   methods: MethodLayoutContext[]
 }
 
+const paginationParameterNames = new Set(['limit', 'page_cursor'])
+
+const getAtLeastOneParameterNames = (method: ClassMethod): string[] =>
+  method.hasRequiredParameters &&
+  method.parameters.every(({ required }) => !(required ?? false))
+    ? method.parameters
+        .map(({ name }) => name)
+        .filter((name) => !paginationParameterNames.has(name))
+    : []
+
 const getRequestLayoutContext = (
   preferredMethod: string,
 ): Pick<MethodLayoutContext, 'httpVerb' | 'payloadVar' | 'payloadArg'> => {
@@ -82,7 +96,8 @@ export const getMethodLayoutContext = (
   name: method.methodName,
   path: method.path,
   ...getRequestLayoutContext(method.preferredMethod),
-  hasRequiredParameters: method.hasRequiredParameters,
+  requiresAtLeastOneParameter: getAtLeastOneParameterNames(method).length > 0,
+  atLeastOneParameterNames: getAtLeastOneParameterNames(method),
   hasPagination: method.hasPagination,
   description: method.description,
   responseDescription: method.responseDescription,
@@ -130,6 +145,18 @@ export const setRouteLayoutContext = (cls: ClassModel): RouteLayoutContext => {
     params.some(({ isNullable }) => isNullable),
   )
 
+  const importUnwrap = methods.some(
+    ({ returnPath, returnType }) =>
+      returnPath.length > 0 && !returnType.startsWith('List['),
+  )
+
+  const importUnwrapList = methods.some(
+    ({ returnPath, returnType }) =>
+      returnPath.length > 0 && returnType.startsWith('List['),
+  )
+
+  const importPaginatedList = methods.some(({ hasPagination }) => hasPagination)
+
   const showPass =
     cls.methods.length === 0 && cls.childClassIdentifiers.length === 0
 
@@ -172,6 +199,9 @@ export const setRouteLayoutContext = (cls: ClassModel): RouteLayoutContext => {
     })),
     importResolveActionAttempt,
     importNull,
+    importUnwrap,
+    importUnwrapList,
+    importPaginatedList,
     methods,
   }
 }

package-lock.json

@@ -30,7 +30,7 @@
   "packageManager": "npm@11.19.0",
   "devDependencies": {
     "@seamapi/blueprint": "^1.10.0",
-    "@seamapi/fake-seam-connect": "2.0.5",
+    "@seamapi/fake-seam-connect": "2.0.6",
     "@seamapi/smith": "^1.1.0",
     "@seamapi/types": "1.1047.0",
     "change-case": "^5.4.4",

package.json

@@ -1,6 +1,6 @@
 [project]
 name = "seam"
-version = "3.13.3"
+version = "3.13.8"
 description = "SDK for the Seam API written in Python."
 authors = [{ name = "Seam Labs, Inc.", email = "engineering@getseam.com" }]
 license = "MIT"

pyproject.toml

@@ -8,6 +8,7 @@
 from .exceptions import (
     SeamError,
     SeamHttpApiError,
+    SeamHttpInvalidResponseError,
     SeamHttpUnauthorizedError,
     SeamHttpInvalidInputError,
     SeamValidationError,

seam/__init__.py

@@ -1,4 +1,5 @@
 from collections.abc import Mapping
+from json import JSONDecodeError
 from typing import Any, Dict, Optional
 from importlib.metadata import version
 import abc
@@ -14,6 +15,7 @@
     SeamHttpUnauthorizedError,
 )
 from .null import replace_null
+from .options import SeamInvalidOptionsError
 from .strict_url_search_params_serializer import serialize_url_search_params
 
 SDK_HEADERS = {
@@ -68,7 +70,13 @@ def _handle_response(self, response: Response):
             self._handle_error_response(response)
 
         if "application/json" in response.headers.get("content-type", ""):
-            return response.json()
+            try:
+                return response.json()
+            except JSONDecodeError:
+                # A body that lies about its content type is handed on as
+                # text, so readers report an invalid response instead of
+                # leaking a decode error.
+                return response.text
 
         return response.text
 
@@ -105,14 +113,24 @@ def __init__(
         self,
         base_url: str,
         auth_headers: Dict[str, str],
-        retries: Optional[Retry] = DEFAULT_RETRIES,
+        retries: Optional[Retry] = None,
         timeout: Optional[float] = DEFAULT_TIMEOUT,
         httpx_options: Optional[Dict[str, Any]] = None,
         **kwargs,
     ):
         options = _build_client_options(base_url, timeout, httpx_options, kwargs)
 
         custom_headers = options.pop("headers", {})
+
+        if retries is not None and (
+            options.get("transport") is not None or options.get("mounts") is not None
+        ):
+            raise SeamInvalidOptionsError(
+                "The retries option cannot be combined with a custom transport "
+                "or mounts, which bypass the retry transport; wrap your "
+                "transport with httpx_retries.RetryTransport instead"
+            )
+
         self._retry_policy = DEFAULT_RETRIES if retries is None else retries
 
         super().__init__(**options)
@@ -173,14 +191,24 @@ def __init__(
         self,
         base_url: str,
         auth_headers: Dict[str, str],
-        retries: Optional[Retry] = DEFAULT_RETRIES,
+        retries: Optional[Retry] = None,
         timeout: Optional[float] = DEFAULT_TIMEOUT,
         httpx_options: Optional[Dict[str, Any]] = None,
         **kwargs,
     ):
         options = _build_client_options(base_url, timeout, httpx_options, kwargs)
 
         custom_headers = options.pop("headers", {})
+
+        if retries is not None and (
+            options.get("transport") is not None or options.get("mounts") is not None
+        ):
+            raise SeamInvalidOptionsError(
+                "The retries option cannot be combined with a custom transport "
+                "or mounts, which bypass the retry transport; wrap your "
+                "transport with httpx_retries.RetryTransport instead"
+            )
+
         self._retry_policy = DEFAULT_RETRIES if retries is None else retries
 
         super().__init__(**options)