Clarify wording of interceptor documentation

Author: JordonPhillips

python-packages/smithy-python/smithy_python/interfaces/interceptor.py

@@ -50,6 +50,12 @@ def response(self) -> Response | Exception:
         """
         return self._response
 
+    # Note that TransportRequest (and TransportResponse below) aren't resolved types,
+    # but rather TypeVars. This is very important, because in the actual Interceptor
+    # interface class these are sometimes typed as None rather than, say, HttpRequest.
+    # That lets us use the type system to tell people when something will be set and
+    # when it will not be set without leaking nullability into the cases where the
+    # property will ALWAYS be set.
     @property
     def transport_request(self) -> TransportRequest:
         """Retrieve the transmittable request for the operation being invoked.
@@ -146,15 +152,15 @@ def modify_before_serialization(
         self, context: InterceptorContext[Request, None, None, None]
     ) -> Request:
         """
-        A hook called before the request is marshalled into a transport message.
+        A hook called before the request is serialized into a transport request.
         This method has the ability to modify and return a new request of the
         same type.
 
         This will ALWAYS be called once per execution, except when a failure occurs
         earlier in the request pipeline.
 
         The `request` of the context will always be available. This `request` may have
-        been modified by earlier `modify_before_serializtion` hooks, and may be
+        been modified by earlier `modify_before_serialization` hooks, and may be
         modified further by later hooks. Other static properites will be None.
 
         If exceptions are thrown by this hook, execution will jump to
@@ -169,7 +175,7 @@ def read_before_serialization(
         self, context: InterceptorContext[Request, None, None, None]
     ) -> None:
         """
-        A hook called before the input message is marshalled into a transport message.
+        A hook called before the input message is serialized into a transport request.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
@@ -191,15 +197,15 @@ def read_after_serialization(
         self, context: InterceptorContext[Request, None, TransportRequest, None]
     ) -> None:
         """
-        A hook called after the input message is marshalled into a transport message.
+        A hook called after the input message is serialized into a transport request.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
 
         This will always be called once per execution, except when a failure occurs
-        earlier in the request pipeline. The duration between invocation of this hook
-        and `read_before_serialization` is very close to the amount of time spent
-        marshalling the request.
+        earlier in the request pipeline. The duration between
+        `read_before_serialization` and the invocation of this hook is very close to
+        the amount of time spent serializing the request.
 
         The `request` and `transport_request` of the context will always be available.
         Other static properties will be None.
@@ -231,8 +237,8 @@ def read_before_attempt(
         self, context: InterceptorContext[Request, None, TransportRequest, None]
     ) -> None:
         """
-        A hook called before each attempt at sending the transmission request message
-        to the service.
+        A hook called before each attempt at sending the transport request to the
+        service.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
@@ -258,9 +264,8 @@ def modify_before_signing(
         self, context: InterceptorContext[Request, None, TransportRequest, None]
     ) -> TransportRequest:
         """
-        A hook called before the transport request message is signed. This method has
-        the ability to modify and return a new transport request message of the same
-        type.
+        A hook called before the transport request is signed. This method has the
+        ability to modify and return a new transport request of the same type.
 
         This will always be called once per attempt, except when a failure occurs
         earlier in the request pipeline. This method will be called multiple times in
@@ -284,7 +289,7 @@ def read_before_signing(
         self, context: InterceptorContext[Request, None, TransportRequest, None]
     ) -> None:
         """
-        A hook called before the transport request message is signed.
+        A hook called before the transport request is signed.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
@@ -309,15 +314,15 @@ def read_after_signing(
         self, context: InterceptorContext[Request, None, TransportRequest, None]
     ) -> None:
         """
-        A hook called after the transport request message is signed.
+        A hook called after the transport request is signed.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
 
         This will always be called once per attempt, except when a failure occurs
         earlier in the request pipeline. This method may be called multiple times in
-        the event of retries. The duration between invocation of this hook and
-        `read_before_signing` is very close to the amount of time spent signing the
+        the event of retries. The duration between `read_before_signing` and the
+        invocation of this hook is very close to the amount of time spent signing the
         request.
 
         The `request` and `transport_request` of the context will always be available.
@@ -334,8 +339,8 @@ def modify_before_transmit(
         self, context: InterceptorContext[Request, None, TransportRequest, None]
     ) -> TransportRequest:
         """
-        A hook called before the transport request message is sent to the service. This
-        method has the ability to modify and return a new transport request message of
+        A hook called before the transport request is sent to the service. This
+        method has the ability to modify and return a new transport request of
         the same type.
 
         This will always be called once per attempt, except when a failure occurs
@@ -360,14 +365,14 @@ def read_before_transmit(
         self, context: InterceptorContext[Request, None, TransportRequest, None]
     ) -> None:
         """
-        A hook called before the transport request message is sent to the service.
+        A hook called before the transport request is sent to the service.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
 
         This will always be called once per attempt, except when a failure occurs
         earlier in the request pipeline. This method may be called multiple times in
-        the event of retries.The duration between invocation of this hook and
+        the event of retries. The duration between invocation of this hook and
         `read_after_transmit` is very close to the amount of time spent communicating
         with the service. Depending on the protocol, the duration may not include the
         time spent reading the response data.
@@ -387,16 +392,16 @@ def read_after_transmit(
         context: InterceptorContext[Request, None, TransportRequest, TransportResponse],
     ) -> None:
         """
-        A hook called after the transport request message is sent to the service and a
+        A hook called after the transport request is sent to the service and a
         transport response is received.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
 
         This will always be called once per attempt, except when a failure occurs
         earlier in the request pipeline. This method may be called multiple times in
-        the event of retries. The duration between invocation of this hook and
-        `read_before_transmit` is very close to the amount of time spent communicating
+        the event of retries. The duration between `read_before_transmit` and the
+        invocation of this hook is very close to the amount of time spent communicating
         with the service. Depending on the protocol, the duration may not include the
         time spent reading the response data.
 
@@ -415,7 +420,7 @@ def modify_before_deserialization(
         context: InterceptorContext[Request, None, TransportRequest, TransportResponse],
     ) -> TransportResponse:
         """
-        A hook called before the transport response is unmarshalled. This method has
+        A hook called before the transport response is deserialized. This method has
         the ability to modify and return a new transport response of the same type.
 
         This will always be called once per attempt, except when a failure occurs
@@ -444,7 +449,7 @@ def read_before_deserialization(
         context: InterceptorContext[Request, None, TransportRequest, TransportResponse],
     ) -> None:
         """
-        A hook called before the transport response is unmarshalled.
+        A hook called before the transport response is deserialized.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
@@ -453,7 +458,7 @@ def read_before_deserialization(
         earlier in the request pipeline. This method may be called multiple times in
         the event of retries. The duration between invocation of this hook and
         `read_after_deserialization` is very close to the amount of time spent
-        unmarshalling the service response. Depending on the protocol and operation,
+        deserializing the service response. Depending on the protocol and operation,
         the duration may include the time spent downloading the response data.
 
         The `request`, `transport_request`, and `transport_response` of the context
@@ -473,16 +478,16 @@ def read_after_deserialization(
         ],
     ) -> None:
         """
-        A hook called after the transport response is unmarshalled.
+        A hook called after the transport response is deserialized.
 
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
 
         This will always be called once per attempt, except when a failure occurs
         earlier in the request pipeline. This method may be called multiple times in
-        the event of retries. The duration between invocation of this hook and
-        `read_before_deserialization` is very close to the amount of time spent
-        unmarshalling the service response. Depending on the protocol and operation,
+        the event of retries. The duration between `read_before_deserialization`
+        and the invocation of this hook is very close to the amount of time spent
+        deserializing the service response. Depending on the protocol and operation,
         the duration may include the time spent downloading the response data.
 
         The `request`, `response`, `transport_request`, and `transport_response` of the
@@ -592,9 +597,9 @@ def read_after_execution(
         Implementations MUST NOT modify the `request`, `response`, `transport_request`,
         or `transport_response` in this hook.
 
-        This will always be called once per execution. The duration between invocation
-        of this hook and `read_before_execution` is very close to the full duration of
-        the execution.
+        This will always be called once per execution. The duration between
+        `read_before_execution` and the invocation of this hook is very close to the
+        full duration of the execution.
 
         The `request` and `response` of the context will always be available. The
         `transport_request` and `transport_response` will be available if the execution