Documentation updates

awsiot/__init__.py

@@ -200,7 +200,15 @@ def __repr__(self):
 
 
 class V2ServiceException(Exception):
+    """
+    Wrapper exception thrown by V2 service clients to indicate the failure of an operation
 
+    Args:
+        message (str): Description of the failure.
+        inner_error (Optional[Exception]): Cause of the failure.
+        modeled_error (Optional[Any]): Modeled error shape that contains additional information about the failure.
+            The modeled type is specific to each individual service operation.
+    """
     def __init__(self, message: str, inner_error: 'Optional[Exception]', modeled_error: 'Optional[Any]'):
         self.message = message
         self.inner_error = inner_error
@@ -233,6 +241,14 @@ def complete_modeled_future(unmodeled_future):
     return modeled_future
 
 class V2DeserializationFailure(Exception):
+    """
+    An exception raised when deserialization from an MQTT message payload to a modeled type fails
+
+    Args:
+        message (str): description of the failure
+        inner_error (Optional[Exception]): the underlying deserialization exception
+        payload (Optional[bytes]): original MQTT message payload that could not be deserialized properly
+    """
     def __init__(self, message: str, inner_error: 'Optional[Exception]', payload: Optional[bytes]):
         self.message = message
         self.inner_error = inner_error

awsiot/iotidentity.py

@@ -709,10 +709,11 @@ def create_certificate_from_csr(self, request : CreateCertificateFromCsrRequest)
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html#fleet-provision-api
 
         Args:
-            request: `CreateCertificateFromCsrRequest` instance.
+            request (CreateCertificateFromCsrRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `CreateCertificateFromCsrResponse`.
+            A Future whose result will be an instance of :class:`CreateCertificateFromCsrResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -752,10 +753,11 @@ def create_keys_and_certificate(self, request : CreateKeysAndCertificateRequest)
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html#fleet-provision-api
 
         Args:
-            request: `CreateKeysAndCertificateRequest` instance.
+            request (CreateKeysAndCertificateRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `CreateKeysAndCertificateResponse`.
+            A Future whose result will be an instance of :class:`CreateKeysAndCertificateResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -795,10 +797,11 @@ def register_thing(self, request : RegisterThingRequest) -> concurrent.futures.F
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html#fleet-provision-api
 
         Args:
-            request: `RegisterThingRequest` instance.
+            request (RegisterThingRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `RegisterThingResponse`.
+            A Future whose result will be an instance of :class:`RegisterThingResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 

awsiot/iotjobs.py

@@ -1561,10 +1561,11 @@ def describe_job_execution(self, request : DescribeJobExecutionRequest) -> concu
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-describejobexecution
 
         Args:
-            request: `DescribeJobExecutionRequest` instance.
+            request (DescribeJobExecutionRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `DescribeJobExecutionResponse`.
+            A Future whose result will be an instance of :class:`DescribeJobExecutionResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -1608,10 +1609,11 @@ def get_pending_job_executions(self, request : GetPendingJobExecutionsRequest) -
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-getpendingjobexecutions
 
         Args:
-            request: `GetPendingJobExecutionsRequest` instance.
+            request (GetPendingJobExecutionsRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `GetPendingJobExecutionsResponse`.
+            A Future whose result will be an instance of :class:`GetPendingJobExecutionsResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -1655,10 +1657,11 @@ def start_next_pending_job_execution(self, request : StartNextPendingJobExecutio
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-startnextpendingjobexecution
 
         Args:
-            request: `StartNextPendingJobExecutionRequest` instance.
+            request (StartNextPendingJobExecutionRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `StartNextJobExecutionResponse`.
+            A Future whose result will be an instance of :class:`StartNextJobExecutionResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -1702,10 +1705,11 @@ def update_job_execution(self, request : UpdateJobExecutionRequest) -> concurren
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-updatejobexecution
 
         Args:
-            request: `UpdateJobExecutionRequest` instance.
+            request (UpdateJobExecutionRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `UpdateJobExecutionResponse`.
+            A Future whose result will be an instance of :class:`UpdateJobExecutionResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -1749,8 +1753,8 @@ def create_job_executions_changed_stream(self, request : JobExecutionsChangedSub
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-jobexecutionschanged
 
         Args:
-            request: `JobExecutionsChangedSubscriptionRequest` instance.
-            options: callbacks to invoke for streaming operation events
+            request (JobExecutionsChangedSubscriptionRequest): configuration for the streaming operation to create
+            options (awsiot.ServiceStreamOptions[JobExecutionsChangedEvent]): callbacks to invoke for streaming operation events
 
         Returns:
             An instance of `awscrt.mqtt_request_response.StreamingOperation`
@@ -1770,8 +1774,8 @@ def create_next_job_execution_changed_stream(self, request : NextJobExecutionCha
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/jobs-api.html#mqtt-nextjobexecutionchanged
 
         Args:
-            request: `NextJobExecutionChangedSubscriptionRequest` instance.
-            options: callbacks to invoke for streaming operation events
+            request (NextJobExecutionChangedSubscriptionRequest): configuration for the streaming operation to create
+            options (awsiot.ServiceStreamOptions[NextJobExecutionChangedEvent]): callbacks to invoke for streaming operation events
 
         Returns:
             An instance of `awscrt.mqtt_request_response.StreamingOperation`

awsiot/iotshadow.py

@@ -1161,6 +1161,11 @@ def __init__(self, *args, **kwargs):
         for key, val in zip(['shadow_name', 'thing_name'], args):
             setattr(self, key, val)
 
+    def to_payload(self):
+        # type: () -> typing.Dict[str, typing.Any]
+        payload = {} # type: typing.Dict[str, typing.Any]
+        return payload
+
     def _validate(self):
         if not self.shadow_name:
             raise ValueError("shadow_name is required")
@@ -1194,6 +1199,11 @@ def __init__(self, *args, **kwargs):
         for key, val in zip(['shadow_name', 'thing_name'], args):
             setattr(self, key, val)
 
+    def to_payload(self):
+        # type: () -> typing.Dict[str, typing.Any]
+        payload = {} # type: typing.Dict[str, typing.Any]
+        return payload
+
     def _validate(self):
         if not self.shadow_name:
             raise ValueError("shadow_name is required")
@@ -1283,6 +1293,11 @@ def __init__(self, *args, **kwargs):
         for key, val in zip(['thing_name'], args):
             setattr(self, key, val)
 
+    def to_payload(self):
+        # type: () -> typing.Dict[str, typing.Any]
+        payload = {} # type: typing.Dict[str, typing.Any]
+        return payload
+
     def _validate(self):
         if not self.thing_name:
             raise ValueError("thing_name is required")
@@ -1558,6 +1573,11 @@ def __init__(self, *args, **kwargs):
         for key, val in zip(['thing_name'], args):
             setattr(self, key, val)
 
+    def to_payload(self):
+        # type: () -> typing.Dict[str, typing.Any]
+        payload = {} # type: typing.Dict[str, typing.Any]
+        return payload
+
     def _validate(self):
         if not self.thing_name:
             raise ValueError("thing_name is required")
@@ -1857,10 +1877,11 @@ def delete_named_shadow(self, request : DeleteNamedShadowRequest) -> concurrent.
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#delete-pub-sub-topic
 
         Args:
-            request: `DeleteNamedShadowRequest` instance.
+            request (DeleteNamedShadowRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `DeleteShadowResponse`.
+            A Future whose result will be an instance of :class:`DeleteShadowResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -1904,10 +1925,11 @@ def delete_shadow(self, request : DeleteShadowRequest) -> concurrent.futures.Fut
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#delete-pub-sub-topic
 
         Args:
-            request: `DeleteShadowRequest` instance.
+            request (DeleteShadowRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `DeleteShadowResponse`.
+            A Future whose result will be an instance of :class:`DeleteShadowResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -1951,10 +1973,11 @@ def get_named_shadow(self, request : GetNamedShadowRequest) -> concurrent.future
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#get-pub-sub-topic
 
         Args:
-            request: `GetNamedShadowRequest` instance.
+            request (GetNamedShadowRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `GetShadowResponse`.
+            A Future whose result will be an instance of :class:`GetShadowResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -1998,10 +2021,11 @@ def get_shadow(self, request : GetShadowRequest) -> concurrent.futures.Future :
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#get-pub-sub-topic
 
         Args:
-            request: `GetShadowRequest` instance.
+            request (GetShadowRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `GetShadowResponse`.
+            A Future whose result will be an instance of :class:`GetShadowResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -2045,10 +2069,11 @@ def update_named_shadow(self, request : UpdateNamedShadowRequest) -> concurrent.
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#update-pub-sub-topic
 
         Args:
-            request: `UpdateNamedShadowRequest` instance.
+            request (UpdateNamedShadowRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `UpdateShadowResponse`.
+            A Future whose result will be an instance of :class:`UpdateShadowResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -2094,10 +2119,11 @@ def update_shadow(self, request : UpdateShadowRequest) -> concurrent.futures.Fut
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#update-pub-sub-topic
 
         Args:
-            request: `UpdateShadowRequest` instance.
+            request (UpdateShadowRequest): information about the operation to perform.
 
         Returns:
-            A Future whose result will be an instance of `UpdateShadowResponse`.
+            A Future whose result will be an instance of :class:`UpdateShadowResponse`.  If the
+            operation fails, the future will be completed with a :class:`awsiot.V2ServiceException` exception.
         """
         request._validate()
 
@@ -2143,8 +2169,8 @@ def create_named_shadow_delta_updated_stream(self, request : NamedShadowDeltaUpd
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#update-delta-pub-sub-topic
 
         Args:
-            request: `NamedShadowDeltaUpdatedSubscriptionRequest` instance.
-            options: callbacks to invoke for streaming operation events
+            request (NamedShadowDeltaUpdatedSubscriptionRequest): configuration for the streaming operation to create
+            options (awsiot.ServiceStreamOptions[ShadowDeltaUpdatedEvent]): callbacks to invoke for streaming operation events
 
         Returns:
             An instance of `awscrt.mqtt_request_response.StreamingOperation`
@@ -2166,8 +2192,8 @@ def create_named_shadow_updated_stream(self, request : NamedShadowUpdatedSubscri
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#update-documents-pub-sub-topic
 
         Args:
-            request: `NamedShadowUpdatedSubscriptionRequest` instance.
-            options: callbacks to invoke for streaming operation events
+            request (NamedShadowUpdatedSubscriptionRequest): configuration for the streaming operation to create
+            options (awsiot.ServiceStreamOptions[ShadowUpdatedEvent]): callbacks to invoke for streaming operation events
 
         Returns:
             An instance of `awscrt.mqtt_request_response.StreamingOperation`
@@ -2189,8 +2215,8 @@ def create_shadow_delta_updated_stream(self, request : ShadowDeltaUpdatedSubscri
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#update-delta-pub-sub-topic
 
         Args:
-            request: `ShadowDeltaUpdatedSubscriptionRequest` instance.
-            options: callbacks to invoke for streaming operation events
+            request (ShadowDeltaUpdatedSubscriptionRequest): configuration for the streaming operation to create
+            options (awsiot.ServiceStreamOptions[ShadowDeltaUpdatedEvent]): callbacks to invoke for streaming operation events
 
         Returns:
             An instance of `awscrt.mqtt_request_response.StreamingOperation`
@@ -2212,8 +2238,8 @@ def create_shadow_updated_stream(self, request : ShadowUpdatedSubscriptionReques
         API Docs: https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-mqtt.html#update-documents-pub-sub-topic
 
         Args:
-            request: `ShadowUpdatedSubscriptionRequest` instance.
-            options: callbacks to invoke for streaming operation events
+            request (ShadowUpdatedSubscriptionRequest): configuration for the streaming operation to create
+            options (awsiot.ServiceStreamOptions[ShadowUpdatedEvent]): callbacks to invoke for streaming operation events
 
         Returns:
             An instance of `awscrt.mqtt_request_response.StreamingOperation`

samples/fleet_provisioning_basic.md

@@ -75,7 +75,7 @@ If the venv does not yet have the device SDK installed, install it:
 python3 -m pip install awsiotsdk
 ```
 
-Assuming you are in the SDK root directory, you can now run the shadow sandbox sample:
+Assuming you are in the SDK root directory, you can now run the basic fleet provisioning sample:
 
 ``` sh
 # from the samples folder

samples/fleet_provisioning_csr.md

@@ -76,7 +76,7 @@ If the venv does not yet have the device SDK installed, install it:
 python3 -m pip install awsiotsdk
 ```
 
-Assuming you are in the SDK root directory, you can now run the shadow sandbox sample:
+Assuming you are in the SDK root directory, you can now run the CSR fleet provisioning sample:
 
 ``` sh
 python3 samples/fleet_provisioning_csr.py --endpoint <endpoint> --cert <file> --key <file> --csr_file <file> --template_name <template name> --template_parameters <template parameters>