Merge pull request #1215 from appwrite/PLA-3382

feat: add `DeprecationWarning` decorator support Python language

Author: amustaque97

src/SDK/Language/Python.php

@@ -125,6 +125,16 @@ public function getFiles(): array
                 'destination' => '{{ spec.title | caseSnake}}/__init__.py',
                 'template' => 'python/package/__init__.py.twig',
             ],
+            [
+                'scope' => 'default',
+                'destination' => '{{ spec.title | caseSnake}}/utils/deprecated.py',
+                'template' => 'python/package/utils/deprecated.py.twig',
+            ],
+            [
+                'scope' => 'default',
+                'destination' => '{{ spec.title | caseSnake}}/utils/__init__.py',
+                'template' => 'python/package/utils/__init__.py.twig',
+            ],
             [
                 'scope' => 'default',
                 'destination' => '{{ spec.title | caseSnake}}/client.py',

templates/python/package/services/service.py.twig

@@ -1,6 +1,7 @@
 from ..service import Service
 from typing import List, Dict, Any
 from ..exception import AppwriteException
+from appwrite.utils.deprecated import deprecated
 {% set added = [] %}
 {% for method in service.methods %}
 {% for parameter in method.parameters.all %}
@@ -39,6 +40,13 @@ class {{ service.name | caseUcfirst }}(Service):
 {% endif %}
 {% if not shouldSkip %}
 
+{% if method.deprecated %}
+{% if method.since and method.replaceWith %}
+    @deprecated("This API has been deprecated since {{ method.since }}. Please use `{{ method.replaceWith | caseSnakeExceptFirstDot }}` instead.")
+{% else %}
+    @deprecated("This API has been deprecated.")
+{% endif %}
+{% endif %}
     def {{ method.name | caseSnake }}(self{% if method.parameters.all|length > 0 %}, {% endif %}{% for parameter in method.parameters.all %}{{ parameter.name | escapeKeyword | caseSnake }}: {{ parameter | getPropertyType(method) | raw }}{% if not parameter.required %} = None{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}{% if 'multipart/form-data' in method.consumes %}, on_progress = None{% endif %}) -> {% if method.type == 'webAuth' %}str{% elseif method.type == 'location' %}bytes{% else %}Dict[str, Any]{% endif %}:
         """
         {% autoescape false %}{{ method.description | replace({"\n": "\n        "}) }}{% endautoescape %}

templates/python/package/utils/__init__.py.twig

@@ -0,0 +1 @@
+# This file makes the 'utils' directory a Python package.

templates/python/package/utils/deprecated.py.twig

@@ -0,0 +1,51 @@
+"""
+A decorator to mark functions as deprecated.
+
+When the function is called, a DeprecationWarning is emitted.
+Compatible with Python 2.7+ and Python 3.x.
+"""
+
+import functools
+import warnings
+
+def deprecated(reason=None):
+    """
+    Decorator to mark functions as deprecated.
+    Emits a DeprecationWarning when the function is called.
+
+    Args:
+        reason (str, optional): Reason for deprecation. Defaults to None.
+
+    Usage:
+        @deprecated("Use another_function instead.")
+        def old_function(...):
+            ...
+    """
+    def decorator(func):
+        message = "Call to deprecated function '{}'.{}".format(
+            func.__name__,
+            " " + reason if reason else ""
+        )
+
+        @functools.wraps(func)
+        def wrapped(*args, **kwargs):
+            warnings.simplefilter('always', DeprecationWarning) # show warning every time
+            try:
+                warnings.warn(
+                    message,
+                    category=DeprecationWarning,
+                    stacklevel=2
+                )
+                return func(*args, **kwargs)
+            finally:
+                warnings.simplefilter('default', DeprecationWarning)  # reset filter
+        return wrapped
+
+    # Support both @deprecated and @deprecated("reason")
+    if callable(reason):
+        # Used as @deprecated without arguments
+        func = reason
+        reason = None
+        return decorator(func)
+    else:
+        return decorator

templates/python/setup.py.twig

@@ -4,15 +4,10 @@ long_description: str
 
 with open("README.md", "r", encoding="utf-8") as readme_file_desc:
     long_description = readme_file_desc.read()
-    
+
 setuptools.setup(
   name = '{{spec.title | caseSnake}}',
-  packages = [
-    '{{spec.title | caseSnake}}',
-    '{{spec.title | caseSnake}}/services',
-    '{{spec.title | caseSnake}}/encoders',
-    '{{spec.title | caseSnake}}/enums',
-  ],
+  packages = setuptools.find_packages(),
   version = '{{sdk.version}}',
   license='{{spec.licenseName}}',
   description = '{{sdk.shortDescription}}',