Skip to content

bpo-24132: Add direct subclassing of PurePath/Path in pathlib #26906

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
kfollstad wants to merge 7 commits into from
Closed

bpo-24132: Add direct subclassing of PurePath/Path in pathlib #26906

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
710f577
bpo-24132: Add tests for class properties in pathlib's PurePath/Path
kfollstad Jun 11, 2021
a373969
bpo-24132: Add test for direct subclassing of PurePath/Path in pathlib
kfollstad Jun 14, 2021
35d8f78
bpo-24132: Fix inconsistent organization of is_mount in pathlib
kfollstad May 27, 2021
bab67b4
bpo-24132: Replace additional hardcoded references in pathlib
kfollstad May 3, 2021
67faae0
bpo-24132: Replace factory functionality with masquerade in pathlib
kfollstad Jun 14, 2021
610f41e
bpo-24132: Add tests for comparing subclasses of PurePath in pathlib
kfollstad Jun 17, 2021
a0c4998
bpo-24132: Document direct subclassing of PurePath/Path in pathlib
kfollstad Jun 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
bpo-24132: Document direct subclassing of PurePath/Path in pathlib 
Add documentation highlighting the new direct subclass functionality of
PurePath and Path. Also add new is_posix & is_windows doctest conditions
so that system specific doctest code can still be tested instead of just
being taken as a literal block and always skipped.
  • Loading branch information
@kfollstad
kfollstad committed Jun 24, 2021
commit a0c4998ffd2fdb32aa8901a7ba872a4d9ddaabba
4 changes: 4 additions & 0 deletions Doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@
import _tkinter
except ImportError:
_tkinter = None
from os import name as system_name
is_posix = system_name == 'posix'
is_windows = system_name == 'nt'
del system_name

@kfollstad kfollstad Jun 25, 2021 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or IS_POSIX/IS_WINDOWS? I am unaware of any precedence for the naming convention here. However having the ability to skip tests depending on platform, gives one the ability to actually have sphinx doctest the code in the documentation rather than just skipping it with :: and trusting that it is correct (as is the current practice throughout much of pathlib's documentation).

@merwok merwok Jan 5, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesnt really matter in this snippet that’s invisible to readers of the doc 🙂

I think lower case looks fine.

'''

manpages_url = 'https://manpages.debian.org/{path}'
Expand Down
52 changes: 51 additions & 1 deletion Doc/library/pathlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,7 +273,7 @@ Methods and properties

.. testsetup::

from pathlib import PurePath, PurePosixPath, PureWindowsPath
from pathlib import PurePath, PurePosixPath, PureWindowsPath, Path

Pure paths provide the following methods and properties:

Expand Down Expand Up @@ -1229,6 +1229,56 @@ call fails (for example because the path doesn't exist).
.. versionchanged:: 3.10
The *newline* parameter was added.

Subclassing and Extensibility
-----------------------------

Both :class:`PurePath` and :class:`Path` are directly subclassable and extensible as you
see fit:

>>> class MyPath(Path):
... def my_method(self, *args, **kwargs):
... ... # Platform agnostic implementation

.. note::
Unlike :class:`PurePath` or :class:`Path`, instantiating the derived
class will not generate a differently named class:

.. doctest::
:pyversion: > 3.11

@merwok merwok Jan 5, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is surprising to me: python docs document one version, so what is this for?
(also > and not >=?)

:skipif: is_windows

>>> Path('.') # On POSIX
PosixPath('.')
>>> MyPath('.')
MyPath('.')

Despite this, the subclass will otherwise match the class that would be
returned by the factory on your particular system type. For instance,
when instantiated on a POSIX system:

.. doctest::
:pyversion: > 3.11
:skipif: is_windows

>>> [Path('/dir').is_absolute, MyPath('/dir').is_absolute()]
[True, True]
>>> [Path().home().drive, MyPath().home().drive]
['', '']

@merwok merwok Jan 5, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A minor point: the lists here are a little bit distracting (we are looking at methods/properties, not working with lists).
Could use separate lines, or >>> Path().home().drive, MyPath().home().drive (which will have parens in the output but that’s fine, we’re used to commas being sometimes multiple things, sometimes a tuple object).


However on Windows, the *same code* will instead return values which
apply to that system:

.. doctest::
:pyversion: > 3.11
:skipif: is_posix

>>> [Path('/dir').is_absolute(), MyPath('/dir').is_absolute()]
[False, False]
>>> [Path().home().drive, MyPath().home().drive]
['C:', 'C:']

.. versionadded:: 3.11

Correspondence to tools in the :mod:`os` module
-----------------------------------------------

Expand Down
1 change: 1 addition & 0 deletions Misc/ACKS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -545,6 +545,7 @@ Matt Fleming
Hernán Martínez Foffani
Benjamin Fogle
Artem Fokin
Kevin Follstad
Arnaud Fontaine
Michael Foord
Amaury Forgeot d'Arc
Expand Down
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Library/2021-06-16-17-38-36.bpo-24132.FqsJWY.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Add a mechanism and support for direct subclassing of :class:`PurePath`
and :class:`Path` in pathlib.