Add design doc and a few generator tweaks

Author: JordonPhillips

codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/StructureGenerator.java

@@ -31,6 +31,7 @@
 import software.amazon.smithy.model.traits.InputTrait;
 import software.amazon.smithy.model.traits.OutputTrait;
 import software.amazon.smithy.model.traits.RequiredTrait;
+import software.amazon.smithy.model.traits.RetryableTrait;
 import software.amazon.smithy.model.traits.SensitiveTrait;
 import software.amazon.smithy.model.traits.StreamingTrait;
 import software.amazon.smithy.python.codegen.CodegenUtils;
@@ -134,12 +135,26 @@ private void renderError() {
         var symbol = symbolProvider.toSymbol(shape);
         var baseError = CodegenUtils.getServiceError(settings);
         writer.pushState(new ErrorSection(symbol));
+        writer.putContext("retryable", false);
+        writer.putContext("throttling", false);
+
+        var retryableTrait = shape.getTrait(RetryableTrait.class);
+        if (retryableTrait.isPresent()) {
+            writer.putContext("retryable", true);
+            writer.putContext("throttling", retryableTrait.get().getThrottling());
+        }
         writer.write("""
                 @dataclass(kw_only=True)
                 class $1L($2T):
                     ${4C|}
 
                     fault: Literal["client", "server"] | None = $3S
+                    ${?retryable}
+                    is_retry_safe: bool | None = True
+                    ${?throttling}
+                    is_throttle: bool = True
+                    ${/throttling}
+                    ${/retryable}
 
                     ${5C|}
 

codegen/core/src/main/java/software/amazon/smithy/python/codegen/integrations/HttpProtocolGeneratorUtils.java

@@ -140,6 +140,7 @@ public static void generateErrorDispatcher(
         delegator.useFileWriter(errorDispatcher.getDefinitionFile(), errorDispatcher.getNamespace(), writer -> {
             writer.pushState(new ErrorDispatcherSection(operation, errorShapeToCode, errorMessageCodeGenerator));
             writer.addImport("smithy_core.exceptions", "CallException");
+            // TODO: include standard retry-after in the pure-python version of this
             writer.write("""
                     async def $1L(http_response: $2T, config: $3T) -> CallException:
                         ${4C|}
@@ -148,9 +149,12 @@ public static void generateErrorDispatcher(
                             ${5C|}
 
                             case _:
+                                is_throttle = http_response.status == 429
                                 return CallException(
                                     message=f"{code}: {message}",
-                                    fault="client" if http_response.status < 500 else "server"
+                                    fault="client" if http_response.status < 500 else "server",
+                                    is_throttle=is_throttle,
+                                    is_retry_safe=is_throttle or None,
                                 )
                     """,
                     errorDispatcher.getName(),

designs/exceptions.md

@@ -0,0 +1,124 @@
+# Exceptions
+
+Exceptions are a necessary aspect of any software product (Go notwithstanding),
+and care must be taken in how they're exposed. This document describes how
+smithy-python clients will expose exceptions to customers.
+
+## Goals
+
+* Every exception raised by a Smithy client should be catchable with a single,
+  specific catch statement (that is, not just `except Exception`).
+* Every modeled exception raised by a service should be catchable with a single,
+  specific catch statement.
+* Exceptions should contain information about retryablility where relevant.
+
+## Specification
+
+Every exception raised by a Smithy client MUST inherit from `SmithyException`.
+
+```python
+class SmithyException(Exception):
+    """Base exception type for all exceptions raised by smithy-python."""
+```
+
+If an exception that is not a `SmithyException` is thrown while executing a
+request, that exception MUST be wrapped in a `SmithyException` and the
+`__cause__` MUST be set to the original exception.
+
+Just as in normal Python programming, different exception types SHOULD be made
+for different kinds of exceptions. `SerializationException`, for example, will
+serve as the exception type for any exceptions that occur while serializing a
+request.
+
+### Retryability
+
+Not all exceptions need to include information about retryability, as most will
+not be retryable at all. To avoid overly complicating the class hierarchy,
+retryability properties will be standardized as a `Protocol` that exceptions MAY
+implement.
+
+```python
+@dataclass(kw_only=True)
+@runtime_checkable
+class RetryInfo(Protocol):
+    is_retry_safe: bool | None = None
+    """Whether the exception is safe to retry.
+
+    A value of True does not mean a retry will occur, but rather that a retry is allowed
+    to occur.
+
+    A value of None indicates that there is not enough information available to
+    determine if a retry is safe.
+    """
+
+    retry_after: float | None = None
+    """The amount of time that should pass before a retry.
+
+    Retry strategies MAY choose to wait longer.
+    """
+
+    is_throttle: bool = False
+    """Whether the error is a throttling error."""
+```
+
+If an exception with `RetryInfo` is received while attempting to send a
+serialized request to the server, the contained information will be used to
+inform the next retry.
+
+### Service Exceptions
+
+Exceptions returned by the service MUST be a `CallException`. `CallException`s
+include a `fault` property that indicates whether the client or server is
+responsible for the exception. HTTP protocols can determine this based on the
+status code.
+
+Similarly, protocols can and should determine retry information. HTTP protocols
+can generally be confident that a status code 429 is a throttling error and can
+also make use of the `Retry-After` header. Specific protocols may also include
+more information in protocol-specific headers.
+
+```python
+type Fault = Literal["client", "server"] | None
+"""Whether the client or server is at fault.
+
+If None, then there was not enough information to determine fault.
+"""
+
+
+@dataclass(kw_only=True)
+class CallException(SmithyException, RetryInfo):
+    fault: Fault = None
+    message: str = field(default="", kw_only=False)
+```
+
+#### Modeled Exceptions
+
+Most exceptions thrown by a service will be present in the Smithy model for the
+service. These exceptions will all be generated into the client package. Each
+modeled exception will be inherit from a generated exception named
+`ServiceException` which itself inherits from the static `ModeledException`.
+
+```python
+@dataclass(kw_only=True)
+class ModeledException(CallException):
+    """Base exception to be used for modeled errors."""
+```
+
+The Smithy model itself can contain fault information in the
+[error trait](https://smithy.io/2.0/spec/type-refinement-traits.html#smithy-api-error-trait)
+and retry information in the
+[retryable trait](https://smithy.io/2.0/spec/behavior-traits.html#retryable-trait).
+This information will be statically generated onto the exception.
+
+```python
+@dataclass(kw_only=True)
+class ServiceException(ModeledException):
+    pass
+
+
+@dataclass(kw_only=True)
+class ThrottlingException(ServcieException):
+    fault: Fault = "client"
+    is_retry_safe: bool | None = True
+    is_throttle: bool = True
+```

packages/smithy-core/src/smithy_core/exceptions.py

@@ -1,14 +1,22 @@
 #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #  SPDX-License-Identifier: Apache-2.0
 from dataclasses import dataclass, field
-from typing import Literal, Protocol
+from typing import Literal, Protocol, runtime_checkable
 
 
 class SmithyException(Exception):
     """Base exception type for all exceptions raised by smithy-python."""
 
 
+type Fault = Literal["client", "server"] | None
+"""Whether the client or server is at fault.
+
+If None, then there was not enough information to determine fault.
+"""
+
+
 @dataclass(kw_only=True)
+@runtime_checkable
 class RetryInfo(Protocol):
     is_retry_safe: bool | None = None
     """Whether the exception is safe to retry.
@@ -32,9 +40,9 @@ class RetryInfo(Protocol):
 
 @dataclass(kw_only=True)
 class CallException(SmithyException, RetryInfo):
-    """Base exceptio to be used in application-level errors."""
+    """Base exception to be used in application-level errors."""
 
-    fault: Literal["client", "server"] | None = None
+    fault: Fault = None
     """Whether the client or server is at fault.
 
     If None, then there was not enough information to determine fault.
@@ -51,11 +59,7 @@ def __post_init__(self):
 class ModeledException(CallException):
     """Base exception to be used for modeled errors."""
 
-    fault: Literal["client", "server"] | None = "client"
-    """Whether the client or server is at fault.
-
-    If None, then there was not enough information to determine fault.
-    """
+    fault: Fault = "client"
 
 
 class SerializationException(Exception):