warnings.deprecated should support instances as input

Feature or enhancement

Proposal:

i'm working on a library that allows to manage the life-cycle of deprecations

its using different warning types based on different contexts and is heavily relying on warnings.warn... supporting passing instances or strings

from deprecator import Deprecator

deprecator = Deprecator.for_package("my_package")

# depending on  the version of package and gone_in/warn_in this will be a PendingDeprecation, a Deprecation or a PassedDeprecation as defined in deprecator (Passed deprecations will auto register for triggering errors)


OLD_FEATURE = deprecator.define("Myfeature", warn_in="25.02.0", gone_in="26.05.0", repacement="new feature)


def my_code(...):
   warnings.warn(OLD_FEATURE)

i'd like to be able to do

@warnings.deprecated(OLD_FEATURE)
def my_code(...):
  ...

however currently warnings.deprecated is defined in terms that only allow a string

i'm aware of https://github.com/python/cpython/blob/fd8f42d3d1038a812340c3ec3cbfc995a80c4e13/Lib/_py_warnings.py#L817-L833 and intentional choose a new warning subclass to be registered for errors, as i want to ensure test suites can keep running with records of the issue instead of failures plus enable a work-flow where dead code removal happens after dysfunction sets in so that users have the possibility of a informed workaround while mitigating

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Start with Lib/_py_warnings.py lines 817-833, which define warnings.deprecated, and review how the decorator currently handles string inputs. Completion means the decorator also accepts warning instances while preserving existing behavior; verify the change with relevant warning tests.