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

[mdrxy]

IDEs and type checkers that support PEP 702 (e.g., Pyright, VS Code Pylance) can now display deprecation warnings inline—showing strikethrough text and hover messages—without requiring code execution. Improves DX.

[codspeed-hq]

CodSpeed Performance Report

Merging #34257 will not alter performance

_{Comparing mdrxy/improve-deprecated (af9d07e) with master (8a5f463)¹}

⚠️ 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. No successful run was found on master (85012ae) during the generation of this report, so 8a5f463 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

2. 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]

The __deprecated__ attribute is being set with _alternative and _alternative_import values that have been modified to include markdown backticks (lines 389-401). This means the PEP 702 deprecation message shown in IDEs will contain backticks like "Use some_function instead."

PEP 702's __deprecated__ attribute is meant for display in IDEs and type checkers, not for documentation, so it should use plain text without markdown formatting. The _build_deprecation_message calls should use the original, unmodified values of alternative and alternative_import parameters from the outer scope, not _alternative and _alternative_import which have been wrapped in backticks.

Suggested change

	alternative=_alternative,
	alternative_import=_alternative_import,
	alternative=alternative,
	alternative_import=alternative_import,

[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.

[Copilot]

Same issue as lines 247-251 and 347-351: _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.

Suggested change

	alternative=_alternative,
	alternative_import=_alternative_import,
	alternative=alternative,
	alternative_import=alternative_import,

[Copilot]

The new __deprecated__ attribute functionality lacks test coverage. Tests should verify that:

1. The __deprecated__ attribute is set correctly on deprecated functions, classes, and properties
2. The attribute contains the expected message format (plain text without markdown backticks)
3. The attribute is set with the correct alternative/alternative_import values when provided

Example test:

def test_deprecated_function_has_pep702_attribute():
    @deprecated(since="2.0.0", alternative="new_function")
    def old_function():
        pass
    
    assert hasattr(old_function, '__deprecated__')
    assert old_function.__deprecated__ == "Use new_function instead."