Repository navigation
Protocol naming convention #4174
Description
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:
ReadableHasReadSupportsReadIsReadableReader
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
SupportsXfor protocols that provide type conversion (e.g.SupportsInt). - Use
Xablefor protocols that provide callable methods (e.g.Readable,LineReadable,BytesReadable,ReadSeekable). - Use
HasXfor protocols that have readable and/or writable attributes or getter/setter methods (e.g.HasItems,HasFileno).
Activity
hauntsaninja commentedon Jun 4, 2020
Overall, I like this! Some off the cuff notes:
_FormatMapMapping?SupportsRoundandSupportsAbsaren't exactly type conversion. It would be nice if they fit in, but maybe we're just stuck with that.Xablecan be awkward if there isn't a goodX. I'm not sure that there's too much value in reserving a separate verb for attributes/getters/setters. Maybe we can combine theXableandHasXcategories: so preferXableif there's an appropriateX, otherwise fall back toHasX._SupportsLessThanbe_SupportsLessThan,_Comparableor_HasLessThan(or something else)?JelleZijlstra commentedon Jun 4, 2020
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
SupportsXorXablevariety, exceptSizedandContainer. As @hauntsaninja says, not all of theSupportsXprotocols are really type conversions; I'm having a hard type coming up with a difference between theround()andreversed()protocols for example.I'd favor defaulting to
SupportsXin most cases, because it's less likely to lead to awkward phrasing. For example,SupportsLessThanfeels like the best option.Comparableisn't as precise because aComparableobject should also support other methods than__lt__, andLessThanAbleisn't a word. It's too late to change it, but I'd also have preferredSupportsInandSupportsLenoverContainerandSized.srittau commentedon Jun 8, 2020
Revised proposal:
Iterator,Container).SupportsInt,SupportsRead,SupportsReadline,SupportsReadSeek).HasItems,HasFileno).CraftSpider commentedon Jun 12, 2020
I like the proposed plan. Apologies for the delay, life has been hectic.
Protocol naming guidelines
Protocol naming guidelines (#4229)
Protocol naming guidelines (python#4229)