[Design] Deprecation timing for Decorators: Definition-time vs. Call-time

[Borda]

Description

Context

pyDeprecate/tests/test_functions.py

Lines 3 to 16 in eda5c86

	TODO: Reconsider and/or refine the deprecation warning behavior for decorator syntax.
	When using @decorator syntax, the warning is currently raised at decoration time
	(during function/class definition or module import), not at call time.
	This might differ from the intended behavior if warnings should be raised at runtime.
	Consider whether the warning should be raised:
	1. Only once during import/decoration (current behavior)
	2. At every function call (runtime behavior)
	3. Once per function call location (hybrid approach)
	This could be a future improvement to make decorator deprecation more consistent
	with function/class deprecation patterns.
	Current test coverage:
	- TestDeprecatedFunctionWrappers.test_with_decorator_syntax (line ~348)
	- TestDeprecatedClassWrappers.test_with_decorator_syntax (line ~447)

This issue serves to formalize the design discussion regarding when a warning should be raised if the deprecated object is itself a decorator.

The Scenario

When a developer deprecates a decorator (e.g., @my_deprecated_wrapper) and a user applies it to their code:

@my_deprecated_wrapper  # <--- Should the warning fire here? (Definition/Import Time)
def my_function():
    pass

my_function()  # <--- Or should the warning fire here? (Runtime/Call Time)

The Design Decision

We need to determine the expected behavior for this specific use case:

1. Warn at Definition (Import Time):

   • Behavior: The warning is raised immediately when the Python interpreter processes the @decorator syntax.
   • Pro: Immediate feedback. The "usage" of the decorator technically happens at definition.
   • Con: Can be noisy during imports; harder to suppress via runtime flags if the function is never actually called.

2. Warn at Execution (Runtime/Call Time):

   • Behavior: The warning is delayed until the decorated function is actually invoked.
   • Pro: Consistent with standard function deprecation; avoids import-side effects.
   • Con: If the function is rarely called, the developer might not realize they are using a deprecated pattern until it is too late.

Action Items

• Collect Feedback: Gather user expectations on which behavior is less intrusive yet sufficiently visible.
• Gather Use Cases: Identify real-world scenarios where "Definition Time" warnings are critical versus where they might be a hindrance.
• Decide & Implement: Finalize the logic in pyDeprecate and update documentation.
• Cleanup: Remove the TODO note from tests/test_functions.py.

[uahroberto]

Hi @Borda

I would recommend raising the warning at Definition Time, treating the application of the decorator as the actual "usage" event. While dealing with import-time warnings can sometimes be perceived as noisy, the alternative presents a significant risk to system reliability

If we delay the warning until Execution Time, as you said: "the developer might not realize they are using a deprecated pattern until it is too late". Decorators are often used on specific, non-critical paths or error handlers that may not be invoked during standard development or testing loops. A runtime warning on such functions might go unnoticed for months, only to surface in production logs during a sensitive event or edge case. By that point, it is often too late to address the deprecation cleanly. Adopting a fail fast philosophy ensures that developers are aware of the deprecated usage immediately, regardless of how frequently the decorated function is called.

I also think that this approach maintains symmetry with the future removal of the feature. When the deprecated decorator is eventually deleted from the library, any code still using it will crash with a NameError or ImportError specifically at import time, not at call time. Therefore, the warning behavior today should mirror the failure state of tomorrow. Alerting the developer at the exact point where their code will eventually break provides the most honest and actionable signal for refactoring.