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

[sobolevn]

Feature or enhancement

In #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 inspect.formatannotationrelativeto is not tested #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

[JelleZijlstra]

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

PEP 387 now prefers waiting at least five years

It is preferred, though, to wait 5 years before removal (e.g., warn starting in Python 3.10, removal in 3.15; this happens to coincide with the current lifetime of a minor release of Python).

Since there is little cost for keeping this function around, I'd prefer to wait longer.

[sobolevn]

Ok, let's wait 5 years, this also works :)

[serhiy-storchaka]

Note also that the base_module argument is never passed to formatannotation() in the stdlib (and it was not tested before #138729). That argument may not actually work in many cases. So we should consider deprecating it too. Is it used outside of the stdlib?

formatannotation() itself is only used internally in the inspect module, not documented, and poorly directly tested.

[JelleZijlstra]

Maybe we should consider moving to a private _formatannotation function for the internal use case, and also deprecate the public formatannotation function?

[serhiy-storchaka]

These functions were added in 2e65f89 (bpo-1607548/gh-44297) for use in formatargspec() (removed in 2021, bpo-45320). They were added to __all__ in 810c176 (bpo-27062/gh-71249).

formatannotationrelativeto() and the second argument of formatannotation() were never used.