Soft deprecation of MQTT 3.1.1 and V1 Service Clients

awscrt/common.py

@@ -1,8 +1,48 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0.
 """
 Cross-platform library for `awscrt`.
 """
+from typing import TYPE_CHECKING
 import _awscrt
 
+__all__ = [
+    "get_cpu_group_count",
+    "get_cpu_count_for_group",
+    "join_all_native_threads",
+    "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)
+
 
 def get_cpu_group_count() -> int:
     """

awscrt/mqtt.py

@@ -16,6 +16,7 @@
 from awscrt.io import ClientBootstrap, ClientTlsContext, SocketOptions
 from dataclasses import dataclass
 from awscrt.mqtt5 import Client as Mqtt5Client
+from awscrt.common import deprecated
 
 
 class QoS(IntEnum):
@@ -168,8 +169,22 @@ class OnConnectionClosedData:
     pass
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5.Client. 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")
 class Client(NativeResource):
-    """MQTT client.
+    """
+    Deprecated: We strongly recommend using mqtt5.Client. 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
+
+    MQTT client.
 
     Args:
         bootstrap (Optional [ClientBootstrap]): Client bootstrap to use when initiating new socket connections.
@@ -208,8 +223,22 @@ class OperationStatisticsData:
     unacked_operation_size: int = 0
 
 
+@deprecated(
+    """
+    We strongly recommend using mqtt5.Client. 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")
 class Connection(NativeResource):
-    """MQTT client connection.
+    """
+    Deprecated: We strongly recommend using mqtt5.Client. 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
+
+    MQTT client connection.
 
     Args:
         client (Client): MQTT client to spawn connection from.