Issue title reflects just how long-term this might be… As of 2023-11-11, a new warnings.deprecated decorator is "Accepted" (via PEP 702) but not yet fully implemented in Python 3.13 alpha (see python/cpython#104004). The final release of Python 3.13.0 isn't expected until next October (2024), so this is definitely a planning issue for now. I just want to make sure it isn't forgotten.
We've had occasional conversations about improvements to Sopel's own @deprecated decorator—including a possible switch to use warnings instead of the normal logger—for a few years now. This upcoming stdlib feature can give us both a runtime warning and a type-checker warning, and it looks like our existing decorator should be able to simply wrap this:
message argument (positional-only) is built by our @deprecated decorator based on its optional arguments
category argument (keyword-only) can be warnings.PendingDeprecationWarning (ignored by default) before the warning_in version has been reached, and warnings.DeprecationWarning after
stacklevel argument (keyword-only) should be abs(stack_frame) if I understand the upstream implementation correctly
Our decorator's stack_frame argument is expected to be negative due to an implementation detail; it's used to truncate the stack trace, which is basically the same as the "skipping" of stack frames that stacklevel does.
Yes, we should consider formally updating this argument so that it takes the same (positive) value as the stdlib decorator would, just so it'll be less confusing for people who hop between multiple codebases.
@deprecated is available as an experimental decorator since typing-extensions 4.5.0, and will most likely be updated with a stdlib-compatible, non-experimental implementation by the time Python 3.13.0 is finalized, if not even before then. We'll be able to use that for our own backward compatibility purposes.
Issue title reflects just how long-term this might be… As of 2023-11-11, a new
warnings.deprecateddecorator is "Accepted" (via PEP 702) but not yet fully implemented in Python 3.13 alpha (see python/cpython#104004). The final release of Python 3.13.0 isn't expected until next October (2024), so this is definitely a planning issue for now. I just want to make sure it isn't forgotten.We've had occasional conversations about improvements to Sopel's own
@deprecateddecorator—including a possible switch to usewarningsinstead of the normal logger—for a few years now. This upcoming stdlib feature can give us both a runtime warning and a type-checker warning, and it looks like our existing decorator should be able to simply wrap this:messageargument (positional-only) is built by our@deprecateddecorator based on its optional argumentscategoryargument (keyword-only) can bewarnings.PendingDeprecationWarning(ignored by default) before thewarning_inversion has been reached, andwarnings.DeprecationWarningafterstacklevelargument (keyword-only) should beabs(stack_frame)if I understand the upstream implementation correctlystack_frameargument is expected to be negative due to an implementation detail; it's used to truncate the stack trace, which is basically the same as the "skipping" of stack frames thatstackleveldoes.@deprecatedis available as an experimental decorator sincetyping-extensions4.5.0, and will most likely be updated with a stdlib-compatible, non-experimental implementation by the time Python 3.13.0 is finalized, if not even before then. We'll be able to use that for our own backward compatibility purposes.