Editing for the tomllib PEP

[encukou]

• title: I'd like if people said "the tomllib PEP" rather than "PEP 31415926"
• numbered references are annoying, you need to scroll around too much
• the SupportsRead type is specific to tomli, right?
• discussions on a write/roundtrip API are best left to a future PEP
• TODO: why does tomllib.loads take str but not bytes, then??

[hukkin]

the SupportsRead type is specific to tomli, right?

Nope, it's from typeshed https://github.com/python/typeshed/blob/6ff9020603eead6682a0a81f4b6095f00f3b216d/stdlib/_typeshed/__init__.pyi#L171

But yeah, I'm not sure if it's ok to use it in a PEP like this?

EDIT: Tomli actually uses typing.BinaryIO currently (because it's available in the stdlib) but that interface is much larger than strictly needed: https://github.com/python/cpython/blob/46e4c257e7c26c813620232135781e6c53fe8d4d/Lib/typing.py#L2580

EDIT 2: We could define SupportsRead in the PEP, it doesn't take many lines of code:

from typing import TypeVar, Protocol


_T_co = TypeVar("_T_co", covariant=True)


class SupportsRead(Protocol[_T_co]):
    def read(self) -> _T_co: ...

we can simplify further by making it non-generic:

from typing import Protocol

class SupportsReadBytes(Protocol):
    def read(self) -> bytes: ...

[hroncok]

If you pass a custom parse_float, this won't necessarily be true... right?

[hukkin]

That is correct!

[encukou]

The stdlib doesn't use type annotations, the hints should be moved to typeshed anyway.

In the PEP, TMO the typing is OK as a summary, as long as it's explained in prose. No need to define it as code. The annotation doesn't capture everything anyway: e.g. how end-of-file is signalled.

[hauntsaninja]

Thank you for the additional edits! This reads much clearer.

I think the draft is in a decent state, so I'll open a PR against python/peps soon :-)

[hukkin]

The stdlib doesn't use type annotations, the hints should be moved to typeshed anyway.

I found an interesting related discourse discussion. Some takes from there:

Guido van Rossum:

All that said, for brand new stdlib modules I think we could do an experiment. But we’d need a convention to tell type checkers “for this module, look in the stdlib for inline annotations.”

Paul Ganssle:

For Python-only modules inline type hints should be fine, but if you are writing a PEP 399-style C extension (and admittedly very few of these exist right now), it may not make a lot of sense to maintain stubs and inline type hints.

Guido van Rossum:

Before you do this, please check whether mypy even looks in the stdlib. IIRC it only looks in the typeshed stubs.

@hauntsaninja you've worked on mypy a lot, right? Do you know if mypy looks in the stdlib or only typeshed? Of course this isn't very relevant if @encukou isn't interested in such an experiment.

[encukou]

Hmm, I am interested in the experiment, actually!
But for now, please add the PEP without it, and let's discuss afterwards. (FWIW, I don't care that much for static type analyzers like mypy. Rather, I think typing can be nice documentation for humans.)

[hauntsaninja]

Yes, I'm a maintainer of mypy and typeshed. Type checkers currently only look at typeshed and do not look at standard library code.

Type annotations in the stdlib are very controversial; I wouldn't recommend touching that subject. I'm -1 on the idea of stdlib type annotations instead of typeshed, at least for now:

Pros:

• Makes aesthetic sense
• Helps document stdlib functions
• Keeps type annotations closer to source, potentially making maintenance easier

Cons:

• Appears to be a touchy subject among core developers
• Maintenance of annotations likely moves from people who care about typing to people who don't care about typing
• In practice, typeshed's rate of change is quite high. typeshed allows us to easily backport any type annotation improvements to all Python versions
• Lots of the standard library is tricky or impossible to type, typeshed uses a lot of new typing features and we often make editorial decisions about how truthful to be in stubs. Some typeshed tricks would be hard to pull off for modules that use inline types
• Maintenance of annotations might not be easier if we're not able to use type checkers to validate against the source (and could be harder e.g. typeshed uses a lot of third party tools to test annotations and it's not clear if they could be incorporated into CPython tests)
• Might not be ergonomic for C extension modules or PEP 399 modules
• Potential runtime cost of having annotations

That said, and perhaps more relevant here, I'd be totally fine with modules in the standard library using types for their own documentation (without the expectation that type checkers use them).

[encukou]

Looks like it'll be best to keep that discussion separate from this PEP.