Protocol naming convention

[srittau]

Now that we have a central stub for common types and protocols, we should think about how we name protocols in typeshed. Currently there is no common convention. Some possible conventions for a "read" protocol:

• Readable
• HasRead
• SupportsRead
• IsReadable
• Reader

I have no strong preferences, but I think the naming to reflect that a class is a protocol. Therefore I'd suggest we should use either, some, or all of the above. The second name (HasRead) clearly implies the existence of a field read, but would exclude protocols with multiple fields, such as this from stdlib/3.9/zoneinfo/__init__.pyi:

class _IOBytes(Protocol):
    def read(self, __size: int) -> bytes: ...
    def seek(self, __size: int, __whence: int = ...) -> Any: ...

Here is a proposal to start the discussion:

• Use plain names for protocols that represent a clear concept (e.g. Iterator, Container).
• Use SupportsX for protocols that provide type conversion (e.g. SupportsInt).
• Use Xable for protocols that provide callable methods (e.g. Readable, LineReadable, BytesReadable, ReadSeekable).
• Use HasX for protocols that have readable and/or writable attributes or getter/setter methods (e.g. HasItems, HasFileno).

[hauntsaninja]

Overall, I like this! Some off the cuff notes:

• What would you recommend for _FormatMapMapping?
• Do you have suggestions for conventions for callback protocols?
• SupportsRound and SupportsAbs aren't exactly type conversion. It would be nice if they fit in, but maybe we're just stuck with that.
• Xable can be awkward if there isn't a good X. I'm not sure that there's too much value in reserving a separate verb for attributes/getters/setters. Maybe we can combine the Xable and HasX categories: so prefer Xable if there's an appropriate X, otherwise fall back to HasX.
• Should _SupportsLessThan be _SupportsLessThan, _Comparable or _HasLessThan (or something else)?

[JelleZijlstra]

I decided to look at the existing one-shot protocols in typing (since we're stuck with their names):

• SupportsInt (__int__)
• SupportsFloat (__float__)
• SupportsComplex (__complex__)
• SupportsBytes (__bytes__)
• SupportsIndex (__index__)
• SupportsAbs (__abs__)
• SupportsRound (__round__)
• Reversible (__reversed__)
• Hashable (__hash__)
• Iterable (__iter__)
• Awaitable (__await__)
• AsyncIterable (__aiter__)
• Sized (__len__)
• Container (__contains__)

Most are of the SupportsX or Xable variety, except Sized and Container. As @hauntsaninja says, not all of the SupportsX protocols are really type conversions; I'm having a hard type coming up with a difference between the round() and reversed() protocols for example.

I'd favor defaulting to SupportsX in most cases, because it's less likely to lead to awkward phrasing. For example, SupportsLessThan feels like the best option. Comparable isn't as precise because a Comparable object should also support other methods than __lt__, and LessThanAble isn't a word. It's too late to change it, but I'd also have preferred SupportsIn and SupportsLen over Container and Sized.

[srittau]

Revised proposal:

• Use plain names for protocols that represent a clear concept (e.g. Iterator, Container).
• Use SupportsX for protocols that provide callable methods (e.g. SupportsInt, SupportsRead, SupportsReadline, SupportsReadSeek).
• Use HasX for protocols that have readable and/or writable attributes or getter/setter methods (e.g. HasItems, HasFileno).

[CraftSpider]

I like the proposed plan. Apologies for the delay, life has been hectic.