Support and render @deprecated with a strike through

[AaronFriel]

See: https://code.visualstudio.com/updates/v1_49#_deprecated-tag-support-for-javascript-and-typescript

Deprecated tag support for JavaScript and TypeScript

VS Code now supports the @deprecated JSDoc tag in JavaScript and TypeScript files. To mark an API as deprecated, simply add a @deprecated JSDoc comment:

It would be wonderful if this support worked with Pylance in some manner, either via a string in the docstring for a class or an @deprecated decorator.

[jakebailey]

Are there any standard formats for this in Python? There are quite a few documentation formats, and I'm aware of a number of different decorators for this (including many project-specific ones).

[erictraut]

I'm not aware of any standard way to mark a function, method or class as deprecated. There are a few third-party libraries that offer decorators:
https://pypi.org/project/Deprecated/
https://deprecation.readthedocs.io/en/latest/

I think there's value in supporting something like this, but it probably makes sense only if it is first standardized and included in stdlib, e.g. as part of the typing or functools modules. It loses most of its value if it's not standardized across the Python ecosystem because different tools (linters, type checkers, IDEs) will not work consistently, and there won't be much incentive for adoption within type stubs or libraries.

If you're passionate about this idea and want to champion it, I recommend posting a proposal to the typing-sig list.

[AaronFriel]

It seems to me that any decorator called deprecated should suffice, no? JSDoc is also not part of the EcmaScript standard.

I'm not suggesting anything more than supporting the same syntax highlighting that the TypeScript Language Server has when it detects a JSDoc comment of @deprecated. That's not part of the language spec, and it isn't part of the typings either. It has no impact on functionality. There's no need for other tools (linters, type checkers, IDEs) to know or understand that the text is struck through.

There would also be, I believe, no problem with supporting multiple formats or making it configurable. e.g.: have the language server take in deprecatedDecorators option which could contain a list of which decorators should apply that syntax highlighting, and/or a deprecatedCommentTokens which contains a list of tokens in a doc string to do the same.

I'm asking for language server support and syntax highlighting, not a change to types.

[jakebailey]

See also the discussion on microsoft/pyright#2300 and the (just posted) typing-sig thread: https://mail.python.org/archives/list/typing-sig@python.org/thread/E24WTMQUTGKPFKEXVCGGEFFMG7LDF3WT/

[yiannikolokythas]

@erictraut I will agree with @AaronFriel . All we need is @deprecated in the docstring similar to JS solution. This feature is very important in the case of autocomplete modules. We would like to be able to mark the deprecated functions so that the users have a good awareness (with the strike through interface) of what is deprecated.

[AaronFriel]

@erictraut based on the feedback in the thread, is there a reason this feature has to exist as a PEP within the Python organization and some sort of type-level feature? @deprecated is not part of the ECMAScript or TypeScript standard, it's purely a visual/IDE feature.

There are multiple libraries that seek to add some behavior and types or decorators to deprecate things. My suggestion would be: let a thousand flowers bloom and in the language server, support one or several of them, again, solely for the purpose of adding a visual strikethrough. No type checking change, purely visual. Let the decorator libraries do their thing until there's consensus or a PEP, but in the meantime, improve IDE tooling. After all, even if a PEP was approved adding a standard decorator and type annotation, how many years would it be until people stop using the other libraries out there?

To me, the suggestion that this needs to go through a PEP and committee process will hold back the Python language server. It adds an enormous amount of process for what could be more rapid iteration. See the rust-analyzer changelog for an example of a rapidly moving, improving language server: https://rust-analyzer.github.io/thisweek or the TypeScript language server: https://github.com/typescript-language-server/typescript-language-server/blob/master/CHANGELOG.md

As a hypothetical: if someone wanted to add inlay hints to Pyright/Pylance, would that require a PEP?

[erictraut]

Pyright is a standards-based type checker. We generally don't add any type-related functionality to it unless it is either in a standard or in the process of becoming a standard. So, to answer your hypothetical question, the answer is "yes, it would require a PEP". The approach of "letting a thousand flowers bloom" works well for libraries, but it falls apart quickly with programming language features.

My advice is for someone who feels strongly about this feature to champion a solution in the typing-sig or python-sig and start the path toward standardization. I'm willing to work with that person and do a reference implementation in pyright as part of the PEP review process.

[jakebailey]

As a hypothetical: if someone wanted to add inlay hints to Pyright/Pylance, would that require a PEP?

I feel like this is a bad comparison, as that is a feature that is fully dependent on the client (it's very close to hover and semantic tokens), whereas deprecation is both something that is visual but also would be exposed in something like a diagnostic that would ban deprecated items. This feature is here #1559, and we have experimented with it.

Pyright/pylance have the code to deprecate types like typing.Union (as | makes them obsolete, but also other things from typing), but have disabled them for now as it's very likely to be noisy for those upgrading to 3.10 but working with old code, and we'd need to very clearly provide docs as to how to disable deprecation diagnostics in VS Code in the editor and in completions and such.

I don't personally think we've eliminated implementing deprecation support without a PEP in Pylance (this issue is not closed!), but having a PEP for deprecation is a very welcomed case that benefits both editors and type checkers alike. Without it, we have to venture into the heuristics of all of the different ways every library and docstring format chooses to deprecate things.

[erictraut]

I agree with Jake that client-only language service features have a different bar for standardization. I may have misinterpreted what you meant by "inlay hints".

[AaronFriel]

whereas deprecation is both something that is visual but also would be exposed in something like a diagnostic that would ban deprecated items

This is not the perspective every language server implementation has applied. What I'm suggesting is narrower and purely client-only. Whether the @deprecated decorator, or other user-configurable decorator name, carries with it an implementation or is a no-op, the intention is clear and there is a clear benefit to displaying that identifier with a strikethrough.

The following 4 Python packages all define @deprecated:

• https://pypi.org/project/deprecate/
• https://pypi.org/project/deprecation/
• https://pypi.org/project/Python-Deprecated/
• https://pypi.org/project/Deprecated/

The intention is clear regardless of implementation.

[judej]

Moving this issue to discussion as an enhancement request for comments and upvotes.

[erictraut]

PEP 702 adds a standard way to mark classes, functions, and methods as deprecated. This PEP was just recently approved, and pyright and pylance support it. Use of a deprecated symbol will result in either a strike-through appearance or a diagnostic (if the reportDeprecated diagnostic check is enabled).