Soft Deprecation

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
       - 'docs'
 
 env:
-  BUILDER_VERSION: v0.9.84
+  BUILDER_VERSION: v0.9.87
   BUILDER_SOURCE: releases
   BUILDER_HOST: https://d19elf31gohf1l.cloudfront.net
   PACKAGE_NAME: aws-iot-device-sdk-python-v2

awsiot/iotidentity.py

@@ -9,8 +9,20 @@
 import json
 import typing
 
+from .remove_me import deprecated
+# from awscrt.common import deprecated
+
+@deprecated(
+    """
+    We strongly recommend using IotIdentityClientV2. There are no current plans to
+    fully deprecate IotIdentityClient but it is highly recommended customers migrate to IotIdentityClientV2.
+    More details can be found in the GitHub Repo FAQ
+    """)
 class IotIdentityClient(awsiot.MqttServiceClient):
     """
+    Deprecated: We strongly recommend using IotIdentityClientV2. There are no current plans to
+    fully deprecate IotIdentityClient but it is highly recommended customers migrate to IotIdentityClientV2.
+    More details can be found in the GitHub Repo FAQ
 
     An AWS IoT service that assists with provisioning a device and installing unique client certificates on it
 

awsiot/iotjobs.py

@@ -11,8 +11,20 @@
 import typing
 import uuid
 
+from .remove_me import deprecated
+# from awscrt.common import deprecated
+
+@deprecated(
+    """
+    We strongly recommend using IotJobsClientV2. There are no current plans to
+    fully deprecate IotJobsClient but it is highly recommended customers migrate to IotJobsClientV2.
+    More details can be found in the GitHub Repo FAQ
+    """)
 class IotJobsClient(awsiot.MqttServiceClient):
     """
+    Deprecated: We strongly recommend using IotJobsClientV2. There are no current plans to
+    fully deprecate IotJobsClient but it is highly recommended customers migrate to IotJobsClientV2.
+    More details can be found in the GitHub Repo FAQ
 
     The AWS IoT jobs service can be used to define a set of remote operations that are sent to and executed on one or more devices connected to AWS IoT.
 

awsiot/iotshadow.py

@@ -11,8 +11,20 @@
 import typing
 import uuid
 
+from .remove_me import deprecated
+# from awscrt.common import deprecated
+
+@deprecated(
+    """
+    We strongly recommend using IotShadowClientV2. There are no current plans to
+    fully deprecate IotShadowClient but it is highly recommended customers migrate to IotShadowClientV2.
+    More details can be found in the GitHub Repo FAQ
+    """)
 class IotShadowClient(awsiot.MqttServiceClient):
     """
+    Deprecated: We strongly recommend using IotShadowClientV2. There are no current plans to
+    fully deprecate IotShadowClient but it is highly recommended customers migrate to IotShadowClientV2.
+    More details can be found in the GitHub Repo FAQ
 
     The AWS IoT Device Shadow service adds shadows to AWS IoT thing objects. Shadows are a simple data store for device properties and state.  Shadows can make a device’s state available to apps and other services whether the device is connected to AWS IoT or not.
 

awsiot/mqtt_connection_builder.py

@@ -124,6 +124,9 @@
 import awscrt.io
 import awscrt.mqtt
 import urllib.parse
+from .remove_me import deprecated
+# from awscrt.common import deprecated
+
 
 
 def _check_required_kwargs(**kwargs):
@@ -258,6 +261,14 @@ def _builder(
     )
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def mtls_from_path(cert_filepath, pri_key_filepath, **kwargs) -> awscrt.mqtt.Connection:
     """
     This builder creates an :class:`awscrt.mqtt.Connection`, configured for an mTLS MQTT connection to AWS IoT.
@@ -276,6 +287,14 @@ def mtls_from_path(cert_filepath, pri_key_filepath, **kwargs) -> awscrt.mqtt.Con
     return _builder(tls_ctx_options, **kwargs)
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def mtls_from_bytes(cert_bytes, pri_key_bytes, **kwargs) -> awscrt.mqtt.Connection:
     """
     This builder creates an :class:`awscrt.mqtt.Connection`, configured for an mTLS MQTT connection to AWS IoT.
@@ -294,6 +313,14 @@ def mtls_from_bytes(cert_bytes, pri_key_bytes, **kwargs) -> awscrt.mqtt.Connecti
     return _builder(tls_ctx_options, **kwargs)
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def mtls_with_pkcs11(*,
                      pkcs11_lib: awscrt.io.Pkcs11Lib,
                      user_pin: str,
@@ -350,6 +377,15 @@ def mtls_with_pkcs11(*,
 
     return _builder(tls_ctx_options, **kwargs)
 
+
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def mtls_with_pkcs12(*,
                      pkcs12_filepath: str,
                      pkcs12_password: str,
@@ -376,6 +412,14 @@ def mtls_with_pkcs12(*,
     return _builder(tls_ctx_options, **kwargs)
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def mtls_with_windows_cert_store_path(*,
                                       cert_store_path: str,
                                       **kwargs) -> awscrt.mqtt.Connection:
@@ -400,6 +444,14 @@ def mtls_with_windows_cert_store_path(*,
     return _builder(tls_ctx_options, **kwargs)
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def websockets_with_default_aws_signing(
         region,
         credentials_provider,
@@ -444,6 +496,14 @@ def _sign_websocket_handshake_request(transform_args, **kwargs):
     return websockets_with_custom_handshake(_sign_websocket_handshake_request, websocket_proxy_options, **kwargs)
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def websockets_with_custom_handshake(
         websocket_handshake_transform,
         websocket_proxy_options=None,
@@ -498,6 +558,14 @@ def _add_to_username_parameter(input_string, parameter_value, parameter_pretext)
         return return_string + parameter_pretext + parameter_value
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def direct_with_custom_authorizer(
         auth_username=None,
         auth_authorizer_name=None,
@@ -552,6 +620,15 @@ def direct_with_custom_authorizer(
         use_websockets=False,
         **kwargs)
 
+
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def websockets_with_custom_authorizer(
         region=None,
         credentials_provider=None,
@@ -615,6 +692,14 @@ def websockets_with_custom_authorizer(
         **kwargs)
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def _with_custom_authorizer(auth_username=None,
         auth_authorizer_name=None,
         auth_authorizer_signature=None,
@@ -675,6 +760,14 @@ def _sign_websocket_handshake_request(transform_args, **kwargs):
                     **kwargs)
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5_client_builder. There are no current plans to fully deprecate
+    the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to access
+    a more robust feature set, clearer error handling, and lifetime management. More details can be found
+    in the GitHub Repo FAQ
+    """,
+    since="9.9.9")
 def new_default_builder(**kwargs) -> awscrt.mqtt.Connection:
     """
     This builder creates an :class:`awscrt.mqtt.Connection`, without any configuration besides the default TLS context options.

awsiot/remove_me.py

@@ -0,0 +1,41 @@
+# TEMPORARY WIP FILE TO USE IN PLACE OF NON-ACCESSIBLE common.py from awscrt until a version is cut.
+# DELETE THIS FILE and point to the correct location after crt has released a version with soft deprecation
+
+"""
+Cross-platform library for `awscrt`.
+"""
+from typing import TYPE_CHECKING
+
+__all__ = [
+    "deprecated",
+]
+
+# At type-check time, expose a real symbol so linters/IDEs understand it.
+# At runtime, prefer typing_extensions; fall back to typing (Py3.13+); else no-op.
+if TYPE_CHECKING:
+    # Static analysers will always attempt to import deprecated from typing_extensions and
+    # fall back to known interpretation of `deprecated` if it fails and appropriately handle
+    # the `@deprecated` tags.
+    from typing_extensions import deprecated as deprecated
+else:
+    _deprecated_impl = None
+    try:
+        # preferred import of deprecated
+        from typing_extensions import deprecated as _deprecated_impl
+    except Exception:
+        try:
+            from typing import deprecated as _deprecated_impl  # Python 3.13+
+        except Exception:
+            _deprecated_impl = None
+
+    def deprecated(msg=None, *, since=None):
+        if _deprecated_impl is None:
+            def _noop(obj): return obj
+            return _noop
+        if since is not None:
+            try:
+                return _deprecated_impl(msg, since=since)
+            except TypeError:
+                # older typing_extensions doesn't support the 'since' kwarg
+                pass
+        return _deprecated_impl(msg)