diff --git a/Doc/library/pathlib-parts.svg b/Doc/library/pathlib-parts.svg new file mode 100644 index 000000000000000..d561b6563c355ed --- /dev/null +++ b/Doc/library/pathlib-parts.svg @@ -0,0 +1,67 @@ + + Parts of a pathlib path + + For p = PurePosixPath('/srv/holy/grail.tar.gz'), p.parent is + PurePosixPath('/srv/holy'), p.name is 'grail.tar.gz', + p.stem is 'grail.tar', and p.suffix is '.gz'. + + + + + + /srv/holy/grail.tar.gz + + + + + + + + + + + + + + + + + + + + + + + p.stem + p.suffix + p.name + p.parent + + diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 709e7b49632c735..55b9098d55d26b3 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -307,6 +307,21 @@ Methods and properties from pathlib import PurePath, PurePosixPath, PureWindowsPath +The :attr:`~PurePath.parent`, :attr:`~PurePath.name`, +:attr:`~PurePath.stem`, and :attr:`~PurePath.suffix` properties describe +different parts of a path. For example, given:: + + >>> p = PurePosixPath('/srv/holy/grail.tar.gz') + +.. image:: pathlib-parts.svg + :align: center + :class: invert-in-dark-mode + :alt: For p = PurePosixPath('/srv/holy/grail.tar.gz'), p.parent is + PurePosixPath('/srv/holy'), p.name is 'grail.tar.gz', + p.stem is 'grail.tar', and p.suffix is '.gz'. + +The stem excludes only the final suffix: in this example, it includes ``.tar``. + Pure paths provide the following methods and properties: .. attribute:: PurePath.parser