Type hints for pathlib.types

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

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).

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 ¯\_(ツ)_/¯

My inspiration for the name was wsgiref.types

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).

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.

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?

Two reasons:

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
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.

Thanks, that all makes sense to me.

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

Huh, I thought we only avoided them for performance reasons. I don't see the point in splitting them across repositories otherwise, as it makes it too easy for things to go out-of-sync.

I'll follow up in discourse

we are avoiding adding type hints to the standard library, as

Yes, and that's what I said for others. However, Barney said that pathlib.types would not be imported by the stdlib itself and should only serve for external implementations. So, I guessed that we could add type hints here (this point was also stated on DPO but I'm re-writing it here as well for those who only skimmed through the issue)

I've replied in discourse (sorry for the delay). I'd personally suggest that the annotations are contributed to typeshed and that the pathlib.types module uses an ABC with the typing protocol trick (see the recent io.Readable PR). If you're amenable to that, I can help with a PR.

Since pathlib.types is not imported at runtime, what is the reason to apply the protocol trick to _PathParser and PathInfo?

Or are you suggesting to make both available under the pathlib namesspace, therefore requiring to work around the typing import?

Navigation Menu

Repository navigation

Type hints for `pathlib.types` #130798

Feature or enhancement

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Type hints for pathlib.types #130798

Description

Feature or enhancement

Linked PRs

Activity

picnixz commented on Mar 3, 2025

barneygale commented on Mar 3, 2025

barneygale commented on Mar 3, 2025

picnixz commented on Mar 3, 2025

barneygale commented on Mar 3, 2025

gvanrossum commented on Mar 3, 2025

barneygale commented on Mar 4, 2025

gvanrossum commented on Mar 4, 2025

AA-Turner commented on Mar 26, 2025

barneygale commented on Mar 26, 2025

barneygale commented on Mar 26, 2025

picnixz commented on Mar 28, 2025

AA-Turner commented on Apr 10, 2025

ap-- commented on Apr 12, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Type hints for `pathlib.types` #130798