feat: add DeprecationWarning decorator support Python language

[amustaque97]

What does this PR do?

This PR introduces support for marking deprecated methods in the generated Python SDK using a custom decorator that emits a DeprecationWarning. The following changes are included:

• Added a deprecated decorator utility to the generated Python SDK (utils/deprecated.py).
• Ensured the utils package is always generated and included in the SDK output.
• Updated service templates to use the decorator for deprecated methods.
• Switched to absolute imports for robust package usage.
• Updated setup.py to use setuptools.find_packages() for correct subpackage inclusion.

This improves deprecation visibility for SDK users and ensures compatibility with Python packaging best practices.

(Provide a description of what this PR does.)

Test Plan

1. Generate the python package using command php example.php python client
2. Create a virtualenv based on the python version python3 -m venv venv
3. Activate virtualenv by running command . ./venv/bin/activate
4. Install locally generated package (step1), execute command: pip3 install examples/python --no-cache
5. Use below code snippet to test the functionality

from appwrite.client import Client
from appwrite.services.account import Account

# Initialize the Appwrite client
client = Client()
client.set_endpoint(
   <hostname_detail>/v1"
)  # Replace with your Appwrite endpoint
client.set_project("<project_id>")  # Replace with your project ID
# Initialize the Account service
account = Account(client)

# The user_id and secret should be obtained from the magic URL flow
user_id = "USER_ID_FROM_MAGIC_URL"
secret = "SECRET_FROM_MAGIC_URL"

# Call the deprecated update_magic_url_session method
try:
    session = account.update_magic_url_session(user_id, secret)
    print("Session created:", session)
except Exception as e:
    print("Error creating session:", e)

Save the above code in a file test.py and run command python3 test.py.

You will get output like below

test.py:19: DeprecationWarning: Call to deprecated function 'update_magic_url_session'. This API has been deprecated since 1.6.0. Please use `account.create_session` instead.

Screenshots
Python3.9

Python3.13

(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work.)

Related PRs and Issues

(If this PR is related to any other PR or resolves any issue or related to any issue link all related PR and issues here.)

Have you read the Contributing Guidelines on issues?

(Write your answer here.)

Summary by CodeRabbit

• New Features

  • Python SDK methods now include deprecation annotations that emit warnings and, when available, point to suggested replacements.
  • Deprecated methods surface clearer doc notes explaining deprecation status.

• Refactor

  • Packaging now uses automatic package discovery for the Python SDK.
  • Added a utilities package to support deprecation handling.

[coderabbitai]

Walkthrough

Adds two new generated files under the package utils: {{ spec.title | caseSnake}}/utils/deprecated.py and {{ spec.title | caseSnake}}/utils/\_\_init\_\_.py. Service code generation now imports deprecated and annotates deprecated methods with @deprecated(...), emitting conditional messages and corresponding reST deprecation notes. Introduces a deprecated(reason=None) utility that issues DeprecationWarning and supports both @deprecated and @deprecated("reason") usages. setup.py now uses setuptools.find_packages() for package discovery.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly conveys the primary change—adding DeprecationWarning decorator support for the Python SDK generator—and directly reflects the core functionality introduced without extraneous details.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch PLA-3382

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

templates/python/package/services/service.py.twig (1)

4-4: Prefer relative import for consistency.

This line uses an absolute import (appwrite.utils.deprecated) while other imports in the file (lines 1, 3, 9) use relative imports (..service, ..exception, ..input_file). Relative imports are more robust and consistent.

Apply this diff to use a relative import:

-from appwrite.utils.deprecated import deprecated
+from ..utils.deprecated import deprecated

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0721992 and 10764ee.

📒 Files selected for processing (5)

• src/SDK/Language/Python.php (1 hunks)
• templates/python/package/services/service.py.twig (2 hunks)
• templates/python/package/utils/__init__.py.twig (1 hunks)
• templates/python/package/utils/deprecated.py.twig (1 hunks)
• templates/python/setup.py.twig (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (18)

• GitHub Check: swift (server)
• GitHub Check: cli (console)
• GitHub Check: go (server)
• GitHub Check: dart (server)
• GitHub Check: ruby (server)
• GitHub Check: build (8.3, AppleSwift56)
• GitHub Check: apple (client)
• GitHub Check: android (client)
• GitHub Check: build (8.3, WebNode)
• GitHub Check: build (8.3, Swift56)
• GitHub Check: build (8.3, Python311)
• GitHub Check: build (8.3, Ruby27)
• GitHub Check: build (8.3, Ruby31)
• GitHub Check: build (8.3, Python310)
• GitHub Check: build (8.3, Python313)
• GitHub Check: build (8.3, KotlinJava8)
• GitHub Check: build (8.3, DotNet60)
• GitHub Check: build (8.3, Android5Java17)

🔇 Additional comments (6)

templates/python/package/utils/__init__.py.twig (1)

1-1: LGTM!

The __init__.py marker correctly designates the utils directory as a Python package.

templates/python/setup.py.twig (1)

10-10: LGTM!

Using find_packages() is the standard approach for automatic package discovery and will correctly include the new utils subpackage without requiring manual enumeration.

templates/python/package/utils/deprecated.py.twig (1)

42-49: LGTM!

The dual-mode support logic correctly handles both @deprecated (without arguments) and @deprecated("reason") (with a reason string) by detecting whether reason is callable.

src/SDK/Language/Python.php (1)

128-137: LGTM!

The new file generation entries for the utils package are correctly structured with appropriate scopes, destinations, and template references.

templates/python/package/services/service.py.twig (2)

43-49: LGTM!

The conditional decorator application correctly handles two cases:

• When both since and replaceWith are available, it provides a detailed message referencing the replacement method.
• Otherwise, it shows a generic deprecation message.

The logic is clean and appropriate.

---

56-64: LGTM!

The reST documentation blocks appropriately mirror the decorator usage, providing consistent deprecation notices in both the runtime warnings and the generated documentation.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

templates/python/package/utils/deprecated.py.twig (1)

32-41: Consider thread-safety implications of global filter manipulation.

The warnings filter is global state. If multiple threads concurrently call deprecated functions, their filter modifications could interleave (e.g., Thread A sets 'always', Thread B sets 'always', Thread A resets to 'default', Thread B emits warning with 'default' already active). In practice, the impact is minimal—worst case is a warning being suppressed or shown unexpectedly—but be aware that this is not thread-safe.

If thread-safety becomes a concern, you could use warnings.catch_warnings(record=True) as a context manager instead of manipulating the global filter. However, for deprecation warnings in an SDK, the current approach is acceptable.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 10764ee and 5585eb9.

📒 Files selected for processing (1)

• templates/python/package/utils/deprecated.py.twig (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (19)

• GitHub Check: build (8.3, Ruby27)
• GitHub Check: build (8.3, AppleSwift56)
• GitHub Check: build (8.3, Python310)
• GitHub Check: build (8.3, Python313)
• GitHub Check: build (8.3, Ruby31)
• GitHub Check: build (8.3, PHP80)
• GitHub Check: build (8.3, DotNet60)
• GitHub Check: build (8.3, Go118)
• GitHub Check: build (8.3, KotlinJava17)
• GitHub Check: build (8.3, Node18)
• GitHub Check: build (8.3, KotlinJava11)
• GitHub Check: build (8.3, DartStable)
• GitHub Check: build (8.3, Go112)
• GitHub Check: build (8.3, FlutterStable)
• GitHub Check: build (8.3, Android14Java17)
• GitHub Check: build (8.3, Android5Java17)
• GitHub Check: swift (server)
• GitHub Check: android (client)
• GitHub Check: apple (client)

🔇 Additional comments (3)

templates/python/package/utils/deprecated.py.twig (3)

30-42: Previous exception-safety issue has been resolved.

The try/finally block now ensures the warnings filter is correctly reset even when the wrapped function raises an exception. This addresses the critical issue from the previous review.

---

32-32: Comment clarification has been applied.

The inline comment now accurately describes that the filter is set to 'always' to show the warning every time, which is clearer than the previous "turn off filter" wording.

---

44-51: LGTM! Dual-use decorator pattern is correctly implemented.

The logic correctly handles both @deprecated and @deprecated("reason") usage by checking if reason is callable. This is a standard and well-tested pattern for Python decorators.