@apollo-deploy/tesseract 1.8.0 → 2.0.0

package/templates/python/domain.hbs

@@ -1,11 +1,13 @@
 """{{interfaceName}} operations."""
 
-from typing import Optional, Dict, Any, List
+from typing import Any, Dict, Iterator, List, Literal, Optional, Union
+from urllib.parse import quote
+
+from pydantic import TypeAdapter
 {{#if imports.length}}
-from ..types import {{#each imports}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
+from ..types import {{join imports ", "}}
 {{/if}}
-from ..transport import SDKTransport, RequestOptions
-from ..errors import SDKError
+from ..transport import RequestOptions, SDKTransport
 
 
 class {{interfaceName}}:
@@ -15,125 +17,65 @@ class {{interfaceName}}:
         self._transport = transport
 
 {{#each operations}}
-{{#if isEventStream}}
-    def {{snakeCase name}}(
-        self,
+    def {{methodName}}(
+        self{{#if signature}},
+        {{{signature}}}{{/if}},
+    ) -> {{{targetResponseType}}}:
+        """{{#if summary}}{{summary}}{{else}}{{description}}{{/if}}"""
+        path = "{{path}}"
 {{#each pathParams}}
-        {{name}}: str,
+        path = path.replace("{{placeholder}}", quote(str({{parameterName}}), safe=""))
 {{/each}}
-{{#if (and queryType (not queryParams.length))}}
-        *,
-        query: Optional[Dict[str, Any]] = None,
-{{/if}}
-{{#if queryParams.length}}
-        *,
+        query: Dict[str, Any] = {}
 {{#each queryParams}}
-        {{name}}: Optional[{{pythonType type}}] = None,
-{{/each}}
-{{/if}}
-        options: Optional[RequestOptions] = None,
-    ):
-        """{{#if summary}}{{summary}}{{#if description}} - {{description}}{{/if}}{{else if description}}{{description}}{{/if}} (SSE stream)
-        """
-{{#if deprecated}}
-        # @deprecated {{deprecationMessage}}
-{{/if}}
-        # Build path with parameter substitution
-        _path = "{{path}}"
-{{#each pathParams}}
-        _path = _path.replace("{" + "{{originalName}}" + "}", str({{name}}))
-{{/each}}
-
-        # Build query parameters
-        _query: Dict[str, Any] = {}
-{{#each queryParams}}
-        if query is not None and hasattr(query, "{{name}}") and getattr(query, "{{name}}") is not None:
-            _query["{{originalName}}"] = getattr(query, "{{name}}")
-{{/each}}
-
-        response = self._transport.request(
-            method="{{httpMethod}}",
-            path=_path,
-            query=_query if _query else None,
-            options=options,
-        )
-        return response.json()
-
+{{#if required}}
+        query["{{originalName}}"] = {{parameterName}}
 {{else}}
-    def {{snakeCase name}}(
-        self,
-{{#each pathParams}}
-        {{name}}: str,
-{{/each}}
-{{#if requestBody}}
-        body: {{pythonType requestBody.type}},
+        if {{parameterName}} is not None:
+            query["{{originalName}}"] = {{parameterName}}
 {{/if}}
-{{#if (and queryType (not queryParams.length))}}
-        *,
-        query: Optional[Dict[str, Any]] = None,
-{{/if}}
-{{#if queryParams.length}}
-        *,
-{{#each queryParams}}
-        {{name}}: Optional[{{pythonType type}}] = None,
 {{/each}}
+        headers: Dict[str, str] = {}
+{{#each headerParams}}
+{{#if required}}
+        headers["{{originalName}}"] = str({{parameterName}})
+{{else}}
+        if {{parameterName}} is not None:
+            headers["{{originalName}}"] = str({{parameterName}})
 {{/if}}
-{{#if headerType}}
-        headers: Optional[{{pythonType headerType}}] = None,
-{{/if}}
-        options: Optional[RequestOptions] = None,
-    ) -> {{pythonType responseType}}:
-        """{{#if summary}}{{summary}}{{#if description}} - {{description}}{{/if}}{{else if description}}{{description}}{{/if}}
-        """
-{{#if deprecated}}
-        # @deprecated {{deprecationMessage}}
-{{/if}}
-        # Build path with parameter substitution
-        _path = "{{path}}"
-{{#each pathParams}}
-        _path = _path.replace("{" + "{{originalName}}" + "}", str({{name}}))
 {{/each}}
-
-        # Build query parameters
-        _query: Dict[str, Any] = {}
-{{#each queryParams}}
-        if {{name}} is not None:
-            _query["{{originalName}}"] = {{name}}
-{{/each}}
-{{#if queryType}}
-        if query is not None:
-            _items = query.__dict__.items() if hasattr(query, "__dict__") else []
-            for k, v in _items:
-                if v is not None:
-                    _query[k] = v
+{{#if cookieParams.length}}
+        cookies = []
+{{#each cookieParams}}
+{{#if required}}
+        cookies.append("{{originalName}}=" + str({{parameterName}}))
+{{else}}
+        if {{parameterName}} is not None:
+            cookies.append("{{originalName}}=" + str({{parameterName}}))
 {{/if}}
-
-        # Build headers
-        _headers: Dict[str, str] = {}
-{{#each headerParams}}
-        if headers is not None and hasattr(headers, "{{name}}") and getattr(headers, "{{name}}") is not None:
-            _headers["{{originalName}}"] = str(getattr(headers, "{{name}}"))
 {{/each}}
-
-{{#if (hasRequestBody this)}}
-        _content_type = "{{requestBody.contentType}}"
+        if cookies:
+            headers["Cookie"] = "; ".join(cookies)
 {{/if}}
-
+        request_options = options or RequestOptions()
+        if headers:
+            request_options.headers.update(headers)
         response = self._transport.request(
             method="{{httpMethod}}",
-            path=_path,
-{{#if (or queryParams.length queryType)}}
-            query=_query if _query else None,
-{{/if}}
-{{#if (hasRequestBody this)}}
+            path=path,
+            query=query or None,
+{{#if requestBody}}
             body=body,
-            content_type=_content_type,
-{{/if}}
-{{#if (or headerParams.length (hasRequestBody this))}}
-            options=RequestOptions(headers=_headers if _headers else None),
+            content_type="{{requestBody.contentType}}",
 {{/if}}
+            options=request_options,
         )
-        return response.json()
-
+{{#if isEventStream}}
+        return response.iter_lines()
+{{else if isVoid}}
+        return None
+{{else}}
+        return TypeAdapter({{{targetResponseType}}}).validate_python(response.json())
 {{/if}}
+
 {{/each}}

package/templates/python/pyproject.hbs

@@ -24,3 +24,8 @@ dev = [
 
 [tool.setuptools.packages.find]
 include = ["{{moduleName}}*"]
+
+[tool.setuptools.data-files]
+"." = ["README.md", "LICENSE"]
+"docs" = ["docs/*.md"]
+"docs/domains" = ["docs/domains/*.md"]

package/templates/python/readme.hbs

@@ -1,10 +1,8 @@
 # {{title}} Python SDK
 
-{{#if description}}
-{{description}}
-{{/if}}
+{{#if description}}{{description}}{{else}}Python client for the {{title}} API.{{/if}}
 
-> Auto-generated by Tesseract.
+> Generated by Tesseract. Generated source files should not be edited manually.
 
 ## Installation
 
@@ -12,7 +10,7 @@
 pip install {{packageName}}
 ```
 
-## Quick Start
+## Quick start
 
 ```python
 from {{moduleName}} import create_{{snakeCase clientName}}_client
@@ -20,45 +18,64 @@ from {{moduleName}} import create_{{snakeCase clientName}}_client
 client = create_{{snakeCase clientName}}_client(
     base_url="{{baseUrl}}",
 {{#each securitySchemes}}
-{{#if (eq type "apiKey")}}
-    {{configKey}}="your-api-key",
-{{/if}}
-{{#if (and (eq type "http") (eq scheme "bearer"))}}
-    {{configKey}}="your-bearer-token",
-{{/if}}
+    {{configKey}}="your-credential",
 {{/each}}
+    timeout_ms=15_000,
 )
 
-{{#with groups.[0]}}
-# Example: {{interfaceName}}
-result = client.{{snakeCase name}}.{{snakeCase operations.[0].name}}()
-{{/with}}
+{{#if groups.length}}
+api = client.{{groups.[0].accessorName}}
+{{/if}}
 ```
 
-## API Reference
+The client owns an `httpx.Client`. Close it when the application shuts down, or use it as a context manager.
 
-{{#each groups}}
-### {{interfaceName}}
+## Configuration and reliability
 
-{{#if description}}
-{{description}}
-{{/if}}
+- Bounded request timeouts
+- Exponential-backoff retries for transient failures
+- `Retry-After` support for rate limits
+- Default and per-request headers
+- Structured `SDKError` values containing status, code, and request ID
+- Request, response, and error hooks
 
-| Method | HTTP | Path | Description |
-|--------|------|------|-------------|
-{{#each operations}}
-| `{{name}}` | {{httpMethod}} | `{{path}}` | {{#if description}}{{description}}{{else}}-{{/if}} |
-{{/each}}
+```python
+client = create_{{snakeCase clientName}}_client(
+    timeout_ms=30_000,
+    retries=3,
+    default_headers={"X-Application": "my-service"},
+)
+```
+
+Unsafe HTTP methods are not retried unless an idempotency key is present or unsafe retries are explicitly enabled.
+
+## Documentation
 
+- [Documentation index](./docs/README.md)
+- [Generated types](./docs/types.md)
+
+| Domain | Description |
+|---|---|
+{{#each groups}}
+| [{{interfaceName}}](./docs/domains/{{fileName}}.md) | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
 {{/each}}
 
-## Error Handling
+## Error handling
 
 ```python
 from {{moduleName}}.errors import SDKError
 
 try:
-    result = client.some_api.some_method()
-except SDKError as e:
-    print(f"Error {e.status}: {e.message} ({e.code})")
+    pass  # Call a domain operation.
+except SDKError as error:
+    print(error.status, error.code, error.request_id)
+    raise
 ```
+
+## Requirements
+
+- Python 3.9 or later
+
+## License
+
+MIT

package/templates/python/resources-init.hbs

@@ -1,7 +1,7 @@
 """API resource modules for {{moduleName}}."""
 
 {{#each groups}}
-from .{{fileName}} import {{interfaceName}}
+from .{{fileModule}} import {{interfaceName}}
 {{/each}}
 
 __all__ = [

package/templates/python/transport.hbs

@@ -1,30 +1,42 @@
 """HTTP transport layer for {{moduleName}}."""
 
-import time
+from __future__ import annotations
+
+import email.utils
 import json
 import random
-from typing import Optional, Dict, Any, Callable
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional
 from urllib.parse import urlencode
+
 import httpx
+
 from .errors import SDKError
 
 
+_RETRYABLE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+_RETRYABLE_STATUSES = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+
 class RequestOptions:
-    """Per-request options."""
+    """Per-request transport overrides."""
 
     def __init__(
         self,
         timeout_ms: Optional[int] = None,
         headers: Optional[Dict[str, str]] = None,
-        signal: Optional[Any] = None,
+        retries: Optional[int] = None,
+        retry_unsafe_requests: Optional[bool] = None,
     ):
         self.timeout_ms = timeout_ms
         self.headers = headers or {}
-        self.signal = signal
+        self.retries = retries
+        self.retry_unsafe_requests = retry_unsafe_requests
 
 
 class SDKTransport:
-    """HTTP transport with retry, auth, and error handling."""
+    """Synchronous HTTP transport with bounded retries and structured errors."""
 
     def __init__(
         self,
@@ -34,25 +46,36 @@ class SDKTransport:
 {{/each}}
         timeout_ms: int = 15000,
         retries: int = 3,
+        retry_unsafe_requests: bool = False,
         default_headers: Optional[Dict[str, str]] = None,
-        on_request: Optional[Callable] = None,
-        on_response: Optional[Callable] = None,
-        on_error: Optional[Callable] = None,
+        on_request: Optional[Callable[..., None]] = None,
+        on_response: Optional[Callable[[httpx.Response], None]] = None,
+        on_error: Optional[Callable[[SDKError], None]] = None,
     ):
+        if timeout_ms <= 0:
+            raise ValueError("timeout_ms must be greater than zero")
+        if retries < 0:
+            raise ValueError("retries cannot be negative")
+
         self.base_url = base_url.rstrip("/")
 {{#each securitySchemes}}
         self._{{configKey}} = {{configKey}}
 {{/each}}
         self.timeout_ms = timeout_ms
         self.max_retries = retries
-        self.default_headers = default_headers or {}
+        self.retry_unsafe_requests = retry_unsafe_requests
+        self.default_headers = {
+            "Accept": "application/json",
+            "User-Agent": "{{moduleName}}-python-sdk/{{packageVersion}}",
+            **(default_headers or {}),
+        }
         self.on_request = on_request
         self.on_response = on_response
         self.on_error = on_error
         self._client = httpx.Client(timeout=timeout_ms / 1000.0)
 
     def _build_headers(self, extra_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
-        headers = {**self.default_headers}
+        headers = dict(self.default_headers)
 {{#each securitySchemes}}
 {{#if (eq type "apiKey")}}
         if self._{{configKey}}:
@@ -84,84 +107,173 @@ class SDKTransport:
         content_type: str = "application/json",
         options: Optional[RequestOptions] = None,
     ) -> httpx.Response:
-        """Execute an HTTP request with retry logic."""
+        """Execute a request and retry only transient, idempotent failures."""
+        method = method.upper()
         url = self.base_url + path
         headers = self._build_headers(options.headers if options else None)
-        timeout = (options.timeout_ms if options and options.timeout_ms else self.timeout_ms) / 1000.0
+        timeout_ms = (
+            options.timeout_ms
+            if options is not None and options.timeout_ms is not None
+            else self.timeout_ms
+        )
+        retries = (
+            options.retries
+            if options is not None and options.retries is not None
+            else self.max_retries
+        )
+        retry_unsafe = (
+            options.retry_unsafe_requests
+            if options is not None and options.retry_unsafe_requests is not None
+            else self.retry_unsafe_requests
+        )
+
+        if timeout_ms <= 0:
+            raise ValueError("timeout_ms must be greater than zero")
+        if retries < 0:
+            raise ValueError("retries cannot be negative")
 
         if query:
-            filtered = {k: v for k, v in query.items() if v is not None}
+            filtered = {key: value for key, value in query.items() if value is not None}
             if filtered:
-                url += "?" + urlencode(filtered)
+                url += "?" + urlencode(filtered, doseq=True)
 
-        data = None
+        content = None
         if body is not None:
             if content_type == "application/json":
-                data = json.dumps(body, default=str)
+                payload = (
+                    body.model_dump(by_alias=True, exclude_none=True)
+                    if hasattr(body, "model_dump")
+                    else body
+                )
+                content = json.dumps(payload, default=str)
                 headers["Content-Type"] = "application/json"
             else:
-                data = body
+                content = body
+                headers["Content-Type"] = content_type
 
-        last_error = None
-        for attempt in range(self.max_retries + 1):
+        can_retry = self._can_retry(method, headers, retry_unsafe)
+        last_error: Optional[SDKError] = None
+
+        for attempt in range(retries + 1):
             try:
                 if self.on_request:
-                    self.on_request(method, url, attempt)
+                    self.on_request(method=method, url=url, attempt=attempt)
 
                 response = self._client.request(
                     method=method,
                     url=url,
                     headers=headers,
-                    content=data,
-                    timeout=timeout,
+                    content=content,
+                    timeout=timeout_ms / 1000.0,
                 )
 
                 if self.on_response:
                     self.on_response(response)
 
-                if response.status_code >= 400:
-                    self._handle_error_response(response)
+                if response.status_code < 400:
+                    return response
 
-                return response
+                last_error = self._error_from_response(response)
+                if not (
+                    can_retry
+                    and attempt < retries
+                    and response.status_code in _RETRYABLE_STATUSES
+                ):
+                    self._notify_error(last_error)
+                    raise last_error
 
-            except httpx.TimeoutException as e:
-                last_error = SDKError("Request timed out: " + str(e), 0, "timeout")
-            except httpx.NetworkError as e:
-                last_error = SDKError("Network error: " + str(e), 0, "network_error")
+                self._sleep_before_retry(attempt, response.headers.get("Retry-After"))
+            except (httpx.TimeoutException, httpx.NetworkError) as error:
+                code = "timeout" if isinstance(error, httpx.TimeoutException) else "network_error"
+                last_error = SDKError(str(error) or "Request failed", 0, code)
+                if not (can_retry and attempt < retries):
+                    self._notify_error(last_error)
+                    raise last_error from error
+                self._sleep_before_retry(attempt, None)
             except SDKError:
                 raise
-            except Exception as e:
-                last_error = SDKError("Request failed: " + str(e), 0, "unknown_error")
+            except Exception as error:
+                last_error = SDKError(str(error) or "Request failed", 0, "unknown_error")
+                self._notify_error(last_error)
+                raise last_error from error
+
+        error = last_error or SDKError("Request failed after retries", 0, "retry_exhausted")
+        self._notify_error(error)
+        raise error
 
-            if attempt < self.max_retries:
-                delay = min(1000 * (2 ** attempt) + random.uniform(0, 500), 30000) / 1000.0
-                time.sleep(delay)
+    def _can_retry(self, method: str, headers: Dict[str, str], retry_unsafe: bool) -> bool:
+        if retry_unsafe or method in _RETRYABLE_METHODS:
+            return True
+        return any(
+            name.lower() == "x-idempotency-key" and bool(value)
+            for name, value in headers.items()
+        )
 
-        if self.on_error and last_error:
-            self.on_error(last_error)
-        raise last_error
+    def _sleep_before_retry(self, attempt: int, retry_after: Optional[str]) -> None:
+        delay = self._parse_retry_after(retry_after)
+        if delay is None:
+            maximum = min(0.4 * (2**attempt), 30.0)
+            delay = random.uniform(0.0, maximum)
+        time.sleep(delay)
 
-    def _handle_error_response(self, response: httpx.Response) -> None:
+    @staticmethod
+    def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+        if not value:
+            return None
+        try:
+            return min(max(float(value), 0.0), 30.0)
+        except ValueError:
+            try:
+                parsed = email.utils.parsedate_to_datetime(value)
+                if parsed.tzinfo is None:
+                    parsed = parsed.replace(tzinfo=timezone.utc)
+                return min(
+                    max((parsed - datetime.now(timezone.utc)).total_seconds(), 0.0),
+                    30.0,
+                )
+            except (TypeError, ValueError, OverflowError):
+                return None
+
+    def _error_from_response(self, response: httpx.Response) -> SDKError:
+        request_id = response.headers.get("x-request-id") or response.headers.get("request-id")
         try:
             body = response.json()
-            error_code = body.get("error", "unknown_error")
-            message = body.get("message", response.text)
-            request_id = body.get("request_id")
-            raise SDKError(message, response.status_code, error_code, request_id)
-        except (json.JSONDecodeError, KeyError):
-            raise SDKError(
-                "HTTP " + str(response.status_code) + ": " + str(response.text)[:200],
+        except json.JSONDecodeError:
+            body = None
+
+        if isinstance(body, dict):
+            nested = body.get("error") if isinstance(body.get("error"), dict) else None
+            code = body.get("code") or (nested or {}).get("code")
+            if not code and isinstance(body.get("error"), str):
+                code = body.get("error")
+            message = body.get("message") or (nested or {}).get("message")
+            return SDKError(
+                str(message or response.reason_phrase or "Request failed"),
                 response.status_code,
-                "http_error",
+                str(code or "http_error"),
+                str(body.get("request_id") or request_id) if body.get("request_id") or request_id else None,
+                details=body.get("details"),
             )
 
-    def close(self):
+        text = response.text.strip()
+        return SDKError(
+            text[:500] or f"HTTP {response.status_code}: {response.reason_phrase}",
+            response.status_code,
+            "http_error",
+            request_id,
+        )
+
+    def _notify_error(self, error: SDKError) -> None:
+        if self.on_error:
+            self.on_error(error)
+
+    def close(self) -> None:
         self._client.close()
 
-    def __enter__(self):
+    def __enter__(self) -> "SDKTransport":
         return self
 
-    def __exit__(self, *args):
+    def __exit__(self, *_: Any) -> None:
         self.close()
 
 
@@ -172,10 +284,11 @@ def create_transport(
 {{/each}}
     timeout_ms: int = 15000,
     retries: int = 3,
+    retry_unsafe_requests: bool = False,
     default_headers: Optional[Dict[str, str]] = None,
-    on_request: Optional[Callable] = None,
-    on_response: Optional[Callable] = None,
-    on_error: Optional[Callable] = None,
+    on_request: Optional[Callable[..., None]] = None,
+    on_response: Optional[Callable[[httpx.Response], None]] = None,
+    on_error: Optional[Callable[[SDKError], None]] = None,
 ) -> SDKTransport:
     return SDKTransport(
         base_url=base_url,
@@ -184,6 +297,7 @@ def create_transport(
 {{/each}}
         timeout_ms=timeout_ms,
         retries=retries,
+        retry_unsafe_requests=retry_unsafe_requests,
         default_headers=default_headers,
         on_request=on_request,
         on_response=on_response,