Skip to content

Commit

Permalink
pythonGH-100502: Add pathlib.PurePath.flavour attribute
Browse files Browse the repository at this point in the history
This instance attribute stores the implementation of `os.path` used for
low-level path operations: either `posixpath` or `ntpath`.

The `PurePath` and `Path` initialisers gain a *flavour* keyword-only
argument that sets the flavour. This argument is not available in the
Posix- and Windows-specific subclasses, and as the `PurePath` and `Path`
classes are not directly instantiable, it is available therefore only in
user subclasses of `PurePath and `Path`. Such subclasses may determine
their flavour in `__init__()` and supply the flavour to `super()`.
  • Loading branch information
barneygale committed Jul 7, 2023
1 parent 363f4f9 commit aa553f1
Show file tree
Hide file tree
Showing 4 changed files with 89 additions and 56 deletions.
25 changes: 22 additions & 3 deletions Doc/library/pathlib.rst
Expand Up @@ -108,7 +108,7 @@ Pure path objects provide path-handling operations which don't actually
access a filesystem. There are three ways to access these classes, which
we also call *flavours*:

.. class:: PurePath(*pathsegments)
.. class:: PurePath(*pathsegments, flavour=os.path)

A generic class that represents the system's path flavour (instantiating
it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`)::
Expand Down Expand Up @@ -162,6 +162,15 @@ we also call *flavours*:
to ``PurePosixPath('bar')``, which is wrong if ``foo`` is a symbolic link
to another directory)

The *flavour* keyword-only argument is available only in user subclasses of
:class:`PurePath` and :class:`Path`. It specifies the implementation of
:mod:`os.path` to use for low-level path operations. It may be left unset
or set to :mod:`os.path` to use the current system's flavour, or set to
:mod:`posixpath` or :mod:`ntpath` to use POSIX or Windows path semantics.

.. versionchanged:: 3.13
The *flavour* parameter was added.

Pure path objects implement the :class:`os.PathLike` interface, allowing them
to be used anywhere the interface is accepted.

Expand Down Expand Up @@ -303,6 +312,13 @@ Methods and properties

Pure paths provide the following methods and properties:

.. attribute:: PurePath.flavour

The implementation of :mod:`os.path` used for low-level path operations;
either :mod:`posixpath` or :mod:`ntpath`.

.. versionchanged:: 3.13

.. attribute:: PurePath.drive

A string representing the drive letter or name, if any::
Expand Down Expand Up @@ -742,7 +758,7 @@ Concrete paths are subclasses of the pure path classes. In addition to
operations provided by the latter, they also provide methods to do system
calls on path objects. There are three ways to instantiate concrete paths:

.. class:: Path(*pathsegments)
.. class:: Path(*pathsegments, flavour=os.path)

A subclass of :class:`PurePath`, this class represents concrete paths of
the system's path flavour (instantiating it creates either a
Expand All @@ -751,7 +767,10 @@ calls on path objects. There are three ways to instantiate concrete paths:
>>> Path('setup.py')
PosixPath('setup.py')

*pathsegments* is specified similarly to :class:`PurePath`.
*pathsegments* and *flavour* are specified similarly to :class:`PurePath`.

.. versionchanged:: 3.13
The *flavour* parameter was added.

.. class:: PosixPath(*pathsegments)

Expand Down

0 comments on commit aa553f1

Please sign in to comment.