Merge typeshed style guide w/ official typing docs?

[yangdanny97]

I see that contributing.md has a style guide for stubs, which somewhat duplicates the documentation on Writing and Maintaining Stubs on the official typing docs.

Should we reduce duplication by linking to the latter from the former? There might be a few extra typeshed-specific things, but for general style stuff I don't see why we need to write it all out again here.

[JelleZijlstra]

Yes, we should point people to the typing docs, and only add typeshed-specific guidance where it's different from the general guide.

[srittau]

In fact, the current style guide from the typing docs was originally copied from typeshed. But due to the limbo that the stubs PEP – which ultimately became part of the docs – was in for a long time, the removal of the advice from the typeshed docs never happened. Most advice from CONTRIBUTING probably needs to be merged into the typing docs and then CONTRIBUTING needs slimming down.

[yangdanny97]

I can take a stab at merging these docs.

The instructions on how to handle disagreement between docs and implementation seems to differ between the two docs.

CONTRIBUTING.md says to follow the implementation over the docs, while the typing guide just says to use your best judgement about intent.

https://github.com/python/typeshed/blob/main/CONTRIBUTING.md#what-to-do-when-a-projects-documentation-and-implementation-disagree

https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#documentation-or-implementation

[yangdanny97]

For the other stuff, made a PR here: #1882

There are a few typeshed-specific sections that probably need to remain:

• Incomplete annotations
• Any vs Incomplete
• The Any trick

[yangdanny97]

The guide to remove docstrings for conciseness seems to conflict with Pyright's advice here: https://microsoft.github.io/pyright/#/typed-libraries?id=inlined-type-annotations-and-type-stubs

Not sure how/if we should align that.

[rchen152]

The instructions on how to handle disagreement between docs and implementation seems to differ between the two docs.

CONTRIBUTING.md says to follow the implementation over the docs, while the typing guide just says to use your best judgement about intent.

https://github.com/python/typeshed/blob/main/CONTRIBUTING.md#what-to-do-when-a-projects-documentation-and-implementation-disagree

https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#documentation-or-implementation

I think we should go with the recommendation in the writing_stubs guide. The language in typeshed's CONTRIBUTING.md comes from a commit in Dec 2016: python/typeshed@0843248. The recommendation in the guide is based on a more recent discussion and consensus from a stubs proto-PEP that was later merged into the guides: srittau/peps#41.

There are a few typeshed-specific sections that probably need to remain:

• Incomplete annotations
• Any vs Incomplete
• The Any trick

I think it would be fine to add these sections to the guide. There's already a bit about Incomplete here: https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#incomplete-stubs, and _typeshed.Incomplete and _typeshed.MaybeNone are both marked as stable.

The guide to remove docstrings for conciseness seems to conflict with Pyright's advice here: https://microsoft.github.io/pyright/#/typed-libraries?id=inlined-type-annotations-and-type-stubs

Not sure how/if we should align that.

I have mixed feelings on this. It feels wrong to me for docstrings to be in stubs (they're not types, they're whole blocks of text that are being duplicated and most certainly will go out-of-sync with the source), but the language server use case is pretty compelling. IMO the easiest way out would be to just stick with the status quo: nothing about docstrings in the guide, typeshed continues to have a typeshed-specific rule.

[JelleZijlstra]

I have mixed feelings on this. It feels wrong to me for docstrings to be in stubs (they're not types, they're whole blocks of text that are being duplicated and most certainly will go out-of-sync with the source), but the language server use case is pretty compelling. IMO the easiest way out would be to just stick with the status quo: nothing about docstrings in the guide, typeshed continues to have a typeshed-specific rule.

Relevant typeshed issue: python/typeshed#4881. I think the typeshed project can make the decision on whether or not to include docstrings in typeshed, but the general guide could have information about the tradeoffs related to adding docstrings. (Some things to include: type checkers will ignore them; docstrings are helpful for IDEs; consider the maintenance cost of duplicating docstrings in stubs.)