Rework the "Incomplete stubs" section

[srittau]

Also move it to the "Conventions" section due its scope change.

Closes: #8955

[AlexWaygood]

I feel sort-of neutral on this.

Most of our stubs these days are contributed using the create_baseline_stubs script. For stubs created using that script, there's indeed no reason to produce partial or incomplete stubs. The idea is to produce "low-quality but complete" stubs, and iterate on them in further PRs to slowly improve the quality.

But not all stubs contributions follow this process: our recently-contributed TensorFlow stubs, for example, are quite incomplete, but what has been contributed has been of a much higher quality than the stubs that create_baseline_stubs would autogenerate. The idea here is different: to produce "high-quality but incomplete" stubs, and iterate on them in further PRs to slowly work towards completion.

Is there a strong reason to forbid the second way of doing things?

[Avasam]

Is there a strong reason to forbid the second way of doing things?

In theory, anything missing can be filled in by stubgen. I've never tried it, but maybe pytype's merge-pyi could help. Although that's more something maintainers would care about, and could run afterward.

Idk if having to provide "stubtest complete" stubs could discourage a potential new contributor to add a new stub gets the feeling this will mean having to put in more work that what they thought they needed. Or if it increases the complexity of their initial stub due to stubtest quirks.

[hmc-cs-mdrissi]

I was assuming some libraries would be treated as exceptional cases. In tensorflow’s case using mypy’s stubgen on it last I tried it crashed. Also problematically tensorflow’s relies on heavy dynamic import patching so most classes/functions where they are defined is in an internal implementation detail and the public documented location is not what stubgen can generate. The last problem is tensorflow also uses a good amount of dynamic patching including for some core methods so my previous experience using pyright generated stubs, they were prone to false positives that my team had bad experience with them.

But at same time I think tensorflow is pretty weird case and most libraries generated stubs shouldn’t hit these issues. I wouldn’t design rules based on tensorflow and as long as special cases can still be allowed as needed this recommendation seems fine.

[AlexWaygood]

I was assuming some libraries would be treated as exceptional cases.

To be clear: I don't think anybody is proposing to lay down rules that can never be broken, so we almost certainly would still have accepted the TensorFlow stubs PR even if this PR had already been merged.

But that's very useful feedback about why you went about TensorFlow stubs the way you did, and makes me lean in favour of this PR being merged :)

[srittau]

Maybe it would be useful to just explain Incomplete and leave out all comments on incomplete stubs, like originally proposed in #8955.

---

Incomplete annotations

When submitting new stubs, it is not necessary to annotate all arguments, return types, and fields. Such items should either be left unannotated or use _typeshed.Incomplete if this is not possible:

from _typeshed import Incomplete

field: Incomplete  # unannotated 

def foo(x): ...  # unannotated argument and return type

Incomplete can also be used for partially known types:

def foo(x: Incomplete | None = None) -> list[Incomplete]: ...

Any vs. Incomplete

While Incomplete is a type alias of Any, they serve difference purposes: Incomplete is a placeholder where a proper type might be substituted. It's a "to do" item and should be replaced if possible. Any is used when it's not possible to accurately type an item using the current type system. It should be used sparingly.

[srittau]

So, any input by one of the co-maintainers? @JelleZijlstra @AlexWaygood @hauntsaninja @Akuli

I personally like the short version in my last comment.

[AlexWaygood]

Happy with either. @hmc-cs-mdrissi's comments about why he's doing TensorFlow stubs the way he is have resolved my prior concerns about the current wording. Your alternative also looks fine :)

[Akuli]

Good to see our conventions being documented :) A couple nits.

[srittau]

I have now substituted and concise version.