diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 989966e0..2174cf0b 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/awsiot/iotidentity.py b/awsiot/iotidentity.py index 3b7f669b..7d16edc8 100644 --- a/awsiot/iotidentity.py +++ b/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 diff --git a/awsiot/iotjobs.py b/awsiot/iotjobs.py index 69a441de..d097855f 100644 --- a/awsiot/iotjobs.py +++ b/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. diff --git a/awsiot/iotshadow.py b/awsiot/iotshadow.py index 6721028c..248d12b3 100644 --- a/awsiot/iotshadow.py +++ b/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. diff --git a/awsiot/mqtt_connection_builder.py b/awsiot/mqtt_connection_builder.py index 33ce88d3..fb7a37b7 100644 --- a/awsiot/mqtt_connection_builder.py +++ b/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. diff --git a/awsiot/remove_me.py b/awsiot/remove_me.py new file mode 100644 index 00000000..3abdd618 --- /dev/null +++ b/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)