pathlib ABCs: add protocols for supporting types

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

@encukou

Penny for your thoughts on this @encukou :)

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

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?

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

Merge branch 'main' into pythongh-127456

pythonGH-127456: pathlib ABCs: remove `ParserBase.sep`

Merge branch 'main' into pythongh-127456

GH-127456: pathlib ABCs: add protocol for path parser (#127494)

pythonGH-127456: pathlib ABCs: add protocol for path parser (python#1…

Navigation Menu

Repository navigation

pathlib ABCs: add protocols for supporting types #127456

Feature or enhancement

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

pathlib ABCs: add protocols for supporting types #127456

Description

Feature or enhancement

Linked PRs

Activity

barneygale commented on Nov 30, 2024

AlexWaygood commented on Nov 30, 2024

barneygale commented on Nov 30, 2024

AlexWaygood commented on Nov 30, 2024

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions