pathlib ABCs: add protocols for supporting types

[barneygale]

Feature or enhancement

For typing and documentation purposes, it would be useful to define three protocols in pathlib:

• Parser: like os.path, but including only pure functionality that's essential for PurePathBase
  • This already exists, but it's defined and used in an odd way.
• DirEntry: like os.DirEntry, but without some non-portable methods (like inode())
• StatResult: like os.stat_result, but without the tuple-like interface, and dropping non-essential attributes

These could be defined in a private module like pathlib._types. For performance reasons that module shouldn't be imported by any other pathlib module.

If/when we make PathBase public, we'll also make these protocols public.

See also: https://discuss.python.org/t/make-pathlib-extensible/3428/196

Linked PRs

• GH-127456: pathlib ABCs: add protocol for path parser #127494
• GH-127456: pathlib ABCs: remove Parser.sep #127725

[barneygale]

Penny for your thoughts on this @encukou :)

[AlexWaygood]

If you want to avoid adding a dependency on the typing module at runtime, you can use a similar technique to what we do with the protocol-like ABCs in collections.abc, contextlib and os:

• Use ABCs for the runtime implementation
• But add them to this allowlist in typing so that the typing module treats them the same way it does protocol classes:

  cpython/Lib/typing.py

  Lines 1940 to 1948 in 328187c

  	_PROTO_ALLOWLIST = {
  	'collections.abc': [
  	'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable',
  	'AsyncIterator', 'Hashable', 'Sized', 'Container', 'Collection',
  	'Reversible', 'Buffer',
  	],
  	'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
  	'os': ['PathLike'],
  	}

• And in typeshed, pretend that they're protocols so that type checkers treat them identically to "actual" protocols

[barneygale]

Thanks Alex - that will be useful when/if when make PathBase and friends public, but for now I might make pathlib._types an "orphan" module that's imported by nothing else. This also lets me add type annotations for free. It's a bit similar to wsgiref.types. Do you think I'm missing a pitfall with that approach?

[AlexWaygood]

Oh, if that's the plan then that should be fine, yup!