Type hints for `pathlib.types`

[barneygale]

Feature or enhancement

The pathlib.types module is new in 3.14, and contains a single public class: pathlib.types.PathInfo.

This module also contains a few private classes: _PathParser, _JoinablePath, _ReadablePath and _WritablePath.

As the pathlib.types module is not imported by pathlib, I think we're free to add proper type annotations to the entire module, including the private classes. I think this will help clarify the interface.

I'd like these hints to be compatible with the oldest version of Python still receiving security updates (3.9 at time of writing) because I'm hoping to provide a PyPI package from this module.

Linked PRs

• GH-130798: Add type hints to pathlib.types #131639

[picnixz]

As the pathlib.types module is not imported by pathlib

Since this is the case, I don't think we'll need to bother about import time then. Are you planning to have more protocol-like classes, namely something that evolves like collections.abc? (I think pathlib.types is something like collections.abc then; maybe we should name it pathlib.abc instead? idk).

[barneygale]

It's currently a mix of protocols (_PathParser, PathInfo) and ABCs (_JoinablePath, _ReadablePath, _WritablePath). I don't mind too much what we name it, and perhaps the protocols would be better off as ABCs anyway. I'm kinda clueless with typing ¯\_(ツ)_/¯

[barneygale]

My inspiration for the name was wsgiref.types

[picnixz]

Err, ok, let's keep it ".types" instead. That way, we can reserve ".abc" for future usage and usage that can be imported by pathlib itself.

Also, now that I think about, .abc would be more for top-level abstract classes rather that would be eventually used by pathlib. But since pathlib doesn't use it, it's probably better as .types (I don't have a better naming).

[barneygale]

FWIW, I don't think pathlib will import ABCs in future. We want to avoid inheriting abc.ABC (via os.PathLike or _JoinablePath) from pathlib.PurePath because it slows down isinstance() checks; instead we register() PurePath as a "virtual" subclass of os.PathLike and _JoinablePath. Same sort of thing applies in Path with the readable/writable ABCs.

[gvanrossum]

I was all okay with the proposed plan (which also seems to be already implemented?) until I saw that you were planning to release some part of the stdlib as a PyPI package. Can you explain why you want that?

[barneygale]

Two reasons:

1. While the ABCs are still private in the stdlib, a PyPI package allows users to use and evaluate the APIs. Unlike in the stdlib, the PyPI package would fully document the classes and drop the underscores prefixes
2. If the ABCs are accepted into the public stdlib (by way of a PEP), the PyPI package would provide backports for older versions of Python, similar to how the zipp PyPI package ports newer zipfile.Path for older Python

Does that make sense? I'm happy to change tack if you'd prefer.

[gvanrossum]

Thanks, that all makes sense to me.

[AA-Turner]

My understanding (Discourse ref) is that we are avoiding adding type hints to the standard library, as they are both more easily changeable in and overriden by typeshed. From that Discourse thread, "Given that typeshed is supposed to override the stdlib, having the same annotations in the stdlib itself wouldn’t gain us anything, and having different annotations might be confusing to users."

Indeed, we have recently removed some annotations from the stdlib where typeshed does a better job.

Perhaps we should hold off on adding type annotations to pathlib.types, in this case?

A