feat(core): add PEP 702 __deprecated__ attribute support to @deprecated

[mdrxy]

Adds PEP 702 __deprecated__ attribute support to the @deprecated decorator, enabling IDE and type checker integration for deprecation warnings.

---

PEP 702 introduced the __deprecated__ attribute convention, which type checkers (Pyright, mypy) and IDEs (VS Code with Pylance, PyCharm) can use to surface deprecations directly in the editor. This PR sets __deprecated__ on all objects decorated with @deprecated.

With this change, developers using supported IDEs will see:

• Strikethrough text on deprecated symbols
• Hover messages showing the deprecation reason and suggested alternative
• Diagnostic warnings during type checking (e.g., pyright, mypy)

References

• PEP 702 – Marking deprecations using the type system
• typing.deprecated specification

[codspeed-hq]

CodSpeed Performance Report

Merging #34257 will not alter performance

_{Comparing mdrxy/improve-deprecated (91dac71) with master (ed9bd6e)}

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

Summary

✅ 13 untouched
⏩ 21 skipped¹

Footnotes

1. 21 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[Copilot]

Pull request overview

This PR adds PEP 702 __deprecated__ attribute support to the @deprecated decorator, enabling IDEs and type checkers (like Pyright and VS Code Pylance) to display deprecation warnings inline without requiring code execution. This improves the developer experience by showing strikethrough text and hover messages for deprecated APIs.

Key Changes:

• Added _build_deprecation_message() helper function to generate PEP 702-compliant deprecation messages
• Set __deprecated__ attribute on deprecated classes, properties, and functions/methods
• Messages include alternative APIs when specified via alternative or alternative_import parameters

[Copilot]

Same issue as lines 247-251: _alternative and _alternative_import have been modified to include markdown backticks before being passed to _build_deprecation_message. Use the original alternative and alternative_import parameters instead.