Consider deprecating `inspect.formatannotationrelativeto` and removing it in the future

Feature or enhancement

In https://github.com/python/cpython/issues/138729 we found that inspect.formatannotationrelativeto is not used in CPython anymore.

It also has several other problems:

• It does not match inspect.formatannotation's signature anymore. Since 3.14 formatannotation has quote_annotation_strings=True kw-only param
• It is not documented (in both Docs/ and does not even have a docstring)
• It was not tested before #138729

Will help your case with deprecation:

• It is very simple to copy-paste to any project that needs it

def formatannotationrelativeto(object):
    module = getattr(object, '__module__', None)
    def _formatannotation(annotation):
        return formatannotation(annotation, module)
    return _formatannotation

• It is not used anywhere except type definitions aka typeshed, I've searched top-5000 packages:

pypi/basedpyright-1.31.4.tar.gz: basedpyright-1.31.4/basedpyright/dist/typeshed-fallback/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/basedpyright-1.31.4.tar.gz: basedpyright-1.31.4/basedpyright/dist/typeshed-fallback/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/basedpyright-1.31.4.tar.gz: basedpyright-1.31.4/docstubs/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/basedpyright-1.31.4.tar.gz: basedpyright-1.31.4/docstubs/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/basedpyright-1.31.4.tar.gz: basedpyright-1.31.4/packages/pyright-internal/typeshed-fallback/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/basedpyright-1.31.4.tar.gz: basedpyright-1.31.4/packages/pyright-internal/typeshed-fallback/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/basedpyright-1.31.4.tar.gz: basedpyright-1.31.4/packages/pyright/dist/typeshed-fallback/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/basedpyright-1.31.4.tar.gz: basedpyright-1.31.4/packages/pyright/dist/typeshed-fallback/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/jedi-0.19.2.tar.gz: jedi-0.19.2/jedi/third_party/typeshed/stdlib/3/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/mypy-1.17.1.tar.gz: mypy-1.17.1/mypy/typeshed/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/mypy-1.17.1.tar.gz: mypy-1.17.1/mypy/typeshed/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/pyright-1.1.405.tar.gz: pyright-1.1.405/src/pyright/dist/dist/typeshed-fallback/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/pyright-1.1.405.tar.gz: pyright-1.1.405/src/pyright/dist/dist/typeshed-fallback/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/pytype-2024.10.11.tar.gz: pytype-2024.10.11/pytype/typeshed/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/pytype-2024.10.11.tar.gz: pytype-2024.10.11/pytype/typeshed/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/ruff-0.12.12.tar.gz: ruff-0.12.12/crates/ty_vendored/vendor/typeshed/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/ruff-0.12.12.tar.gz: ruff-0.12.12/crates/ty_vendored/vendor/typeshed/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/ty-0.0.1a20.tar.gz: ty-0.0.1a20/ruff/crates/ty_vendored/vendor/typeshed/stdlib/inspect.pyi: "formatannotationrelativeto",
pypi/ty-0.0.1a20.tar.gz: ty-0.0.1a20/ruff/crates/ty_vendored/vendor/typeshed/stdlib/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...
pypi/typeshed_client-2.8.2.tar.gz: typeshed_client-2.8.2/typeshed_client/typeshed/inspect.pyi: "formatannotationrelativeto",
pypi/typeshed_client-2.8.2.tar.gz: typeshed_client-2.8.2/typeshed_client/typeshed/inspect.pyi: def formatannotationrelativeto(object: object) -> Callable[[object], str]: ...

Proposal

I propose to deprecate this function in 3.15 and remove it in 3.17 as per our standart policy.

CC @JelleZijlstra and @serhiy-storchaka