[Python-checkins] cpython: Issue #19673: Add pathlib to the stdlib as a provisional module (PEP 428).
antoine.pitrou
python-checkins at python.org
Fri Nov 22 17:38:52 CET 2013
http://hg.python.org/cpython/rev/43377dcfb801
changeset: 87348:43377dcfb801
user: Antoine Pitrou <solipsis at pitrou.net>
date: Fri Nov 22 17:38:12 2013 +0100
summary:
Issue #19673: Add pathlib to the stdlib as a provisional module (PEP 428).
files:
Doc/library/filesys.rst | 1 +
Doc/library/glob.rst | 4 +
Doc/library/os.path.rst | 5 +
Doc/library/pathlib.rst | 874 +++++++++++++
Doc/whatsnew/3.4.rst | 18 +
Lib/pathlib.py | 1287 ++++++++++++++++++++
Lib/test/test_pathlib.py | 1639 ++++++++++++++++++++++++++
Misc/NEWS | 2 +
8 files changed, 3830 insertions(+), 0 deletions(-)
diff --git a/Doc/library/filesys.rst b/Doc/library/filesys.rst
--- a/Doc/library/filesys.rst
+++ b/Doc/library/filesys.rst
@@ -12,6 +12,7 @@
.. toctree::
+ pathlib.rst
os.path.rst
fileinput.rst
stat.rst
diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst
--- a/Doc/library/glob.rst
+++ b/Doc/library/glob.rst
@@ -25,6 +25,10 @@
For example, ``'[?]'`` matches the character ``'?'``.
+.. seealso::
+ The :mod:`pathlib` module offers high-level path objects.
+
+
.. function:: glob(pathname)
Return a possibly-empty list of path names that match *pathname*, which must be
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -22,6 +22,11 @@
explicitly when an application desires shell-like path expansion. (See also
the :mod:`glob` module.)
+
+.. seealso::
+ The :mod:`pathlib` module offers high-level path objects.
+
+
.. note::
All of these functions accept either only bytes or only string objects as
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
new file mode 100644
--- /dev/null
+++ b/Doc/library/pathlib.rst
@@ -0,0 +1,874 @@
+
+:mod:`pathlib` --- Object-oriented filesystem paths
+===================================================
+
+.. module:: pathlib
+ :synopsis: Object-oriented filesystem paths
+
+.. index:: single: path; operations
+
+.. versionadded:: 3.4
+
+
+This module offers classes representing filesystem paths with semantics
+appropriate for different operating systems. Path classes are divided
+between :ref:`pure paths <pure-paths>`, which provide purely computational
+operations without I/O, and :ref:`concrete paths <concrete-paths>`, which
+inherit from pure paths but also provide I/O operations.
+
+The main point of entry is the :class:`Path` class, which will instantiate
+a :ref:`concrete path <concrete-paths>` for the current platform.
+
+.. note::
+ This module module has been included in the standard library on a
+ :term:`provisional basis <provisional package>`. Backwards incompatible
+ changes (up to and including removal of the package) may occur if deemed
+ necessary by the core developers.
+
+.. seealso::
+ :pep:`428`: The pathlib module -- object-oriented filesystem paths.
+
+.. seealso::
+ For low-level path manipulation on strings, you can also use the
+ :mod:`os.path` module.
+
+
+Basic use
+---------
+
+Importing the main class::
+
+ >>> from pathlib import Path
+
+Listing subdirectories::
+
+ >>> p = Path('.')
+ >>> [x for x in p.iterdir() if x.is_dir()]
+ [PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
+ PosixPath('__pycache__'), PosixPath('build')]
+
+Listing Python source files in this directory tree::
+
+ >>> list(p.glob('**/*.py'))
+ [PosixPath('test_pathlib.py'), PosixPath('setup.py'),
+ PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
+ PosixPath('build/lib/pathlib.py')]
+
+Navigating inside a directory tree::
+
+ >>> p = Path('/etc')
+ >>> q = p / 'init.d' / 'reboot'
+ >>> q
+ PosixPath('/etc/init.d/reboot')
+ >>> q.resolve()
+ PosixPath('/etc/rc.d/init.d/halt')
+
+Querying path properties::
+
+ >>> q.exists()
+ True
+ >>> q.is_dir()
+ False
+
+Opening a file::
+
+ >>> with q.open() as f: f.readline()
+ ...
+ '#!/bin/bash\n'
+
+
+.. _pure-paths:
+
+Pure paths
+----------
+
+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:: PurePosixPath
+
+ A subclass of :class:`PurePath`, this path flavour represents non-Windows
+ filesystem paths::
+
+ >>> PurePosixPath('/etc')
+ PurePosixPath('/etc')
+
+.. class:: PureWindowsPath
+
+ A subclass of :class:`PurePath`, this path flavour represents Windows
+ filesystem paths::
+
+ >>> PureWindowsPath('c:/Program Files/')
+ PureWindowsPath('c:/Program Files')
+
+.. class:: PurePath
+
+ A generic class that represents the system's path flavour (instantiating
+ it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`)::
+
+ >>> PurePath('setup.py')
+ PurePosixPath('setup.py')
+
+
+Regardless of the system you're running on, you can instantiate all of
+these classes, since they don't provide any operation that does system calls.
+
+
+Constructing paths
+^^^^^^^^^^^^^^^^^^
+
+Path constructors accept an arbitrary number of positional arguments.
+When called without any argument, a path object points to the current
+directory::
+
+ >>> PurePath()
+ PurePosixPath('.')
+
+Any argument can be a string or bytes object representing an arbitrary number
+of path segments, but it can also be another path object::
+
+ >>> PurePath('foo', 'some/path', 'bar')
+ PurePosixPath('foo/some/path/bar')
+ >>> PurePath(Path('foo'), Path('bar'))
+ PurePosixPath('foo/bar')
+
+When several absolute paths are given, the last is taken as an anchor
+(mimicking :func:`os.path.join`'s behaviour)::
+
+ >>> PurePath('/etc', '/usr', 'lib64')
+ PurePosixPath('/usr/lib64')
+ >>> PureWindowsPath('c:/Windows', 'd:bar')
+ PureWindowsPath('d:bar')
+
+However, in a Windows path, changing the local root doesn't discard the
+previous drive setting::
+
+ >>> PureWindowsPath('c:/Windows', '/Program Files')
+ PureWindowsPath('c:/Program Files')
+
+Spurious slashes and single dots are collapsed, but double dots (``'..'``)
+are not, since this would change the meaning of a path in the face of
+symbolic links::
+
+ >>> PurePath('foo//bar')
+ PurePosixPath('foo/bar')
+ >>> PurePath('foo/./bar')
+ PurePosixPath('foo/bar')
+ >>> PurePath('foo/../bar')
+ PurePosixPath('foo/../bar')
+
+(a naïve approach would make ``PurePosixPath('foo/../bar')`` equivalent
+to ``PurePosixPath('bar')``, which is wrong if ``foo`` is a symbolic link
+to another directory)
+
+
+General properties
+^^^^^^^^^^^^^^^^^^
+
+Paths are immutable and hashable. Paths of a same flavour are comparable
+and orderable. These properties respect the flavour's case-folding
+semantics::
+
+ >>> PurePosixPath('foo') == PurePosixPath('FOO')
+ False
+ >>> PureWindowsPath('foo') == PureWindowsPath('FOO')
+ True
+ >>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
+ True
+ >>> PureWindowsPath('C:') < PureWindowsPath('d:')
+ True
+
+Paths of a different flavour compare unequal and cannot be ordered::
+
+ >>> PureWindowsPath('foo') == PurePosixPath('foo')
+ False
+ >>> PureWindowsPath('foo') < PurePosixPath('foo')
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ TypeError: unorderable types: PureWindowsPath() < PurePosixPath()
+
+
+Operators
+^^^^^^^^^
+
+The slash operator helps create child paths, similarly to :func:`os.path.join`::
+
+ >>> p = PurePath('/etc')
+ >>> p
+ PurePosixPath('/etc')
+ >>> p / 'init.d' / 'apache2'
+ PurePosixPath('/etc/init.d/apache2')
+ >>> q = PurePath('bin')
+ >>> '/usr' / q
+ PurePosixPath('/usr/bin')
+
+The string representation of a path is the raw filesystem path itself
+(in native form, e.g. with backslashes under Windows), which you can
+pass to any function taking a file path as a string::
+
+ >>> p = PurePath('/etc')
+ >>> str(p)
+ '/etc'
+ >>> p = PureWindowsPath('c:/Program Files')
+ >>> str(p)
+ 'c:\\Program Files'
+
+Similarly, calling :class:`bytes` on a path gives the raw filesystem path as a
+bytes object, as encoded by :func:`os.fsencode`::
+
+ >>> bytes(p)
+ b'/etc'
+
+.. note::
+ Calling :class:`bytes` is only recommended under Unix. Under Windows,
+ the unicode form is the canonical representation of filesystem paths.
+
+
+Accessing individual parts
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To access the individual "parts" (components) of a path, use the following
+property:
+
+.. data:: PurePath.parts
+
+ A tuple giving access to the path's various components::
+
+ >>> p = PurePath('/usr/bin/python3')
+ >>> p.parts
+ ('/', 'usr', 'bin', 'python3')
+
+ >>> p = PureWindowsPath('c:/Program Files/PSF')
+ >>> p.parts
+ ('c:\\', 'Program Files', 'PSF')
+
+ (note how the drive and local root are regrouped in a single part)
+
+
+Methods and properties
+^^^^^^^^^^^^^^^^^^^^^^
+
+Pure paths provide the following methods an properties:
+
+.. data:: PurePath.drive
+
+ A string representing the drive letter or name, if any::
+
+ >>> PureWindowsPath('c:/Program Files/').drive
+ 'c:'
+ >>> PureWindowsPath('/Program Files/').drive
+ ''
+ >>> PurePosixPath('/etc').drive
+ ''
+
+ UNC shares are also considered drives::
+
+ >>> PureWindowsPath('//host/share/foo.txt').drive
+ '\\\\host\\share'
+
+.. data:: PurePath.root
+
+ A string representing the (local or global) root, if any::
+
+ >>> PureWindowsPath('c:/Program Files/').root
+ '\\'
+ >>> PureWindowsPath('c:Program Files/').root
+ ''
+ >>> PurePosixPath('/etc').root
+ '/'
+
+ UNC shares always have a root::
+
+ >>> PureWindowsPath('//host/share').root
+ '\\'
+
+.. data:: PurePath.anchor
+
+ The concatenation of the drive and root::
+
+ >>> PureWindowsPath('c:/Program Files/').anchor
+ 'c:\\'
+ >>> PureWindowsPath('c:Program Files/').anchor
+ 'c:'
+ >>> PurePosixPath('/etc').anchor
+ '/'
+ >>> PureWindowsPath('//host/share').anchor
+ '\\\\host\\share\\'
+
+
+.. data:: PurePath.parents
+
+ An immutable sequence providing access to the logical ancestors of
+ the path::
+
+ >>> p = PureWindowsPath('c:/foo/bar/setup.py')
+ >>> p.parents[0]
+ PureWindowsPath('c:/foo/bar')
+ >>> p.parents[1]
+ PureWindowsPath('c:/foo')
+ >>> p.parents[2]
+ PureWindowsPath('c:/')
+
+
+.. data:: PurePath.parent
+
+ The logical parent of the path::
+
+ >>> p = PurePosixPath('/a/b/c/d')
+ >>> p.parent
+ PurePosixPath('/a/b/c')
+
+ You cannot go past an anchor, or empty path::
+
+ >>> p = PurePosixPath('/')
+ >>> p.parent
+ PurePosixPath('/')
+ >>> p = PurePosixPath('.')
+ >>> p.parent
+ PurePosixPath('.')
+
+ .. note::
+ This is a purely lexical operation, hence the following behaviour::
+
+ >>> p = PurePosixPath('foo/..')
+ >>> p.parent
+ PurePosixPath('foo')
+
+ If you want to walk an arbitrary filesystem path upwards, it is
+ recommended to first call :meth:`Path.resolve` so as to resolve
+ symlinks and eliminate `".."` components.
+
+
+.. data:: PurePath.name
+
+ A string representing the final path component, excluding the drive and
+ root, if any::
+
+ >>> PurePosixPath('my/library/setup.py').name
+ 'setup.py'
+
+ UNC drive names are not considered::
+
+ >>> PureWindowsPath('//some/share/setup.py').name
+ 'setup.py'
+ >>> PureWindowsPath('//some/share').name
+ ''
+
+
+.. data:: PurePath.suffix
+
+ The file extension of the final component, if any::
+
+ >>> PurePosixPath('my/library/setup.py').suffix
+ '.py'
+ >>> PurePosixPath('my/library.tar.gz').suffix
+ '.gz'
+ >>> PurePosixPath('my/library').suffix
+ ''
+
+
+.. data:: PurePath.suffixes
+
+ A list of the path's file extensions::
+
+ >>> PurePosixPath('my/library.tar.gar').suffixes
+ ['.tar', '.gar']
+ >>> PurePosixPath('my/library.tar.gz').suffixes
+ ['.tar', '.gz']
+ >>> PurePosixPath('my/library').suffixes
+ []
+
+
+.. data:: PurePath.stem
+
+ The final path component, without its suffix::
+
+ >>> PurePosixPath('my/library.tar.gz').stem
+ 'library.tar'
+ >>> PurePosixPath('my/library.tar').stem
+ 'library'
+ >>> PurePosixPath('my/library').stem
+ 'library'
+
+
+.. method:: PurePath.as_posix()
+
+ Return a string representation of the path with forward slashes (``/``)::
+
+ >>> p = PureWindowsPath('c:\\windows')
+ >>> str(p)
+ 'c:\\windows'
+ >>> p.as_posix()
+ 'c:/windows'
+
+
+.. method:: PurePath.as_uri()
+
+ Represent the path as a ``file`` URI. :exc:`ValueError` is raised if
+ the path isn't absolute.
+
+ >>> p = PurePosixPath('/etc/passwd')
+ >>> p.as_uri()
+ 'file:///etc/passwd'
+ >>> p = PureWindowsPath('c:/Windows')
+ >>> p.as_uri()
+ 'file:///c:/Windows'
+
+
+.. method:: PurePath.is_absolute()
+
+ Return whether the path is absolute or not. A path is considered absolute
+ if it has both a root and (if the flavour allows) a drive::
+
+ >>> PurePosixPath('/a/b').is_absolute()
+ True
+ >>> PurePosixPath('a/b').is_absolute()
+ False
+
+ >>> PureWindowsPath('c:/a/b').is_absolute()
+ True
+ >>> PureWindowsPath('/a/b').is_absolute()
+ False
+ >>> PureWindowsPath('c:').is_absolute()
+ False
+ >>> PureWindowsPath('//some/share').is_absolute()
+ True
+
+
+.. method:: PurePath.is_reserved()
+
+ With :class:`PureWindowsPath`, return True if the path is considered
+ reserved under Windows, False otherwise. With :class:`PurePosixPath`,
+ False is always returned.
+
+ >>> PureWindowsPath('nul').is_reserved()
+ True
+ >>> PurePosixPath('nul').is_reserved()
+ False
+
+ File system calls on reserved paths can fail mysteriously or have
+ unintended effects.
+
+
+.. method:: PurePath.joinpath(*other)
+
+ Calling this method is equivalent to indexing the path with each of
+ the *other* arguments in turn::
+
+ >>> PurePosixPath('/etc').joinpath('passwd')
+ PurePosixPath('/etc/passwd')
+ >>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd'))
+ PurePosixPath('/etc/passwd')
+ >>> PurePosixPath('/etc').joinpath('init.d', 'apache2')
+ PurePosixPath('/etc/init.d/apache2')
+ >>> PureWindowsPath('c:').joinpath('/Program Files')
+ PureWindowsPath('c:/Program Files')
+
+
+.. method:: PurePath.match(pattern)
+
+ Match this path against the provided glob-style pattern. Return True
+ if matching is successful, False otherwise.
+
+ If *pattern* is relative, the path can be either relative or absolute,
+ and matching is done from the right::
+
+ >>> PurePath('a/b.py').match('*.py')
+ True
+ >>> PurePath('/a/b/c.py').match('b/*.py')
+ True
+ >>> PurePath('/a/b/c.py').match('a/*.py')
+ False
+
+ If *pattern* is absolute, the path must be absolute, and the whole path
+ must match::
+
+ >>> PurePath('/a.py').match('/*.py')
+ True
+ >>> PurePath('a/b.py').match('/*.py')
+ False
+
+ As with other methods, case-sensitivity is observed::
+
+ >>> PureWindowsPath('b.py').match('*.PY')
+ True
+
+
+.. method:: PurePath.relative_to(*other)
+
+ Compute a version of this path relative to the path represented by
+ *other*. If it's impossible, ValueError is raised::
+
+ >>> p = PurePosixPath('/etc/passwd')
+ >>> p.relative_to('/')
+ PurePosixPath('etc/passwd')
+ >>> p.relative_to('/etc')
+ PurePosixPath('passwd')
+ >>> p.relative_to('/usr')
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ File "pathlib.py", line 694, in relative_to
+ .format(str(self), str(formatted)))
+ ValueError: '/etc/passwd' does not start with '/usr'
+
+
+.. _concrete-paths:
+
+
+Concrete paths
+--------------
+
+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:: PosixPath
+
+ A subclass of :class:`Path` and :class:`PurePosixPath`, this class
+ represents concrete non-Windows filesystem paths::
+
+ >>> PosixPath('/etc')
+ PosixPath('/etc')
+
+.. class:: WindowsPath
+
+ A subclass of :class:`Path` and :class:`PureWindowsPath`, this class
+ represents concrete Windows filesystem paths::
+
+ >>> WindowsPath('c:/Program Files/')
+ WindowsPath('c:/Program Files')
+
+.. class:: Path
+
+ A subclass of :class:`PurePath`, this class represents concrete paths of
+ the system's path flavour (instantiating it creates either a
+ :class:`PosixPath` or a :class:`WindowsPath`)::
+
+ >>> Path('setup.py')
+ PosixPath('setup.py')
+
+
+You can only instantiate the class flavour that corresponds to your system
+(allowing system calls on non-compatible path flavours could lead to
+bugs or failures in your application)::
+
+ >>> import os
+ >>> os.name
+ 'posix'
+ >>> Path('setup.py')
+ PosixPath('setup.py')
+ >>> PosixPath('setup.py')
+ PosixPath('setup.py')
+ >>> WindowsPath('setup.py')
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ File "pathlib.py", line 798, in __new__
+ % (cls.__name__,))
+ NotImplementedError: cannot instantiate 'WindowsPath' on your system
+
+
+Methods
+^^^^^^^
+
+Concrete paths provide the following methods in addition to pure paths
+methods. Many of these methods can raise an :exc:`OSError` if a system
+call fails (for example because the path doesn't exist):
+
+.. classmethod:: Path.cwd()
+
+ Return a new path object representing the current directory (as returned
+ by :func:`os.getcwd`)::
+
+ >>> Path.cwd()
+ PosixPath('/home/antoine/pathlib')
+
+
+.. method:: Path.stat()
+
+ Return information about this path (similarly to :func:`os.stat`).
+ The result is looked up at each call to this method.
+
+ >>> p = Path('setup.py')
+ >>> p.stat().st_size
+ 956
+ >>> p.stat().st_mtime
+ 1327883547.852554
+
+
+.. method:: Path.chmod(mode)
+
+ Change the file mode and permissions, like :func:`os.chmod`::
+
+ >>> p = Path('setup.py')
+ >>> p.stat().st_mode
+ 33277
+ >>> p.chmod(0o444)
+ >>> p.stat().st_mode
+ 33060
+
+
+.. method:: Path.exists()
+
+ Whether the path points to an existing file or directory::
+
+ >>> Path('.').exists()
+ True
+ >>> Path('setup.py').exists()
+ True
+ >>> Path('/etc').exists()
+ True
+ >>> Path('nonexistentfile').exists()
+ False
+
+ .. note::
+ If the path points to a symlink, :meth:`exists` returns whether the
+ symlink *points to* an existing file or directory.
+
+
+.. method:: Path.glob(pattern)
+
+ Glob the given *pattern* in the directory represented by this path,
+ yielding all matching files (of any kind)::
+
+ >>> sorted(Path('.').glob('*.py'))
+ [PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
+ >>> sorted(Path('.').glob('*/*.py'))
+ [PosixPath('docs/conf.py')]
+
+ The "``**``" pattern means "this directory and all subdirectories,
+ recursively". In other words, it enables recursive globbing::
+
+ >>> sorted(Path('.').glob('**/*.py'))
+ [PosixPath('build/lib/pathlib.py'),
+ PosixPath('docs/conf.py'),
+ PosixPath('pathlib.py'),
+ PosixPath('setup.py'),
+ PosixPath('test_pathlib.py')]
+
+ .. note::
+ Using the "``**``" pattern in large directory trees may consume
+ an inordinate amount of time.
+
+
+.. method:: Path.group()
+
+ Return the name of the group owning the file. :exc:`KeyError` is thrown
+ if the file's gid isn't found in the system database.
+
+
+.. method:: Path.is_dir()
+
+ Return True if the path points to a directory (or a symbolic link
+ pointing to a directory), False if it points to another kind of file.
+
+ False is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.is_file()
+
+ Return True if the path points to a regular file (or a symbolic link
+ pointing to a regular file), False if it points to another kind of file.
+
+ False is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.is_symlink()
+
+ Return True if the path points to a symbolic link, False otherwise.
+
+ False is also returned if the path doesn't exist; other errors (such
+ as permission errors) are propagated.
+
+
+.. method:: Path.is_socket()
+
+ Return True if the path points to a Unix socket (or a symbolic link
+ pointing to a Unix socket), False if it points to another kind of file.
+
+ False is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.is_fifo()
+
+ Return True if the path points to a FIFO (or a symbolic link
+ pointing to a FIFO), False if it points to another kind of file.
+
+ False is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.is_block_device()
+
+ Return True if the path points to a block device (or a symbolic link
+ pointing to a block device), False if it points to another kind of file.
+
+ False is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.is_char_device()
+
+ Return True if the path points to a character device (or a symbolic link
+ pointing to a character device), False if it points to another kind of file.
+
+ False is also returned if the path doesn't exist or is a broken symlink;
+ other errors (such as permission errors) are propagated.
+
+
+.. method:: Path.iterdir()
+
+ When the path points to a directory, yield path objects of the directory
+ contents::
+
+ >>> p = Path('docs')
+ >>> for child in p.iterdir(): child
+ ...
+ PosixPath('docs/conf.py')
+ PosixPath('docs/_templates')
+ PosixPath('docs/make.bat')
+ PosixPath('docs/index.rst')
+ PosixPath('docs/_build')
+ PosixPath('docs/_static')
+ PosixPath('docs/Makefile')
+
+.. method:: Path.lchmod(mode)
+
+ Like :meth:`Path.chmod` but, if the path points to a symbolic link, the
+ symbolic link's mode is changed rather than its target's.
+
+
+.. method:: Path.lstat()
+
+ Like :meth:`Path.stat` but, if the path points to a symbolic link, return
+ the symbolic link's information rather than its target's.
+
+
+.. method:: Path.mkdir(mode=0o777, parents=False)
+
+ Create a new directory at this given path. If *mode* is given, it is
+ combined with the process' ``umask`` value to determine the file mode
+ and access flags. If the path already exists, :exc:`OSError` is raised.
+
+ If *parents* is True, any missing parents of this path are created
+ as needed. If *parents* is False (the default), a missing parent raises
+ :exc:`OSError`.
+
+
+.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
+
+ Open the file pointed to by the path, like the built-in :func:`open`
+ function does::
+
+ >>> p = Path('setup.py')
+ >>> with p.open() as f:
+ ... f.readline()
+ ...
+ '#!/usr/bin/env python3\n'
+
+
+.. method:: Path.owner()
+
+ Return the name of the user owning the file. :exc:`KeyError` is thrown
+ if the file's uid isn't found in the system database.
+
+
+.. method:: Path.rename(target)
+
+ Rename this file or directory to the given *target*. *target* can be
+ either a string or another path object::
+
+ >>> p = Path('foo')
+ >>> p.open('w').write('some text')
+ 9
+ >>> target = Path('bar')
+ >>> p.rename(target)
+ >>> target.open().read()
+ 'some text'
+
+
+.. method:: Path.replace(target)
+
+ Rename this file or directory to the given *target*. If *target* points
+ to an existing file or directory, it will be unconditionally replaced.
+
+
+.. method:: Path.resolve()
+
+ Make the path absolute, resolving any symlinks. A new path object is
+ returned::
+
+ >>> p = Path()
+ >>> p
+ PosixPath('.')
+ >>> p.resolve()
+ PosixPath('/home/antoine/pathlib')
+
+ `".."` components are also eliminated (this is the only method to do so)::
+
+ >>> p = Path('docs/../setup.py')
+ >>> p.resolve()
+ PosixPath('/home/antoine/pathlib/setup.py')
+
+ If the path doesn't exist, :exc:`FileNotFoundError` is raised. If an
+ infinite loop is encountered along the resolution path,
+ :exc:`RuntimeError` is raised.
+
+
+.. method:: Path.rglob(pattern)
+
+ This is like calling :meth:`glob` with "``**``" added in front of the
+ given *pattern*:
+
+ >>> sorted(Path().rglob("*.py"))
+ [PosixPath('build/lib/pathlib.py'),
+ PosixPath('docs/conf.py'),
+ PosixPath('pathlib.py'),
+ PosixPath('setup.py'),
+ PosixPath('test_pathlib.py')]
+
+
+.. method:: Path.rmdir()
+
+ Remove this directory. The directory must be empty.
+
+
+.. method:: Path.symlink_to(target, target_is_directory=False)
+
+ Make this path a symbolic link to *target*. Under Windows,
+ *target_is_directory* must be True (default False) if the link's target
+ is a directory. Under POSIX, *target_is_directory*'s value is ignored.
+
+ >>> p = Path('mylink')
+ >>> p.symlink_to('setup.py')
+ >>> p.resolve()
+ PosixPath('/home/antoine/pathlib/setup.py')
+ >>> p.stat().st_size
+ 956
+ >>> p.lstat().st_size
+ 8
+
+ .. note::
+ The order of arguments (link, target) is the reverse
+ of :func:`os.symlink`'s.
+
+
+.. method:: Path.touch(mode=0o777, exist_ok=True)
+
+ Create a file at this given path. If *mode* is given, it is combined
+ with the process' ``umask`` value to determine the file mode and access
+ flags. If the file already exists, the function succeeds if *exist_ok*
+ is true (and its modification time is updated to the current time),
+ otherwise :exc:`OSError` is raised.
+
+
+.. method:: Path.unlink()
+
+ Remove this file or symbolic link. If the path points to a directory,
+ use :func:`Path.rmdir` instead.
+
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -93,6 +93,7 @@
* :mod:`asyncio`: New provisonal API for asynchronous IO (:pep:`3156`).
* :mod:`enum`: Support for enumeration types (:pep:`435`).
* :mod:`ensurepip`: Bootstrapping the pip installer (:pep:`453`).
+* :mod:`pathlib`: Object-oriented filesystem paths (:pep:`428`).
* :mod:`selectors`: High-level and efficient I/O multiplexing, built upon the
:mod:`select` module primitives.
* :mod:`statistics`: A basic numerically stable statistics library (:pep:`450`).
@@ -318,6 +319,23 @@
implemented by Ethan Furman.
+pathlib
+-------
+
+The new :mod:`pathlib` module offers classes representing filesystem paths
+with semantics appropriate for different operating systems. Path classes are
+divided between *pure paths*, which provide purely computational operations
+without I/O, and *concrete paths*, which inherit from pure paths but also
+provide I/O operations.
+
+For Python 3.4, this module is considered a :term:`provisional API`.
+
+.. seealso::
+
+ :pep:`428` - The pathlib module -- object-oriented filesystem paths
+ PEP written and implemented by Antoine Pitrou.
+
+
selectors
---------
diff --git a/Lib/pathlib.py b/Lib/pathlib.py
new file mode 100644
--- /dev/null
+++ b/Lib/pathlib.py
@@ -0,0 +1,1287 @@
+import fnmatch
+import functools
+import io
+import ntpath
+import os
+import posixpath
+import re
+import sys
+import time
+import weakref
+try:
+ import threading
+except ImportError:
+ import dummy_threading as threading
+
+from collections import Sequence, defaultdict
+from contextlib import contextmanager
+from errno import EINVAL, ENOENT
+from itertools import chain, count
+from operator import attrgetter
+from stat import S_ISDIR, S_ISLNK, S_ISREG, S_ISSOCK, S_ISBLK, S_ISCHR, S_ISFIFO
+from urllib.parse import quote as urlquote, quote_from_bytes as urlquote_from_bytes
+
+
+supports_symlinks = True
+try:
+ import nt
+except ImportError:
+ nt = None
+else:
+ if sys.getwindowsversion()[:2] >= (6, 0):
+ from nt import _getfinalpathname
+ else:
+ supports_symlinks = False
+ _getfinalpathname = None
+
+
+__all__ = [
+ "PurePath", "PurePosixPath", "PureWindowsPath",
+ "Path", "PosixPath", "WindowsPath",
+ ]
+
+#
+# Internals
+#
+
+def _is_wildcard_pattern(pat):
+ # Whether this pattern needs actual matching using fnmatch, or can
+ # be looked up directly as a file.
+ return "*" in pat or "?" in pat or "[" in pat
+
+
+class _Flavour(object):
+ """A flavour implements a particular (platform-specific) set of path
+ semantics."""
+
+ def __init__(self):
+ self.join = self.sep.join
+
+ def parse_parts(self, parts):
+ parsed = []
+ sep = self.sep
+ altsep = self.altsep
+ drv = root = ''
+ it = reversed(parts)
+ for part in it:
+ if not part:
+ continue
+ if altsep:
+ part = part.replace(altsep, sep)
+ drv, root, rel = self.splitroot(part)
+ if sep in rel:
+ for x in reversed(rel.split(sep)):
+ if x and x != '.':
+ parsed.append(sys.intern(x))
+ else:
+ if rel and rel != '.':
+ parsed.append(sys.intern(rel))
+ if drv or root:
+ if not drv:
+ # If no drive is present, try to find one in the previous
+ # parts. This makes the result of parsing e.g.
+ # ("C:", "/", "a") reasonably intuitive.
+ for part in it:
+ drv = self.splitroot(part)[0]
+ if drv:
+ break
+ break
+ if drv or root:
+ parsed.append(drv + root)
+ parsed.reverse()
+ return drv, root, parsed
+
+ def join_parsed_parts(self, drv, root, parts, drv2, root2, parts2):
+ """
+ Join the two paths represented by the respective
+ (drive, root, parts) tuples. Return a new (drive, root, parts) tuple.
+ """
+ if root2:
+ parts = parts2
+ root = root2
+ else:
+ parts = parts + parts2
+ # XXX raise error if drv and drv2 are different?
+ return drv2 or drv, root, parts
+
+
+class _WindowsFlavour(_Flavour):
+ # Reference for Windows paths can be found at
+ # http://msdn.microsoft.com/en-us/library/aa365247%28v=vs.85%29.aspx
+
+ sep = '\\'
+ altsep = '/'
+ has_drv = True
+ pathmod = ntpath
+
+ is_supported = (nt is not None)
+
+ drive_letters = (
+ set(chr(x) for x in range(ord('a'), ord('z') + 1)) |
+ set(chr(x) for x in range(ord('A'), ord('Z') + 1))
+ )
+ ext_namespace_prefix = '\\\\?\\'
+
+ reserved_names = (
+ {'CON', 'PRN', 'AUX', 'NUL'} |
+ {'COM%d' % i for i in range(1, 10)} |
+ {'LPT%d' % i for i in range(1, 10)}
+ )
+
+ # Interesting findings about extended paths:
+ # - '\\?\c:\a', '//?/c:\a' and '//?/c:/a' are all supported
+ # but '\\?\c:/a' is not
+ # - extended paths are always absolute; "relative" extended paths will
+ # fail.
+
+ def splitroot(self, part, sep=sep):
+ first = part[0:1]
+ second = part[1:2]
+ if (second == sep and first == sep):
+ # XXX extended paths should also disable the collapsing of "."
+ # components (according to MSDN docs).
+ prefix, part = self._split_extended_path(part)
+ first = part[0:1]
+ second = part[1:2]
+ else:
+ prefix = ''
+ third = part[2:3]
+ if (second == sep and first == sep and third != sep):
+ # is a UNC path:
+ # vvvvvvvvvvvvvvvvvvvvv root
+ # \\machine\mountpoint\directory\etc\...
+ # directory ^^^^^^^^^^^^^^
+ index = part.find(sep, 2)
+ if index != -1:
+ index2 = part.find(sep, index + 1)
+ # a UNC path can't have two slashes in a row
+ # (after the initial two)
+ if index2 != index + 1:
+ if index2 == -1:
+ index2 = len(part)
+ if prefix:
+ return prefix + part[1:index2], sep, part[index2+1:]
+ else:
+ return part[:index2], sep, part[index2+1:]
+ drv = root = ''
+ if second == ':' and first in self.drive_letters:
+ drv = part[:2]
+ part = part[2:]
+ first = third
+ if first == sep:
+ root = first
+ part = part.lstrip(sep)
+ return prefix + drv, root, part
+
+ def casefold(self, s):
+ return s.lower()
+
+ def casefold_parts(self, parts):
+ return [p.lower() for p in parts]
+
+ def resolve(self, path):
+ s = str(path)
+ if not s:
+ return os.getcwd()
+ if _getfinalpathname is not None:
+ return self._ext_to_normal(_getfinalpathname(s))
+ # Means fallback on absolute
+ return None
+
+ def _split_extended_path(self, s, ext_prefix=ext_namespace_prefix):
+ prefix = ''
+ if s.startswith(ext_prefix):
+ prefix = s[:4]
+ s = s[4:]
+ if s.startswith('UNC\\'):
+ prefix += s[:3]
+ s = '\\' + s[3:]
+ return prefix, s
+
+ def _ext_to_normal(self, s):
+ # Turn back an extended path into a normal DOS-like path
+ return self._split_extended_path(s)[1]
+
+ def is_reserved(self, parts):
+ # NOTE: the rules for reserved names seem somewhat complicated
+ # (e.g. r"..\NUL" is reserved but not r"foo\NUL").
+ # We err on the side of caution and return True for paths which are
+ # not considered reserved by Windows.
+ if not parts:
+ return False
+ if parts[0].startswith('\\\\'):
+ # UNC paths are never reserved
+ return False
+ return parts[-1].partition('.')[0].upper() in self.reserved_names
+
+ def make_uri(self, path):
+ # Under Windows, file URIs use the UTF-8 encoding.
+ drive = path.drive
+ if len(drive) == 2 and drive[1] == ':':
+ # It's a path on a local drive => 'file:///c:/a/b'
+ rest = path.as_posix()[2:].lstrip('/')
+ return 'file:///%s/%s' % (
+ drive, urlquote_from_bytes(rest.encode('utf-8')))
+ else:
+ # It's a path on a network drive => 'file://host/share/a/b'
+ return 'file:' + urlquote_from_bytes(path.as_posix().encode('utf-8'))
+
+
+class _PosixFlavour(_Flavour):
+ sep = '/'
+ altsep = ''
+ has_drv = False
+ pathmod = posixpath
+
+ is_supported = (os.name != 'nt')
+
+ def splitroot(self, part, sep=sep):
+ if part and part[0] == sep:
+ stripped_part = part.lstrip(sep)
+ # According to POSIX path resolution:
+ # http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap04.html#tag_04_11
+ # "A pathname that begins with two successive slashes may be
+ # interpreted in an implementation-defined manner, although more
+ # than two leading slashes shall be treated as a single slash".
+ if len(part) - len(stripped_part) == 2:
+ return '', sep * 2, stripped_part
+ else:
+ return '', sep, stripped_part
+ else:
+ return '', '', part
+
+ def casefold(self, s):
+ return s
+
+ def casefold_parts(self, parts):
+ return parts
+
+ def resolve(self, path):
+ sep = self.sep
+ def split(p):
+ return [x for x in p.split(sep) if x]
+ def absparts(p):
+ # Our own abspath(), since the posixpath one makes
+ # the mistake of "normalizing" the path without resolving the
+ # symlinks first.
+ if not p.startswith(sep):
+ return split(os.getcwd()) + split(p)
+ else:
+ return split(p)
+ parts = absparts(str(path))[::-1]
+ accessor = path._accessor
+ resolved = cur = ""
+ symlinks = {}
+ while parts:
+ part = parts.pop()
+ cur = resolved + sep + part
+ if cur in symlinks and symlinks[cur] <= len(parts):
+ # We've already seen the symlink and there's not less
+ # work to do than the last time.
+ raise RuntimeError("Symlink loop from %r" % cur)
+ try:
+ target = accessor.readlink(cur)
+ except OSError as e:
+ if e.errno != EINVAL:
+ raise
+ # Not a symlink
+ resolved = cur
+ else:
+ # Take note of remaining work from this symlink
+ symlinks[cur] = len(parts)
+ if target.startswith(sep):
+ # Symlink points to absolute path
+ resolved = ""
+ parts.extend(split(target)[::-1])
+ return resolved or sep
+
+ def is_reserved(self, parts):
+ return False
+
+ def make_uri(self, path):
+ # We represent the path using the local filesystem encoding,
+ # for portability to other applications.
+ bpath = bytes(path)
+ return 'file://' + urlquote_from_bytes(bpath)
+
+
+_windows_flavour = _WindowsFlavour()
+_posix_flavour = _PosixFlavour()
+
+
+class _Accessor:
+ """An accessor implements a particular (system-specific or not) way of
+ accessing paths on the filesystem."""
+
+
+class _NormalAccessor(_Accessor):
+
+ def _wrap_strfunc(strfunc):
+ @functools.wraps(strfunc)
+ def wrapped(pathobj, *args):
+ return strfunc(str(pathobj), *args)
+ return staticmethod(wrapped)
+
+ def _wrap_binary_strfunc(strfunc):
+ @functools.wraps(strfunc)
+ def wrapped(pathobjA, pathobjB, *args):
+ return strfunc(str(pathobjA), str(pathobjB), *args)
+ return staticmethod(wrapped)
+
+ stat = _wrap_strfunc(os.stat)
+
+ lstat = _wrap_strfunc(os.lstat)
+
+ open = _wrap_strfunc(os.open)
+
+ listdir = _wrap_strfunc(os.listdir)
+
+ chmod = _wrap_strfunc(os.chmod)
+
+ if hasattr(os, "lchmod"):
+ lchmod = _wrap_strfunc(os.lchmod)
+ else:
+ def lchmod(self, pathobj, mode):
+ raise NotImplementedError("lchmod() not available on this system")
+
+ mkdir = _wrap_strfunc(os.mkdir)
+
+ unlink = _wrap_strfunc(os.unlink)
+
+ rmdir = _wrap_strfunc(os.rmdir)
+
+ rename = _wrap_binary_strfunc(os.rename)
+
+ replace = _wrap_binary_strfunc(os.replace)
+
+ if nt:
+ if supports_symlinks:
+ symlink = _wrap_binary_strfunc(os.symlink)
+ else:
+ def symlink(a, b, target_is_directory):
+ raise NotImplementedError("symlink() not available on this system")
+ else:
+ # Under POSIX, os.symlink() takes two args
+ @staticmethod
+ def symlink(a, b, target_is_directory):
+ return os.symlink(str(a), str(b))
+
+ utime = _wrap_strfunc(os.utime)
+
+ # Helper for resolve()
+ def readlink(self, path):
+ return os.readlink(path)
+
+
+_normal_accessor = _NormalAccessor()
+
+
+#
+# Globbing helpers
+#
+
+ at contextmanager
+def _cached(func):
+ try:
+ func.__cached__
+ yield func
+ except AttributeError:
+ cache = {}
+ def wrapper(*args):
+ try:
+ return cache[args]
+ except KeyError:
+ value = cache[args] = func(*args)
+ return value
+ wrapper.__cached__ = True
+ try:
+ yield wrapper
+ finally:
+ cache.clear()
+
+def _make_selector(pattern_parts):
+ pat = pattern_parts[0]
+ child_parts = pattern_parts[1:]
+ if pat == '**':
+ cls = _RecursiveWildcardSelector
+ elif '**' in pat:
+ raise ValueError("Invalid pattern: '**' can only be an entire path component")
+ elif _is_wildcard_pattern(pat):
+ cls = _WildcardSelector
+ else:
+ cls = _PreciseSelector
+ return cls(pat, child_parts)
+
+if hasattr(functools, "lru_cache"):
+ _make_selector = functools.lru_cache()(_make_selector)
+
+
+class _Selector:
+ """A selector matches a specific glob pattern part against the children
+ of a given path."""
+
+ def __init__(self, child_parts):
+ self.child_parts = child_parts
+ if child_parts:
+ self.successor = _make_selector(child_parts)
+ else:
+ self.successor = _TerminatingSelector()
+
+ def select_from(self, parent_path):
+ """Iterate over all child paths of `parent_path` matched by this
+ selector. This can contain parent_path itself."""
+ path_cls = type(parent_path)
+ is_dir = path_cls.is_dir
+ exists = path_cls.exists
+ listdir = parent_path._accessor.listdir
+ return self._select_from(parent_path, is_dir, exists, listdir)
+
+
+class _TerminatingSelector:
+
+ def _select_from(self, parent_path, is_dir, exists, listdir):
+ yield parent_path
+
+
+class _PreciseSelector(_Selector):
+
+ def __init__(self, name, child_parts):
+ self.name = name
+ _Selector.__init__(self, child_parts)
+
+ def _select_from(self, parent_path, is_dir, exists, listdir):
+ if not is_dir(parent_path):
+ return
+ path = parent_path._make_child_relpath(self.name)
+ if exists(path):
+ for p in self.successor._select_from(path, is_dir, exists, listdir):
+ yield p
+
+
+class _WildcardSelector(_Selector):
+
+ def __init__(self, pat, child_parts):
+ self.pat = re.compile(fnmatch.translate(pat))
+ _Selector.__init__(self, child_parts)
+
+ def _select_from(self, parent_path, is_dir, exists, listdir):
+ if not is_dir(parent_path):
+ return
+ cf = parent_path._flavour.casefold
+ for name in listdir(parent_path):
+ casefolded = cf(name)
+ if self.pat.match(casefolded):
+ path = parent_path._make_child_relpath(name)
+ for p in self.successor._select_from(path, is_dir, exists, listdir):
+ yield p
+
+
+class _RecursiveWildcardSelector(_Selector):
+
+ def __init__(self, pat, child_parts):
+ _Selector.__init__(self, child_parts)
+
+ def _iterate_directories(self, parent_path, is_dir, listdir):
+ yield parent_path
+ for name in listdir(parent_path):
+ path = parent_path._make_child_relpath(name)
+ if is_dir(path):
+ for p in self._iterate_directories(path, is_dir, listdir):
+ yield p
+
+ def _select_from(self, parent_path, is_dir, exists, listdir):
+ if not is_dir(parent_path):
+ return
+ with _cached(listdir) as listdir:
+ yielded = set()
+ try:
+ successor_select = self.successor._select_from
+ for starting_point in self._iterate_directories(parent_path, is_dir, listdir):
+ for p in successor_select(starting_point, is_dir, exists, listdir):
+ if p not in yielded:
+ yield p
+ yielded.add(p)
+ finally:
+ yielded.clear()
+
+
+#
+# Public API
+#
+
+class _PathParents(Sequence):
+ """This object provides sequence-like access to the logical ancestors
+ of a path. Don't try to construct it yourself."""
+ __slots__ = ('_pathcls', '_drv', '_root', '_parts')
+
+ def __init__(self, path):
+ # We don't store the instance to avoid reference cycles
+ self._pathcls = type(path)
+ self._drv = path._drv
+ self._root = path._root
+ self._parts = path._parts
+
+ def __len__(self):
+ if self._drv or self._root:
+ return len(self._parts) - 1
+ else:
+ return len(self._parts)
+
+ def __getitem__(self, idx):
+ if idx < 0 or idx >= len(self):
+ raise IndexError(idx)
+ return self._pathcls._from_parsed_parts(self._drv, self._root,
+ self._parts[:-idx - 1])
+
+ def __repr__(self):
+ return "<{}.parents>".format(self._pathcls.__name__)
+
+
+class PurePath(object):
+ """PurePath represents a filesystem path and offers operations which
+ don't imply any actual filesystem I/O. Depending on your system,
+ instantiating a PurePath will return either a PurePosixPath or a
+ PureWindowsPath object. You can also instantiate either of these classes
+ directly, regardless of your system.
+ """
+ __slots__ = (
+ '_drv', '_root', '_parts',
+ '_str', '_hash', '_pparts', '_cached_cparts',
+ )
+
+ def __new__(cls, *args):
+ """Construct a PurePath from one or several strings and or existing
+ PurePath objects. The strings and path objects are combined so as
+ to yield a canonicalized path, which is incorporated into the
+ new PurePath object.
+ """
+ if cls is PurePath:
+ cls = PureWindowsPath if os.name == 'nt' else PurePosixPath
+ return cls._from_parts(args)
+
+ def __reduce__(self):
+ # Using the parts tuple helps share interned path parts
+ # when pickling related paths.
+ return (self.__class__, tuple(self._parts))
+
+ @classmethod
+ def _parse_args(cls, args):
+ # This is useful when you don't want to create an instance, just
+ # canonicalize some constructor arguments.
+ parts = []
+ for a in args:
+ if isinstance(a, PurePath):
+ parts += a._parts
+ elif isinstance(a, str):
+ # Assuming a str
+ parts.append(a)
+ else:
+ raise TypeError(
+ "argument should be a path or str object, not %r"
+ % type(a))
+ return cls._flavour.parse_parts(parts)
+
+ @classmethod
+ def _from_parts(cls, args, init=True):
+ # We need to call _parse_args on the instance, so as to get the
+ # right flavour.
+ self = object.__new__(cls)
+ drv, root, parts = self._parse_args(args)
+ self._drv = drv
+ self._root = root
+ self._parts = parts
+ if init:
+ self._init()
+ return self
+
+ @classmethod
+ def _from_parsed_parts(cls, drv, root, parts, init=True):
+ self = object.__new__(cls)
+ self._drv = drv
+ self._root = root
+ self._parts = parts
+ if init:
+ self._init()
+ return self
+
+ @classmethod
+ def _format_parsed_parts(cls, drv, root, parts):
+ if drv or root:
+ return drv + root + cls._flavour.join(parts[1:])
+ else:
+ return cls._flavour.join(parts)
+
+ def _init(self):
+ # Overriden in concrete Path
+ pass
+
+ def _make_child(self, args):
+ drv, root, parts = self._parse_args(args)
+ drv, root, parts = self._flavour.join_parsed_parts(
+ self._drv, self._root, self._parts, drv, root, parts)
+ return self._from_parsed_parts(drv, root, parts)
+
+ def __str__(self):
+ """Return the string representation of the path, suitable for
+ passing to system calls."""
+ try:
+ return self._str
+ except AttributeError:
+ self._str = self._format_parsed_parts(self._drv, self._root,
+ self._parts) or '.'
+ return self._str
+
+ def as_posix(self):
+ """Return the string representation of the path with forward (/)
+ slashes."""
+ f = self._flavour
+ return str(self).replace(f.sep, '/')
+
+ def __bytes__(self):
+ """Return the bytes representation of the path. This is only
+ recommended to use under Unix."""
+ return os.fsencode(str(self))
+
+ def __repr__(self):
+ return "{}({!r})".format(self.__class__.__name__, self.as_posix())
+
+ def as_uri(self):
+ """Return the path as a 'file' URI."""
+ if not self.is_absolute():
+ raise ValueError("relative path can't be expressed as a file URI")
+ return self._flavour.make_uri(self)
+
+ @property
+ def _cparts(self):
+ # Cached casefolded parts, for hashing and comparison
+ try:
+ return self._cached_cparts
+ except AttributeError:
+ self._cached_cparts = self._flavour.casefold_parts(self._parts)
+ return self._cached_cparts
+
+ def __eq__(self, other):
+ if not isinstance(other, PurePath):
+ return NotImplemented
+ return self._cparts == other._cparts and self._flavour is other._flavour
+
+ def __ne__(self, other):
+ return not self == other
+
+ def __hash__(self):
+ try:
+ return self._hash
+ except AttributeError:
+ self._hash = hash(tuple(self._cparts))
+ return self._hash
+
+ def __lt__(self, other):
+ if not isinstance(other, PurePath) or self._flavour is not other._flavour:
+ return NotImplemented
+ return self._cparts < other._cparts
+
+ def __le__(self, other):
+ if not isinstance(other, PurePath) or self._flavour is not other._flavour:
+ return NotImplemented
+ return self._cparts <= other._cparts
+
+ def __gt__(self, other):
+ if not isinstance(other, PurePath) or self._flavour is not other._flavour:
+ return NotImplemented
+ return self._cparts > other._cparts
+
+ def __ge__(self, other):
+ if not isinstance(other, PurePath) or self._flavour is not other._flavour:
+ return NotImplemented
+ return self._cparts >= other._cparts
+
+ drive = property(attrgetter('_drv'),
+ doc="""The drive prefix (letter or UNC path), if any.""")
+
+ root = property(attrgetter('_root'),
+ doc="""The root of the path, if any.""")
+
+ @property
+ def anchor(self):
+ """The concatenation of the drive and root, or ''."""
+ anchor = self._drv + self._root
+ return anchor
+
+ @property
+ def name(self):
+ """The final path component, if any."""
+ parts = self._parts
+ if len(parts) == (1 if (self._drv or self._root) else 0):
+ return ''
+ return parts[-1]
+
+ @property
+ def suffix(self):
+ """The final component's last suffix, if any."""
+ name = self.name
+ i = name.rfind('.')
+ if 0 < i < len(name) - 1:
+ return name[i:]
+ else:
+ return ''
+
+ @property
+ def suffixes(self):
+ """A list of the final component's suffixes, if any."""
+ name = self.name
+ if name.endswith('.'):
+ return []
+ name = name.lstrip('.')
+ return ['.' + suffix for suffix in name.split('.')[1:]]
+
+ @property
+ def stem(self):
+ """The final path component, minus its last suffix."""
+ name = self.name
+ i = name.rfind('.')
+ if 0 < i < len(name) - 1:
+ return name[:i]
+ else:
+ return name
+
+ def with_name(self, name):
+ """Return a new path with the file name changed."""
+ if not self.name:
+ raise ValueError("%r has an empty name" % (self,))
+ return self._from_parsed_parts(self._drv, self._root,
+ self._parts[:-1] + [name])
+
+ def with_suffix(self, suffix):
+ """Return a new path with the file suffix changed (or added, if none)."""
+ # XXX if suffix is None, should the current suffix be removed?
+ name = self.name
+ if not name:
+ raise ValueError("%r has an empty name" % (self,))
+ old_suffix = self.suffix
+ if not old_suffix:
+ name = name + suffix
+ else:
+ name = name[:-len(old_suffix)] + suffix
+ return self._from_parsed_parts(self._drv, self._root,
+ self._parts[:-1] + [name])
+
+ def relative_to(self, *other):
+ """Return the relative path to another path identified by the passed
+ arguments. If the operation is not possible (because this is not
+ a subpath of the other path), raise ValueError.
+ """
+ # For the purpose of this method, drive and root are considered
+ # separate parts, i.e.:
+ # Path('c:/').relative_to('c:') gives Path('/')
+ # Path('c:/').relative_to('/') raise ValueError
+ if not other:
+ raise TypeError("need at least one argument")
+ parts = self._parts
+ drv = self._drv
+ root = self._root
+ if drv or root:
+ if root:
+ abs_parts = [drv, root] + parts[1:]
+ else:
+ abs_parts = [drv] + parts[1:]
+ else:
+ abs_parts = parts
+ to_drv, to_root, to_parts = self._parse_args(other)
+ if to_drv or to_root:
+ if to_root:
+ to_abs_parts = [to_drv, to_root] + to_parts[1:]
+ else:
+ to_abs_parts = [to_drv] + to_parts[1:]
+ else:
+ to_abs_parts = to_parts
+ n = len(to_abs_parts)
+ if n == 0 and (drv or root) or abs_parts[:n] != to_abs_parts:
+ formatted = self._format_parsed_parts(to_drv, to_root, to_parts)
+ raise ValueError("{!r} does not start with {!r}"
+ .format(str(self), str(formatted)))
+ return self._from_parsed_parts('', '', abs_parts[n:])
+
+ @property
+ def parts(self):
+ """An object providing sequence-like access to the
+ components in the filesystem path."""
+ # We cache the tuple to avoid building a new one each time .parts
+ # is accessed. XXX is this necessary?
+ try:
+ return self._pparts
+ except AttributeError:
+ self._pparts = tuple(self._parts)
+ return self._pparts
+
+ def joinpath(self, *args):
+ """Combine this path with one or several arguments, and return a
+ new path representing either a subpath (if all arguments are relative
+ paths) or a totally different path (if one of the arguments is
+ anchored).
+ """
+ return self._make_child(args)
+
+ def __truediv__(self, key):
+ return self._make_child((key,))
+
+ def __rtruediv__(self, key):
+ return self._from_parts([key] + self._parts)
+
+ @property
+ def parent(self):
+ """The logical parent of the path."""
+ drv = self._drv
+ root = self._root
+ parts = self._parts
+ if len(parts) == 1 and (drv or root):
+ return self
+ return self._from_parsed_parts(drv, root, parts[:-1])
+
+ @property
+ def parents(self):
+ """A sequence of this path's logical parents."""
+ return _PathParents(self)
+
+ def is_absolute(self):
+ """True if the path is absolute (has both a root and, if applicable,
+ a drive)."""
+ if not self._root:
+ return False
+ return not self._flavour.has_drv or bool(self._drv)
+
+ def is_reserved(self):
+ """Return True if the path contains one of the special names reserved
+ by the system, if any."""
+ return self._flavour.is_reserved(self._parts)
+
+ def match(self, path_pattern):
+ """
+ Return True if this path matches the given pattern.
+ """
+ cf = self._flavour.casefold
+ path_pattern = cf(path_pattern)
+ drv, root, pat_parts = self._flavour.parse_parts((path_pattern,))
+ if not pat_parts:
+ raise ValueError("empty pattern")
+ if drv and drv != cf(self._drv):
+ return False
+ if root and root != cf(self._root):
+ return False
+ parts = self._cparts
+ if drv or root:
+ if len(pat_parts) != len(parts):
+ return False
+ pat_parts = pat_parts[1:]
+ elif len(pat_parts) > len(parts):
+ return False
+ for part, pat in zip(reversed(parts), reversed(pat_parts)):
+ if not fnmatch.fnmatchcase(part, pat):
+ return False
+ return True
+
+
+class PurePosixPath(PurePath):
+ _flavour = _posix_flavour
+ __slots__ = ()
+
+
+class PureWindowsPath(PurePath):
+ _flavour = _windows_flavour
+ __slots__ = ()
+
+
+# Filesystem-accessing classes
+
+
+class Path(PurePath):
+ __slots__ = (
+ '_accessor',
+ '_closed',
+ )
+
+ def __new__(cls, *args, **kwargs):
+ if cls is Path:
+ cls = WindowsPath if os.name == 'nt' else PosixPath
+ self = cls._from_parts(args, init=False)
+ if not self._flavour.is_supported:
+ raise NotImplementedError("cannot instantiate %r on your system"
+ % (cls.__name__,))
+ self._init()
+ return self
+
+ def _init(self,
+ # Private non-constructor arguments
+ template=None,
+ ):
+ self._closed = False
+ if template is not None:
+ self._accessor = template._accessor
+ else:
+ self._accessor = _normal_accessor
+
+ def _make_child_relpath(self, part):
+ # This is an optimization used for dir walking. `part` must be
+ # a single part relative to this path.
+ parts = self._parts + [part]
+ return self._from_parsed_parts(self._drv, self._root, parts)
+
+ def __enter__(self):
+ if self._closed:
+ self._raise_closed()
+ return self
+
+ def __exit__(self, t, v, tb):
+ self._closed = True
+
+ def _raise_closed(self):
+ raise ValueError("I/O operation on closed path")
+
+ def _opener(self, name, flags, mode=0o666):
+ # A stub for the opener argument to built-in open()
+ return self._accessor.open(self, flags, mode)
+
+ # Public API
+
+ @classmethod
+ def cwd(cls):
+ """Return a new path pointing to the current working directory
+ (as returned by os.getcwd()).
+ """
+ return cls(os.getcwd())
+
+ def iterdir(self):
+ """Iterate over the files in this directory. Does not yield any
+ result for the special paths '.' and '..'.
+ """
+ if self._closed:
+ self._raise_closed()
+ for name in self._accessor.listdir(self):
+ if name in {'.', '..'}:
+ # Yielding a path object for these makes little sense
+ continue
+ yield self._make_child_relpath(name)
+ if self._closed:
+ self._raise_closed()
+
+ def glob(self, pattern):
+ """Iterate over this subtree and yield all existing files (of any
+ kind, including directories) matching the given pattern.
+ """
+ pattern = self._flavour.casefold(pattern)
+ drv, root, pattern_parts = self._flavour.parse_parts((pattern,))
+ if drv or root:
+ raise NotImplementedError("Non-relative patterns are unsupported")
+ selector = _make_selector(tuple(pattern_parts))
+ for p in selector.select_from(self):
+ yield p
+
+ def rglob(self, pattern):
+ """Recursively yield all existing files (of any kind, including
+ directories) matching the given pattern, anywhere in this subtree.
+ """
+ pattern = self._flavour.casefold(pattern)
+ drv, root, pattern_parts = self._flavour.parse_parts((pattern,))
+ if drv or root:
+ raise NotImplementedError("Non-relative patterns are unsupported")
+ selector = _make_selector(("**",) + tuple(pattern_parts))
+ for p in selector.select_from(self):
+ yield p
+
+ def absolute(self):
+ """Return an absolute version of this path. This function works
+ even if the path doesn't point to anything.
+
+ No normalization is done, i.e. all '.' and '..' will be kept along.
+ Use resolve() to get the canonical path to a file.
+ """
+ # XXX untested yet!
+ if self._closed:
+ self._raise_closed()
+ if self.is_absolute():
+ return self
+ # FIXME this must defer to the specific flavour (and, under Windows,
+ # use nt._getfullpathname())
+ obj = self._from_parts([os.getcwd()] + self._parts, init=False)
+ obj._init(template=self)
+ return obj
+
+ def resolve(self):
+ """
+ Make the path absolute, resolving all symlinks on the way and also
+ normalizing it (for example turning slashes into backslashes under
+ Windows).
+ """
+ if self._closed:
+ self._raise_closed()
+ s = self._flavour.resolve(self)
+ if s is None:
+ # No symlink resolution => for consistency, raise an error if
+ # the path doesn't exist or is forbidden
+ self.stat()
+ s = str(self.absolute())
+ # Now we have no symlinks in the path, it's safe to normalize it.
+ normed = self._flavour.pathmod.normpath(s)
+ obj = self._from_parts((normed,), init=False)
+ obj._init(template=self)
+ return obj
+
+ def stat(self):
+ """
+ Return the result of the stat() system call on this path, like
+ os.stat() does.
+ """
+ return self._accessor.stat(self)
+
+ def owner(self):
+ """
+ Return the login name of the file owner.
+ """
+ import pwd
+ return pwd.getpwuid(self.stat().st_uid).pw_name
+
+ def group(self):
+ """
+ Return the group name of the file gid.
+ """
+ import grp
+ return grp.getgrgid(self.stat().st_gid).gr_name
+
+ def _raw_open(self, flags, mode=0o777):
+ """
+ Open the file pointed by this path and return a file descriptor,
+ as os.open() does.
+ """
+ if self._closed:
+ self._raise_closed()
+ return self._accessor.open(self, flags, mode)
+
+ def open(self, mode='r', buffering=-1, encoding=None,
+ errors=None, newline=None):
+ """
+ Open the file pointed by this path and return a file object, as
+ the built-in open() function does.
+ """
+ if self._closed:
+ self._raise_closed()
+ return io.open(str(self), mode, buffering, encoding, errors, newline,
+ opener=self._opener)
+
+ def touch(self, mode=0o666, exist_ok=True):
+ """
+ Create this file with the given access mode, if it doesn't exist.
+ """
+ if self._closed:
+ self._raise_closed()
+ if exist_ok:
+ # First try to bump modification time
+ # Implementation note: GNU touch uses the UTIME_NOW option of
+ # the utimensat() / futimens() functions.
+ t = time.time()
+ try:
+ self._accessor.utime(self, (t, t))
+ except OSError:
+ # Avoid exception chaining
+ pass
+ else:
+ return
+ flags = os.O_CREAT | os.O_WRONLY
+ if not exist_ok:
+ flags |= os.O_EXCL
+ fd = self._raw_open(flags, mode)
+ os.close(fd)
+
+ def mkdir(self, mode=0o777, parents=False):
+ if self._closed:
+ self._raise_closed()
+ if not parents:
+ self._accessor.mkdir(self, mode)
+ else:
+ try:
+ self._accessor.mkdir(self, mode)
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ self.parent.mkdir(mode, True)
+ self._accessor.mkdir(self, mode)
+
+ def chmod(self, mode):
+ """
+ Change the permissions of the path, like os.chmod().
+ """
+ if self._closed:
+ self._raise_closed()
+ self._accessor.chmod(self, mode)
+
+ def lchmod(self, mode):
+ """
+ Like chmod(), except if the path points to a symlink, the symlink's
+ permissions are changed, rather than its target's.
+ """
+ if self._closed:
+ self._raise_closed()
+ self._accessor.lchmod(self, mode)
+
+ def unlink(self):
+ """
+ Remove this file or link.
+ If the path is a directory, use rmdir() instead.
+ """
+ if self._closed:
+ self._raise_closed()
+ self._accessor.unlink(self)
+
+ def rmdir(self):
+ """
+ Remove this directory. The directory must be empty.
+ """
+ if self._closed:
+ self._raise_closed()
+ self._accessor.rmdir(self)
+
+ def lstat(self):
+ """
+ Like stat(), except if the path points to a symlink, the symlink's
+ status information is returned, rather than its target's.
+ """
+ if self._closed:
+ self._raise_closed()
+ return self._accessor.lstat(self)
+
+ def rename(self, target):
+ """
+ Rename this path to the given path.
+ """
+ if self._closed:
+ self._raise_closed()
+ self._accessor.rename(self, target)
+
+ def replace(self, target):
+ """
+ Rename this path to the given path, clobbering the existing
+ destination if it exists.
+ """
+ if self._closed:
+ self._raise_closed()
+ self._accessor.replace(self, target)
+
+ def symlink_to(self, target, target_is_directory=False):
+ """
+ Make this path a symlink pointing to the given path.
+ Note the order of arguments (self, target) is the reverse of os.symlink's.
+ """
+ if self._closed:
+ self._raise_closed()
+ self._accessor.symlink(target, self, target_is_directory)
+
+ # Convenience functions for querying the stat results
+
+ def exists(self):
+ """
+ Whether this path exists.
+ """
+ try:
+ self.stat()
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ return False
+ return True
+
+ def is_dir(self):
+ """
+ Whether this path is a directory.
+ """
+ try:
+ return S_ISDIR(self.stat().st_mode)
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ # Path doesn't exist or is a broken symlink
+ # (see https://bitbucket.org/pitrou/pathlib/issue/12/)
+ return False
+
+ def is_file(self):
+ """
+ Whether this path is a regular file (also True for symlinks pointing
+ to regular files).
+ """
+ try:
+ return S_ISREG(self.stat().st_mode)
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ # Path doesn't exist or is a broken symlink
+ # (see https://bitbucket.org/pitrou/pathlib/issue/12/)
+ return False
+
+ def is_symlink(self):
+ """
+ Whether this path is a symbolic link.
+ """
+ try:
+ return S_ISLNK(self.lstat().st_mode)
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ # Path doesn't exist
+ return False
+
+ def is_block_device(self):
+ """
+ Whether this path is a block device.
+ """
+ try:
+ return S_ISBLK(self.stat().st_mode)
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ # Path doesn't exist or is a broken symlink
+ # (see https://bitbucket.org/pitrou/pathlib/issue/12/)
+ return False
+
+ def is_char_device(self):
+ """
+ Whether this path is a character device.
+ """
+ try:
+ return S_ISCHR(self.stat().st_mode)
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ # Path doesn't exist or is a broken symlink
+ # (see https://bitbucket.org/pitrou/pathlib/issue/12/)
+ return False
+
+ def is_fifo(self):
+ """
+ Whether this path is a FIFO.
+ """
+ try:
+ return S_ISFIFO(self.stat().st_mode)
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ # Path doesn't exist or is a broken symlink
+ # (see https://bitbucket.org/pitrou/pathlib/issue/12/)
+ return False
+
+ def is_socket(self):
+ """
+ Whether this path is a socket.
+ """
+ try:
+ return S_ISSOCK(self.stat().st_mode)
+ except OSError as e:
+ if e.errno != ENOENT:
+ raise
+ # Path doesn't exist or is a broken symlink
+ # (see https://bitbucket.org/pitrou/pathlib/issue/12/)
+ return False
+
+
+class PosixPath(Path, PurePosixPath):
+ __slots__ = ()
+
+class WindowsPath(Path, PureWindowsPath):
+ __slots__ = ()
+
diff --git a/Lib/test/test_pathlib.py b/Lib/test/test_pathlib.py
new file mode 100755
--- /dev/null
+++ b/Lib/test/test_pathlib.py
@@ -0,0 +1,1639 @@
+import collections
+import io
+import os
+import errno
+import pathlib
+import pickle
+import shutil
+import socket
+import stat
+import sys
+import tempfile
+import unittest
+from contextlib import contextmanager
+
+from test import support
+TESTFN = support.TESTFN
+
+try:
+ import grp, pwd
+except ImportError:
+ grp = pwd = None
+
+
+class _BaseFlavourTest(object):
+
+ def _check_parse_parts(self, arg, expected):
+ f = self.flavour.parse_parts
+ sep = self.flavour.sep
+ altsep = self.flavour.altsep
+ actual = f([x.replace('/', sep) for x in arg])
+ self.assertEqual(actual, expected)
+ if altsep:
+ actual = f([x.replace('/', altsep) for x in arg])
+ self.assertEqual(actual, expected)
+
+ def test_parse_parts_common(self):
+ check = self._check_parse_parts
+ sep = self.flavour.sep
+ # Unanchored parts
+ check([], ('', '', []))
+ check(['a'], ('', '', ['a']))
+ check(['a/'], ('', '', ['a']))
+ check(['a', 'b'], ('', '', ['a', 'b']))
+ # Expansion
+ check(['a/b'], ('', '', ['a', 'b']))
+ check(['a/b/'], ('', '', ['a', 'b']))
+ check(['a', 'b/c', 'd'], ('', '', ['a', 'b', 'c', 'd']))
+ # Collapsing and stripping excess slashes
+ check(['a', 'b//c', 'd'], ('', '', ['a', 'b', 'c', 'd']))
+ check(['a', 'b/c/', 'd'], ('', '', ['a', 'b', 'c', 'd']))
+ # Eliminating standalone dots
+ check(['.'], ('', '', []))
+ check(['.', '.', 'b'], ('', '', ['b']))
+ check(['a', '.', 'b'], ('', '', ['a', 'b']))
+ check(['a', '.', '.'], ('', '', ['a']))
+ # The first part is anchored
+ check(['/a/b'], ('', sep, [sep, 'a', 'b']))
+ check(['/a', 'b'], ('', sep, [sep, 'a', 'b']))
+ check(['/a/', 'b'], ('', sep, [sep, 'a', 'b']))
+ # Ignoring parts before an anchored part
+ check(['a', '/b', 'c'], ('', sep, [sep, 'b', 'c']))
+ check(['a', '/b', '/c'], ('', sep, [sep, 'c']))
+
+
+class PosixFlavourTest(_BaseFlavourTest, unittest.TestCase):
+ flavour = pathlib._posix_flavour
+
+ def test_parse_parts(self):
+ check = self._check_parse_parts
+ # Collapsing of excess leading slashes, except for the double-slash
+ # special case.
+ check(['//a', 'b'], ('', '//', ['//', 'a', 'b']))
+ check(['///a', 'b'], ('', '/', ['/', 'a', 'b']))
+ check(['////a', 'b'], ('', '/', ['/', 'a', 'b']))
+ # Paths which look like NT paths aren't treated specially
+ check(['c:a'], ('', '', ['c:a']))
+ check(['c:\\a'], ('', '', ['c:\\a']))
+ check(['\\a'], ('', '', ['\\a']))
+
+ def test_splitroot(self):
+ f = self.flavour.splitroot
+ self.assertEqual(f(''), ('', '', ''))
+ self.assertEqual(f('a'), ('', '', 'a'))
+ self.assertEqual(f('a/b'), ('', '', 'a/b'))
+ self.assertEqual(f('a/b/'), ('', '', 'a/b/'))
+ self.assertEqual(f('/a'), ('', '/', 'a'))
+ self.assertEqual(f('/a/b'), ('', '/', 'a/b'))
+ self.assertEqual(f('/a/b/'), ('', '/', 'a/b/'))
+ # The root is collapsed when there are redundant slashes
+ # except when there are exactly two leading slashes, which
+ # is a special case in POSIX.
+ self.assertEqual(f('//a'), ('', '//', 'a'))
+ self.assertEqual(f('///a'), ('', '/', 'a'))
+ self.assertEqual(f('///a/b'), ('', '/', 'a/b'))
+ # Paths which look like NT paths aren't treated specially
+ self.assertEqual(f('c:/a/b'), ('', '', 'c:/a/b'))
+ self.assertEqual(f('\\/a/b'), ('', '', '\\/a/b'))
+ self.assertEqual(f('\\a\\b'), ('', '', '\\a\\b'))
+
+
+class NTFlavourTest(_BaseFlavourTest, unittest.TestCase):
+ flavour = pathlib._windows_flavour
+
+ def test_parse_parts(self):
+ check = self._check_parse_parts
+ # First part is anchored
+ check(['c:'], ('c:', '', ['c:']))
+ check(['c:\\'], ('c:', '\\', ['c:\\']))
+ check(['\\'], ('', '\\', ['\\']))
+ check(['c:a'], ('c:', '', ['c:', 'a']))
+ check(['c:\\a'], ('c:', '\\', ['c:\\', 'a']))
+ check(['\\a'], ('', '\\', ['\\', 'a']))
+ # UNC paths
+ check(['\\\\a\\b'], ('\\\\a\\b', '\\', ['\\\\a\\b\\']))
+ check(['\\\\a\\b\\'], ('\\\\a\\b', '\\', ['\\\\a\\b\\']))
+ check(['\\\\a\\b\\c'], ('\\\\a\\b', '\\', ['\\\\a\\b\\', 'c']))
+ # Second part is anchored, so that the first part is ignored
+ check(['a', 'Z:b', 'c'], ('Z:', '', ['Z:', 'b', 'c']))
+ check(['a', 'Z:\\b', 'c'], ('Z:', '\\', ['Z:\\', 'b', 'c']))
+ check(['a', '\\b', 'c'], ('', '\\', ['\\', 'b', 'c']))
+ # UNC paths
+ check(['a', '\\\\b\\c', 'd'], ('\\\\b\\c', '\\', ['\\\\b\\c\\', 'd']))
+ # Collapsing and stripping excess slashes
+ check(['a', 'Z:\\\\b\\\\c\\', 'd\\'], ('Z:', '\\', ['Z:\\', 'b', 'c', 'd']))
+ # UNC paths
+ check(['a', '\\\\b\\c\\\\', 'd'], ('\\\\b\\c', '\\', ['\\\\b\\c\\', 'd']))
+ # Extended paths
+ check(['\\\\?\\c:\\'], ('\\\\?\\c:', '\\', ['\\\\?\\c:\\']))
+ check(['\\\\?\\c:\\a'], ('\\\\?\\c:', '\\', ['\\\\?\\c:\\', 'a']))
+ # Extended UNC paths (format is "\\?\UNC\server\share")
+ check(['\\\\?\\UNC\\b\\c'], ('\\\\?\\UNC\\b\\c', '\\', ['\\\\?\\UNC\\b\\c\\']))
+ check(['\\\\?\\UNC\\b\\c\\d'], ('\\\\?\\UNC\\b\\c', '\\', ['\\\\?\\UNC\\b\\c\\', 'd']))
+
+ def test_splitroot(self):
+ f = self.flavour.splitroot
+ self.assertEqual(f(''), ('', '', ''))
+ self.assertEqual(f('a'), ('', '', 'a'))
+ self.assertEqual(f('a\\b'), ('', '', 'a\\b'))
+ self.assertEqual(f('\\a'), ('', '\\', 'a'))
+ self.assertEqual(f('\\a\\b'), ('', '\\', 'a\\b'))
+ self.assertEqual(f('c:a\\b'), ('c:', '', 'a\\b'))
+ self.assertEqual(f('c:\\a\\b'), ('c:', '\\', 'a\\b'))
+ # Redundant slashes in the root are collapsed
+ self.assertEqual(f('\\\\a'), ('', '\\', 'a'))
+ self.assertEqual(f('\\\\\\a/b'), ('', '\\', 'a/b'))
+ self.assertEqual(f('c:\\\\a'), ('c:', '\\', 'a'))
+ self.assertEqual(f('c:\\\\\\a/b'), ('c:', '\\', 'a/b'))
+ # Valid UNC paths
+ self.assertEqual(f('\\\\a\\b'), ('\\\\a\\b', '\\', ''))
+ self.assertEqual(f('\\\\a\\b\\'), ('\\\\a\\b', '\\', ''))
+ self.assertEqual(f('\\\\a\\b\\c\\d'), ('\\\\a\\b', '\\', 'c\\d'))
+ # These are non-UNC paths (according to ntpath.py and test_ntpath)
+ # However, command.com says such paths are invalid, so it's
+ # difficult to know what the right semantics are
+ self.assertEqual(f('\\\\\\a\\b'), ('', '\\', 'a\\b'))
+ self.assertEqual(f('\\\\a'), ('', '\\', 'a'))
+
+
+#
+# Tests for the pure classes
+#
+
+class _BasePurePathTest(object):
+
+ # keys are canonical paths, values are list of tuples of arguments
+ # supposed to produce equal paths
+ equivalences = {
+ 'a/b': [
+ ('a', 'b'), ('a/', 'b'), ('a', 'b/'), ('a/', 'b/'),
+ ('a/b/',), ('a//b',), ('a//b//',),
+ # empty components get removed
+ ('', 'a', 'b'), ('a', '', 'b'), ('a', 'b', ''),
+ ],
+ '/b/c/d': [
+ ('a', '/b/c', 'd'), ('a', '///b//c', 'd/'),
+ ('/a', '/b/c', 'd'),
+ # empty components get removed
+ ('/', 'b', '', 'c/d'), ('/', '', 'b/c/d'), ('', '/b/c/d'),
+ ],
+ }
+
+ def setUp(self):
+ p = self.cls('a')
+ self.flavour = p._flavour
+ self.sep = self.flavour.sep
+ self.altsep = self.flavour.altsep
+
+ def test_constructor_common(self):
+ P = self.cls
+ p = P('a')
+ self.assertIsInstance(p, P)
+ P('a', 'b', 'c')
+ P('/a', 'b', 'c')
+ P('a/b/c')
+ P('/a/b/c')
+ self.assertEqual(P(P('a')), P('a'))
+ self.assertEqual(P(P('a'), 'b'), P('a/b'))
+ self.assertEqual(P(P('a'), P('b')), P('a/b'))
+
+ def test_join_common(self):
+ P = self.cls
+ p = P('a/b')
+ pp = p.joinpath('c')
+ self.assertEqual(pp, P('a/b/c'))
+ self.assertIs(type(pp), type(p))
+ pp = p.joinpath('c', 'd')
+ self.assertEqual(pp, P('a/b/c/d'))
+ pp = p.joinpath(P('c'))
+ self.assertEqual(pp, P('a/b/c'))
+ pp = p.joinpath('/c')
+ self.assertEqual(pp, P('/c'))
+
+ def test_div_common(self):
+ # Basically the same as joinpath()
+ P = self.cls
+ p = P('a/b')
+ pp = p / 'c'
+ self.assertEqual(pp, P('a/b/c'))
+ self.assertIs(type(pp), type(p))
+ pp = p / 'c/d'
+ self.assertEqual(pp, P('a/b/c/d'))
+ pp = p / 'c' / 'd'
+ self.assertEqual(pp, P('a/b/c/d'))
+ pp = 'c' / p / 'd'
+ self.assertEqual(pp, P('c/a/b/d'))
+ pp = p / P('c')
+ self.assertEqual(pp, P('a/b/c'))
+ pp = p/ '/c'
+ self.assertEqual(pp, P('/c'))
+
+ def _check_str(self, expected, args):
+ p = self.cls(*args)
+ self.assertEqual(str(p), expected.replace('/', self.sep))
+
+ def test_str_common(self):
+ # Canonicalized paths roundtrip
+ for pathstr in ('a', 'a/b', 'a/b/c', '/', '/a/b', '/a/b/c'):
+ self._check_str(pathstr, (pathstr,))
+ # Special case for the empty path
+ self._check_str('.', ('',))
+ # Other tests for str() are in test_equivalences()
+
+ def test_as_posix_common(self):
+ P = self.cls
+ for pathstr in ('a', 'a/b', 'a/b/c', '/', '/a/b', '/a/b/c'):
+ self.assertEqual(P(pathstr).as_posix(), pathstr)
+ # Other tests for as_posix() are in test_equivalences()
+
+ def test_as_bytes_common(self):
+ sep = os.fsencode(self.sep)
+ P = self.cls
+ self.assertEqual(bytes(P('a/b')), b'a' + sep + b'b')
+
+ def test_as_uri_common(self):
+ P = self.cls
+ with self.assertRaises(ValueError):
+ P('a').as_uri()
+ with self.assertRaises(ValueError):
+ P().as_uri()
+
+ def test_repr_common(self):
+ for pathstr in ('a', 'a/b', 'a/b/c', '/', '/a/b', '/a/b/c'):
+ p = self.cls(pathstr)
+ clsname = p.__class__.__name__
+ r = repr(p)
+ # The repr() is in the form ClassName("forward-slashes path")
+ self.assertTrue(r.startswith(clsname + '('), r)
+ self.assertTrue(r.endswith(')'), r)
+ inner = r[len(clsname) + 1 : -1]
+ self.assertEqual(eval(inner), p.as_posix())
+ # The repr() roundtrips
+ q = eval(r, pathlib.__dict__)
+ self.assertIs(q.__class__, p.__class__)
+ self.assertEqual(q, p)
+ self.assertEqual(repr(q), r)
+
+ def test_eq_common(self):
+ P = self.cls
+ self.assertEqual(P('a/b'), P('a/b'))
+ self.assertEqual(P('a/b'), P('a', 'b'))
+ self.assertNotEqual(P('a/b'), P('a'))
+ self.assertNotEqual(P('a/b'), P('/a/b'))
+ self.assertNotEqual(P('a/b'), P())
+ self.assertNotEqual(P('/a/b'), P('/'))
+ self.assertNotEqual(P(), P('/'))
+ self.assertNotEqual(P(), "")
+ self.assertNotEqual(P(), {})
+ self.assertNotEqual(P(), int)
+
+ def test_match_common(self):
+ P = self.cls
+ self.assertRaises(ValueError, P('a').match, '')
+ self.assertRaises(ValueError, P('a').match, '.')
+ # Simple relative pattern
+ self.assertTrue(P('b.py').match('b.py'))
+ self.assertTrue(P('a/b.py').match('b.py'))
+ self.assertTrue(P('/a/b.py').match('b.py'))
+ self.assertFalse(P('a.py').match('b.py'))
+ self.assertFalse(P('b/py').match('b.py'))
+ self.assertFalse(P('/a.py').match('b.py'))
+ self.assertFalse(P('b.py/c').match('b.py'))
+ # Wilcard relative pattern
+ self.assertTrue(P('b.py').match('*.py'))
+ self.assertTrue(P('a/b.py').match('*.py'))
+ self.assertTrue(P('/a/b.py').match('*.py'))
+ self.assertFalse(P('b.pyc').match('*.py'))
+ self.assertFalse(P('b./py').match('*.py'))
+ self.assertFalse(P('b.py/c').match('*.py'))
+ # Multi-part relative pattern
+ self.assertTrue(P('ab/c.py').match('a*/*.py'))
+ self.assertTrue(P('/d/ab/c.py').match('a*/*.py'))
+ self.assertFalse(P('a.py').match('a*/*.py'))
+ self.assertFalse(P('/dab/c.py').match('a*/*.py'))
+ self.assertFalse(P('ab/c.py/d').match('a*/*.py'))
+ # Absolute pattern
+ self.assertTrue(P('/b.py').match('/*.py'))
+ self.assertFalse(P('b.py').match('/*.py'))
+ self.assertFalse(P('a/b.py').match('/*.py'))
+ self.assertFalse(P('/a/b.py').match('/*.py'))
+ # Multi-part absolute pattern
+ self.assertTrue(P('/a/b.py').match('/a/*.py'))
+ self.assertFalse(P('/ab.py').match('/a/*.py'))
+ self.assertFalse(P('/a/b/c.py').match('/a/*.py'))
+
+ def test_ordering_common(self):
+ # Ordering is tuple-alike
+ def assertLess(a, b):
+ self.assertLess(a, b)
+ self.assertGreater(b, a)
+ P = self.cls
+ a = P('a')
+ b = P('a/b')
+ c = P('abc')
+ d = P('b')
+ assertLess(a, b)
+ assertLess(a, c)
+ assertLess(a, d)
+ assertLess(b, c)
+ assertLess(c, d)
+ P = self.cls
+ a = P('/a')
+ b = P('/a/b')
+ c = P('/abc')
+ d = P('/b')
+ assertLess(a, b)
+ assertLess(a, c)
+ assertLess(a, d)
+ assertLess(b, c)
+ assertLess(c, d)
+ with self.assertRaises(TypeError):
+ P() < {}
+
+ def test_parts_common(self):
+ # `parts` returns a tuple
+ sep = self.sep
+ P = self.cls
+ p = P('a/b')
+ parts = p.parts
+ self.assertEqual(parts, ('a', 'b'))
+ # The object gets reused
+ self.assertIs(parts, p.parts)
+ # When the path is absolute, the anchor is a separate part
+ p = P('/a/b')
+ parts = p.parts
+ self.assertEqual(parts, (sep, 'a', 'b'))
+
+ def test_equivalences(self):
+ for k, tuples in self.equivalences.items():
+ canon = k.replace('/', self.sep)
+ posix = k.replace(self.sep, '/')
+ if canon != posix:
+ tuples = tuples + [
+ tuple(part.replace('/', self.sep) for part in t)
+ for t in tuples
+ ]
+ tuples.append((posix, ))
+ pcanon = self.cls(canon)
+ for t in tuples:
+ p = self.cls(*t)
+ self.assertEqual(p, pcanon, "failed with args {}".format(t))
+ self.assertEqual(hash(p), hash(pcanon))
+ self.assertEqual(str(p), canon)
+ self.assertEqual(p.as_posix(), posix)
+
+ def test_parent_common(self):
+ # Relative
+ P = self.cls
+ p = P('a/b/c')
+ self.assertEqual(p.parent, P('a/b'))
+ self.assertEqual(p.parent.parent, P('a'))
+ self.assertEqual(p.parent.parent.parent, P())
+ self.assertEqual(p.parent.parent.parent.parent, P())
+ # Anchored
+ p = P('/a/b/c')
+ self.assertEqual(p.parent, P('/a/b'))
+ self.assertEqual(p.parent.parent, P('/a'))
+ self.assertEqual(p.parent.parent.parent, P('/'))
+ self.assertEqual(p.parent.parent.parent.parent, P('/'))
+
+ def test_parents_common(self):
+ # Relative
+ P = self.cls
+ p = P('a/b/c')
+ par = p.parents
+ self.assertEqual(len(par), 3)
+ self.assertEqual(par[0], P('a/b'))
+ self.assertEqual(par[1], P('a'))
+ self.assertEqual(par[2], P('.'))
+ self.assertEqual(list(par), [P('a/b'), P('a'), P('.')])
+ with self.assertRaises(IndexError):
+ par[-1]
+ with self.assertRaises(IndexError):
+ par[3]
+ with self.assertRaises(TypeError):
+ par[0] = p
+ # Anchored
+ p = P('/a/b/c')
+ par = p.parents
+ self.assertEqual(len(par), 3)
+ self.assertEqual(par[0], P('/a/b'))
+ self.assertEqual(par[1], P('/a'))
+ self.assertEqual(par[2], P('/'))
+ self.assertEqual(list(par), [P('/a/b'), P('/a'), P('/')])
+ with self.assertRaises(IndexError):
+ par[3]
+
+ def test_drive_common(self):
+ P = self.cls
+ self.assertEqual(P('a/b').drive, '')
+ self.assertEqual(P('/a/b').drive, '')
+ self.assertEqual(P('').drive, '')
+
+ def test_root_common(self):
+ P = self.cls
+ sep = self.sep
+ self.assertEqual(P('').root, '')
+ self.assertEqual(P('a/b').root, '')
+ self.assertEqual(P('/').root, sep)
+ self.assertEqual(P('/a/b').root, sep)
+
+ def test_anchor_common(self):
+ P = self.cls
+ sep = self.sep
+ self.assertEqual(P('').anchor, '')
+ self.assertEqual(P('a/b').anchor, '')
+ self.assertEqual(P('/').anchor, sep)
+ self.assertEqual(P('/a/b').anchor, sep)
+
+ def test_name_common(self):
+ P = self.cls
+ self.assertEqual(P('').name, '')
+ self.assertEqual(P('.').name, '')
+ self.assertEqual(P('/').name, '')
+ self.assertEqual(P('a/b').name, 'b')
+ self.assertEqual(P('/a/b').name, 'b')
+ self.assertEqual(P('/a/b/.').name, 'b')
+ self.assertEqual(P('a/b.py').name, 'b.py')
+ self.assertEqual(P('/a/b.py').name, 'b.py')
+
+ def test_suffix_common(self):
+ P = self.cls
+ self.assertEqual(P('').suffix, '')
+ self.assertEqual(P('.').suffix, '')
+ self.assertEqual(P('..').suffix, '')
+ self.assertEqual(P('/').suffix, '')
+ self.assertEqual(P('a/b').suffix, '')
+ self.assertEqual(P('/a/b').suffix, '')
+ self.assertEqual(P('/a/b/.').suffix, '')
+ self.assertEqual(P('a/b.py').suffix, '.py')
+ self.assertEqual(P('/a/b.py').suffix, '.py')
+ self.assertEqual(P('a/.hgrc').suffix, '')
+ self.assertEqual(P('/a/.hgrc').suffix, '')
+ self.assertEqual(P('a/.hg.rc').suffix, '.rc')
+ self.assertEqual(P('/a/.hg.rc').suffix, '.rc')
+ self.assertEqual(P('a/b.tar.gz').suffix, '.gz')
+ self.assertEqual(P('/a/b.tar.gz').suffix, '.gz')
+ self.assertEqual(P('a/Some name. Ending with a dot.').suffix, '')
+ self.assertEqual(P('/a/Some name. Ending with a dot.').suffix, '')
+
+ def test_suffixes_common(self):
+ P = self.cls
+ self.assertEqual(P('').suffixes, [])
+ self.assertEqual(P('.').suffixes, [])
+ self.assertEqual(P('/').suffixes, [])
+ self.assertEqual(P('a/b').suffixes, [])
+ self.assertEqual(P('/a/b').suffixes, [])
+ self.assertEqual(P('/a/b/.').suffixes, [])
+ self.assertEqual(P('a/b.py').suffixes, ['.py'])
+ self.assertEqual(P('/a/b.py').suffixes, ['.py'])
+ self.assertEqual(P('a/.hgrc').suffixes, [])
+ self.assertEqual(P('/a/.hgrc').suffixes, [])
+ self.assertEqual(P('a/.hg.rc').suffixes, ['.rc'])
+ self.assertEqual(P('/a/.hg.rc').suffixes, ['.rc'])
+ self.assertEqual(P('a/b.tar.gz').suffixes, ['.tar', '.gz'])
+ self.assertEqual(P('/a/b.tar.gz').suffixes, ['.tar', '.gz'])
+ self.assertEqual(P('a/Some name. Ending with a dot.').suffixes, [])
+ self.assertEqual(P('/a/Some name. Ending with a dot.').suffixes, [])
+
+ def test_stem_common(self):
+ P = self.cls
+ self.assertEqual(P('').stem, '')
+ self.assertEqual(P('.').stem, '')
+ self.assertEqual(P('..').stem, '..')
+ self.assertEqual(P('/').stem, '')
+ self.assertEqual(P('a/b').stem, 'b')
+ self.assertEqual(P('a/b.py').stem, 'b')
+ self.assertEqual(P('a/.hgrc').stem, '.hgrc')
+ self.assertEqual(P('a/.hg.rc').stem, '.hg')
+ self.assertEqual(P('a/b.tar.gz').stem, 'b.tar')
+ self.assertEqual(P('a/Some name. Ending with a dot.').stem,
+ 'Some name. Ending with a dot.')
+
+ def test_with_name_common(self):
+ P = self.cls
+ self.assertEqual(P('a/b').with_name('d.xml'), P('a/d.xml'))
+ self.assertEqual(P('/a/b').with_name('d.xml'), P('/a/d.xml'))
+ self.assertEqual(P('a/b.py').with_name('d.xml'), P('a/d.xml'))
+ self.assertEqual(P('/a/b.py').with_name('d.xml'), P('/a/d.xml'))
+ self.assertEqual(P('a/Dot ending.').with_name('d.xml'), P('a/d.xml'))
+ self.assertEqual(P('/a/Dot ending.').with_name('d.xml'), P('/a/d.xml'))
+ self.assertRaises(ValueError, P('').with_name, 'd.xml')
+ self.assertRaises(ValueError, P('.').with_name, 'd.xml')
+ self.assertRaises(ValueError, P('/').with_name, 'd.xml')
+
+ def test_with_suffix_common(self):
+ P = self.cls
+ self.assertEqual(P('a/b').with_suffix('.gz'), P('a/b.gz'))
+ self.assertEqual(P('/a/b').with_suffix('.gz'), P('/a/b.gz'))
+ self.assertEqual(P('a/b.py').with_suffix('.gz'), P('a/b.gz'))
+ self.assertEqual(P('/a/b.py').with_suffix('.gz'), P('/a/b.gz'))
+ self.assertRaises(ValueError, P('').with_suffix, '.gz')
+ self.assertRaises(ValueError, P('.').with_suffix, '.gz')
+ self.assertRaises(ValueError, P('/').with_suffix, '.gz')
+
+ def test_relative_to_common(self):
+ P = self.cls
+ p = P('a/b')
+ self.assertRaises(TypeError, p.relative_to)
+ self.assertEqual(p.relative_to(P()), P('a/b'))
+ self.assertEqual(p.relative_to(P('a')), P('b'))
+ self.assertEqual(p.relative_to(P('a/b')), P())
+ # With several args
+ self.assertEqual(p.relative_to('a', 'b'), P())
+ # Unrelated paths
+ self.assertRaises(ValueError, p.relative_to, P('c'))
+ self.assertRaises(ValueError, p.relative_to, P('a/b/c'))
+ self.assertRaises(ValueError, p.relative_to, P('a/c'))
+ self.assertRaises(ValueError, p.relative_to, P('/a'))
+ p = P('/a/b')
+ self.assertEqual(p.relative_to(P('/')), P('a/b'))
+ self.assertEqual(p.relative_to(P('/a')), P('b'))
+ self.assertEqual(p.relative_to(P('/a/b')), P())
+ # Unrelated paths
+ self.assertRaises(ValueError, p.relative_to, P('/c'))
+ self.assertRaises(ValueError, p.relative_to, P('/a/b/c'))
+ self.assertRaises(ValueError, p.relative_to, P('/a/c'))
+ self.assertRaises(ValueError, p.relative_to, P())
+ self.assertRaises(ValueError, p.relative_to, P('a'))
+
+ def test_pickling_common(self):
+ P = self.cls
+ p = P('/a/b')
+ for proto in range(0, pickle.HIGHEST_PROTOCOL + 1):
+ dumped = pickle.dumps(p, proto)
+ pp = pickle.loads(dumped)
+ self.assertIs(pp.__class__, p.__class__)
+ self.assertEqual(pp, p)
+ self.assertEqual(hash(pp), hash(p))
+ self.assertEqual(str(pp), str(p))
+
+
+class PurePosixPathTest(_BasePurePathTest, unittest.TestCase):
+ cls = pathlib.PurePosixPath
+
+ def test_root(self):
+ P = self.cls
+ self.assertEqual(P('/a/b').root, '/')
+ self.assertEqual(P('///a/b').root, '/')
+ # POSIX special case for two leading slashes
+ self.assertEqual(P('//a/b').root, '//')
+
+ def test_eq(self):
+ P = self.cls
+ self.assertNotEqual(P('a/b'), P('A/b'))
+ self.assertEqual(P('/a'), P('///a'))
+ self.assertNotEqual(P('/a'), P('//a'))
+
+ def test_as_uri(self):
+ from urllib.parse import quote_from_bytes
+ P = self.cls
+ self.assertEqual(P('/').as_uri(), 'file:///')
+ self.assertEqual(P('/a/b.c').as_uri(), 'file:///a/b.c')
+ self.assertEqual(P('/a/b%#c').as_uri(), 'file:///a/b%25%23c')
+ self.assertEqual(P('/a/b\xe9').as_uri(),
+ 'file:///a/b' + quote_from_bytes(os.fsencode('\xe9')))
+
+ def test_match(self):
+ P = self.cls
+ self.assertFalse(P('A.py').match('a.PY'))
+
+ def test_is_absolute(self):
+ P = self.cls
+ self.assertFalse(P().is_absolute())
+ self.assertFalse(P('a').is_absolute())
+ self.assertFalse(P('a/b/').is_absolute())
+ self.assertTrue(P('/').is_absolute())
+ self.assertTrue(P('/a').is_absolute())
+ self.assertTrue(P('/a/b/').is_absolute())
+ self.assertTrue(P('//a').is_absolute())
+ self.assertTrue(P('//a/b').is_absolute())
+
+ def test_is_reserved(self):
+ P = self.cls
+ self.assertIs(False, P('').is_reserved())
+ self.assertIs(False, P('/').is_reserved())
+ self.assertIs(False, P('/foo/bar').is_reserved())
+ self.assertIs(False, P('/dev/con/PRN/NUL').is_reserved())
+
+ def test_join(self):
+ P = self.cls
+ p = P('//a')
+ pp = p.joinpath('b')
+ self.assertEqual(pp, P('//a/b'))
+ pp = P('/a').joinpath('//c')
+ self.assertEqual(pp, P('//c'))
+ pp = P('//a').joinpath('/c')
+ self.assertEqual(pp, P('/c'))
+
+ def test_div(self):
+ # Basically the same as joinpath()
+ P = self.cls
+ p = P('//a')
+ pp = p / 'b'
+ self.assertEqual(pp, P('//a/b'))
+ pp = P('/a') / '//c'
+ self.assertEqual(pp, P('//c'))
+ pp = P('//a') / '/c'
+ self.assertEqual(pp, P('/c'))
+
+
+class PureWindowsPathTest(_BasePurePathTest, unittest.TestCase):
+ cls = pathlib.PureWindowsPath
+
+ equivalences = _BasePurePathTest.equivalences.copy()
+ equivalences.update({
+ 'c:a': [ ('c:', 'a'), ('c:', 'a/'), ('/', 'c:', 'a') ],
+ 'c:/a': [
+ ('c:/', 'a'), ('c:', '/', 'a'), ('c:', '/a'),
+ ('/z', 'c:/', 'a'), ('//x/y', 'c:/', 'a'),
+ ],
+ '//a/b/': [ ('//a/b',) ],
+ '//a/b/c': [
+ ('//a/b', 'c'), ('//a/b/', 'c'),
+ ],
+ })
+
+ def test_str(self):
+ p = self.cls('a/b/c')
+ self.assertEqual(str(p), 'a\\b\\c')
+ p = self.cls('c:/a/b/c')
+ self.assertEqual(str(p), 'c:\\a\\b\\c')
+ p = self.cls('//a/b')
+ self.assertEqual(str(p), '\\\\a\\b\\')
+ p = self.cls('//a/b/c')
+ self.assertEqual(str(p), '\\\\a\\b\\c')
+ p = self.cls('//a/b/c/d')
+ self.assertEqual(str(p), '\\\\a\\b\\c\\d')
+
+ def test_eq(self):
+ P = self.cls
+ self.assertEqual(P('c:a/b'), P('c:a/b'))
+ self.assertEqual(P('c:a/b'), P('c:', 'a', 'b'))
+ self.assertNotEqual(P('c:a/b'), P('d:a/b'))
+ self.assertNotEqual(P('c:a/b'), P('c:/a/b'))
+ self.assertNotEqual(P('/a/b'), P('c:/a/b'))
+ # Case-insensitivity
+ self.assertEqual(P('a/B'), P('A/b'))
+ self.assertEqual(P('C:a/B'), P('c:A/b'))
+ self.assertEqual(P('//Some/SHARE/a/B'), P('//somE/share/A/b'))
+
+ def test_as_uri(self):
+ from urllib.parse import quote_from_bytes
+ P = self.cls
+ with self.assertRaises(ValueError):
+ P('/a/b').as_uri()
+ with self.assertRaises(ValueError):
+ P('c:a/b').as_uri()
+ self.assertEqual(P('c:/').as_uri(), 'file:///c:/')
+ self.assertEqual(P('c:/a/b.c').as_uri(), 'file:///c:/a/b.c')
+ self.assertEqual(P('c:/a/b%#c').as_uri(), 'file:///c:/a/b%25%23c')
+ self.assertEqual(P('c:/a/b\xe9').as_uri(), 'file:///c:/a/b%C3%A9')
+ self.assertEqual(P('//some/share/').as_uri(), 'file://some/share/')
+ self.assertEqual(P('//some/share/a/b.c').as_uri(),
+ 'file://some/share/a/b.c')
+ self.assertEqual(P('//some/share/a/b%#c\xe9').as_uri(),
+ 'file://some/share/a/b%25%23c%C3%A9')
+
+ def test_match_common(self):
+ P = self.cls
+ # Absolute patterns
+ self.assertTrue(P('c:/b.py').match('/*.py'))
+ self.assertTrue(P('c:/b.py').match('c:*.py'))
+ self.assertTrue(P('c:/b.py').match('c:/*.py'))
+ self.assertFalse(P('d:/b.py').match('c:/*.py')) # wrong drive
+ self.assertFalse(P('b.py').match('/*.py'))
+ self.assertFalse(P('b.py').match('c:*.py'))
+ self.assertFalse(P('b.py').match('c:/*.py'))
+ self.assertFalse(P('c:b.py').match('/*.py'))
+ self.assertFalse(P('c:b.py').match('c:/*.py'))
+ self.assertFalse(P('/b.py').match('c:*.py'))
+ self.assertFalse(P('/b.py').match('c:/*.py'))
+ # UNC patterns
+ self.assertTrue(P('//some/share/a.py').match('/*.py'))
+ self.assertTrue(P('//some/share/a.py').match('//some/share/*.py'))
+ self.assertFalse(P('//other/share/a.py').match('//some/share/*.py'))
+ self.assertFalse(P('//some/share/a/b.py').match('//some/share/*.py'))
+ # Case-insensitivity
+ self.assertTrue(P('B.py').match('b.PY'))
+ self.assertTrue(P('c:/a/B.Py').match('C:/A/*.pY'))
+ self.assertTrue(P('//Some/Share/B.Py').match('//somE/sharE/*.pY'))
+
+ def test_ordering_common(self):
+ # Case-insensitivity
+ def assertOrderedEqual(a, b):
+ self.assertLessEqual(a, b)
+ self.assertGreaterEqual(b, a)
+ P = self.cls
+ p = P('c:A/b')
+ q = P('C:a/B')
+ assertOrderedEqual(p, q)
+ self.assertFalse(p < q)
+ self.assertFalse(p > q)
+ p = P('//some/Share/A/b')
+ q = P('//Some/SHARE/a/B')
+ assertOrderedEqual(p, q)
+ self.assertFalse(p < q)
+ self.assertFalse(p > q)
+
+ def test_parts(self):
+ P = self.cls
+ p = P('c:a/b')
+ parts = p.parts
+ self.assertEqual(parts, ('c:', 'a', 'b'))
+ p = P('c:/a/b')
+ parts = p.parts
+ self.assertEqual(parts, ('c:\\', 'a', 'b'))
+ p = P('//a/b/c/d')
+ parts = p.parts
+ self.assertEqual(parts, ('\\\\a\\b\\', 'c', 'd'))
+
+ def test_parent(self):
+ # Anchored
+ P = self.cls
+ p = P('z:a/b/c')
+ self.assertEqual(p.parent, P('z:a/b'))
+ self.assertEqual(p.parent.parent, P('z:a'))
+ self.assertEqual(p.parent.parent.parent, P('z:'))
+ self.assertEqual(p.parent.parent.parent.parent, P('z:'))
+ p = P('z:/a/b/c')
+ self.assertEqual(p.parent, P('z:/a/b'))
+ self.assertEqual(p.parent.parent, P('z:/a'))
+ self.assertEqual(p.parent.parent.parent, P('z:/'))
+ self.assertEqual(p.parent.parent.parent.parent, P('z:/'))
+ p = P('//a/b/c/d')
+ self.assertEqual(p.parent, P('//a/b/c'))
+ self.assertEqual(p.parent.parent, P('//a/b'))
+ self.assertEqual(p.parent.parent.parent, P('//a/b'))
+
+ def test_parents(self):
+ # Anchored
+ P = self.cls
+ p = P('z:a/b/')
+ par = p.parents
+ self.assertEqual(len(par), 2)
+ self.assertEqual(par[0], P('z:a'))
+ self.assertEqual(par[1], P('z:'))
+ self.assertEqual(list(par), [P('z:a'), P('z:')])
+ with self.assertRaises(IndexError):
+ par[2]
+ p = P('z:/a/b/')
+ par = p.parents
+ self.assertEqual(len(par), 2)
+ self.assertEqual(par[0], P('z:/a'))
+ self.assertEqual(par[1], P('z:/'))
+ self.assertEqual(list(par), [P('z:/a'), P('z:/')])
+ with self.assertRaises(IndexError):
+ par[2]
+ p = P('//a/b/c/d')
+ par = p.parents
+ self.assertEqual(len(par), 2)
+ self.assertEqual(par[0], P('//a/b/c'))
+ self.assertEqual(par[1], P('//a/b'))
+ self.assertEqual(list(par), [P('//a/b/c'), P('//a/b')])
+ with self.assertRaises(IndexError):
+ par[2]
+
+ def test_drive(self):
+ P = self.cls
+ self.assertEqual(P('c:').drive, 'c:')
+ self.assertEqual(P('c:a/b').drive, 'c:')
+ self.assertEqual(P('c:/').drive, 'c:')
+ self.assertEqual(P('c:/a/b/').drive, 'c:')
+ self.assertEqual(P('//a/b').drive, '\\\\a\\b')
+ self.assertEqual(P('//a/b/').drive, '\\\\a\\b')
+ self.assertEqual(P('//a/b/c/d').drive, '\\\\a\\b')
+
+ def test_root(self):
+ P = self.cls
+ self.assertEqual(P('c:').root, '')
+ self.assertEqual(P('c:a/b').root, '')
+ self.assertEqual(P('c:/').root, '\\')
+ self.assertEqual(P('c:/a/b/').root, '\\')
+ self.assertEqual(P('//a/b').root, '\\')
+ self.assertEqual(P('//a/b/').root, '\\')
+ self.assertEqual(P('//a/b/c/d').root, '\\')
+
+ def test_anchor(self):
+ P = self.cls
+ self.assertEqual(P('c:').anchor, 'c:')
+ self.assertEqual(P('c:a/b').anchor, 'c:')
+ self.assertEqual(P('c:/').anchor, 'c:\\')
+ self.assertEqual(P('c:/a/b/').anchor, 'c:\\')
+ self.assertEqual(P('//a/b').anchor, '\\\\a\\b\\')
+ self.assertEqual(P('//a/b/').anchor, '\\\\a\\b\\')
+ self.assertEqual(P('//a/b/c/d').anchor, '\\\\a\\b\\')
+
+ def test_name(self):
+ P = self.cls
+ self.assertEqual(P('c:').name, '')
+ self.assertEqual(P('c:/').name, '')
+ self.assertEqual(P('c:a/b').name, 'b')
+ self.assertEqual(P('c:/a/b').name, 'b')
+ self.assertEqual(P('c:a/b.py').name, 'b.py')
+ self.assertEqual(P('c:/a/b.py').name, 'b.py')
+ self.assertEqual(P('//My.py/Share.php').name, '')
+ self.assertEqual(P('//My.py/Share.php/a/b').name, 'b')
+
+ def test_suffix(self):
+ P = self.cls
+ self.assertEqual(P('c:').suffix, '')
+ self.assertEqual(P('c:/').suffix, '')
+ self.assertEqual(P('c:a/b').suffix, '')
+ self.assertEqual(P('c:/a/b').suffix, '')
+ self.assertEqual(P('c:a/b.py').suffix, '.py')
+ self.assertEqual(P('c:/a/b.py').suffix, '.py')
+ self.assertEqual(P('c:a/.hgrc').suffix, '')
+ self.assertEqual(P('c:/a/.hgrc').suffix, '')
+ self.assertEqual(P('c:a/.hg.rc').suffix, '.rc')
+ self.assertEqual(P('c:/a/.hg.rc').suffix, '.rc')
+ self.assertEqual(P('c:a/b.tar.gz').suffix, '.gz')
+ self.assertEqual(P('c:/a/b.tar.gz').suffix, '.gz')
+ self.assertEqual(P('c:a/Some name. Ending with a dot.').suffix, '')
+ self.assertEqual(P('c:/a/Some name. Ending with a dot.').suffix, '')
+ self.assertEqual(P('//My.py/Share.php').suffix, '')
+ self.assertEqual(P('//My.py/Share.php/a/b').suffix, '')
+
+ def test_suffixes(self):
+ P = self.cls
+ self.assertEqual(P('c:').suffixes, [])
+ self.assertEqual(P('c:/').suffixes, [])
+ self.assertEqual(P('c:a/b').suffixes, [])
+ self.assertEqual(P('c:/a/b').suffixes, [])
+ self.assertEqual(P('c:a/b.py').suffixes, ['.py'])
+ self.assertEqual(P('c:/a/b.py').suffixes, ['.py'])
+ self.assertEqual(P('c:a/.hgrc').suffixes, [])
+ self.assertEqual(P('c:/a/.hgrc').suffixes, [])
+ self.assertEqual(P('c:a/.hg.rc').suffixes, ['.rc'])
+ self.assertEqual(P('c:/a/.hg.rc').suffixes, ['.rc'])
+ self.assertEqual(P('c:a/b.tar.gz').suffixes, ['.tar', '.gz'])
+ self.assertEqual(P('c:/a/b.tar.gz').suffixes, ['.tar', '.gz'])
+ self.assertEqual(P('//My.py/Share.php').suffixes, [])
+ self.assertEqual(P('//My.py/Share.php/a/b').suffixes, [])
+ self.assertEqual(P('c:a/Some name. Ending with a dot.').suffixes, [])
+ self.assertEqual(P('c:/a/Some name. Ending with a dot.').suffixes, [])
+
+ def test_stem(self):
+ P = self.cls
+ self.assertEqual(P('c:').stem, '')
+ self.assertEqual(P('c:.').stem, '')
+ self.assertEqual(P('c:..').stem, '..')
+ self.assertEqual(P('c:/').stem, '')
+ self.assertEqual(P('c:a/b').stem, 'b')
+ self.assertEqual(P('c:a/b.py').stem, 'b')
+ self.assertEqual(P('c:a/.hgrc').stem, '.hgrc')
+ self.assertEqual(P('c:a/.hg.rc').stem, '.hg')
+ self.assertEqual(P('c:a/b.tar.gz').stem, 'b.tar')
+ self.assertEqual(P('c:a/Some name. Ending with a dot.').stem,
+ 'Some name. Ending with a dot.')
+
+ def test_with_name(self):
+ P = self.cls
+ self.assertEqual(P('c:a/b').with_name('d.xml'), P('c:a/d.xml'))
+ self.assertEqual(P('c:/a/b').with_name('d.xml'), P('c:/a/d.xml'))
+ self.assertEqual(P('c:a/Dot ending.').with_name('d.xml'), P('c:a/d.xml'))
+ self.assertEqual(P('c:/a/Dot ending.').with_name('d.xml'), P('c:/a/d.xml'))
+ self.assertRaises(ValueError, P('c:').with_name, 'd.xml')
+ self.assertRaises(ValueError, P('c:/').with_name, 'd.xml')
+ self.assertRaises(ValueError, P('//My/Share').with_name, 'd.xml')
+
+ def test_with_suffix(self):
+ P = self.cls
+ self.assertEqual(P('c:a/b').with_suffix('.gz'), P('c:a/b.gz'))
+ self.assertEqual(P('c:/a/b').with_suffix('.gz'), P('c:/a/b.gz'))
+ self.assertEqual(P('c:a/b.py').with_suffix('.gz'), P('c:a/b.gz'))
+ self.assertEqual(P('c:/a/b.py').with_suffix('.gz'), P('c:/a/b.gz'))
+ self.assertRaises(ValueError, P('').with_suffix, '.gz')
+ self.assertRaises(ValueError, P('.').with_suffix, '.gz')
+ self.assertRaises(ValueError, P('/').with_suffix, '.gz')
+ self.assertRaises(ValueError, P('//My/Share').with_suffix, '.gz')
+
+ def test_relative_to(self):
+ P = self.cls
+ p = P('c:a/b')
+ self.assertEqual(p.relative_to(P('c:')), P('a/b'))
+ self.assertEqual(p.relative_to(P('c:a')), P('b'))
+ self.assertEqual(p.relative_to(P('c:a/b')), P())
+ # Unrelated paths
+ self.assertRaises(ValueError, p.relative_to, P())
+ self.assertRaises(ValueError, p.relative_to, P('d:'))
+ self.assertRaises(ValueError, p.relative_to, P('a'))
+ self.assertRaises(ValueError, p.relative_to, P('/a'))
+ self.assertRaises(ValueError, p.relative_to, P('c:a/b/c'))
+ self.assertRaises(ValueError, p.relative_to, P('c:a/c'))
+ self.assertRaises(ValueError, p.relative_to, P('c:/a'))
+ p = P('c:/a/b')
+ self.assertEqual(p.relative_to(P('c:')), P('/a/b'))
+ self.assertEqual(p.relative_to(P('c:/')), P('a/b'))
+ self.assertEqual(p.relative_to(P('c:/a')), P('b'))
+ self.assertEqual(p.relative_to(P('c:/a/b')), P())
+ # Unrelated paths
+ self.assertRaises(ValueError, p.relative_to, P('c:/c'))
+ self.assertRaises(ValueError, p.relative_to, P('c:/a/b/c'))
+ self.assertRaises(ValueError, p.relative_to, P('c:/a/c'))
+ self.assertRaises(ValueError, p.relative_to, P('c:a'))
+ self.assertRaises(ValueError, p.relative_to, P('d:'))
+ self.assertRaises(ValueError, p.relative_to, P('d:/'))
+ self.assertRaises(ValueError, p.relative_to, P('/a'))
+ self.assertRaises(ValueError, p.relative_to, P('//c/a'))
+ # UNC paths
+ p = P('//a/b/c/d')
+ self.assertEqual(p.relative_to(P('//a/b')), P('c/d'))
+ self.assertEqual(p.relative_to(P('//a/b/c')), P('d'))
+ self.assertEqual(p.relative_to(P('//a/b/c/d')), P())
+ # Unrelated paths
+ self.assertRaises(ValueError, p.relative_to, P('/a/b/c'))
+ self.assertRaises(ValueError, p.relative_to, P('c:/a/b/c'))
+ self.assertRaises(ValueError, p.relative_to, P('//z/b/c'))
+ self.assertRaises(ValueError, p.relative_to, P('//a/z/c'))
+
+ def test_is_absolute(self):
+ P = self.cls
+ # Under NT, only paths with both a drive and a root are absolute
+ self.assertFalse(P().is_absolute())
+ self.assertFalse(P('a').is_absolute())
+ self.assertFalse(P('a/b/').is_absolute())
+ self.assertFalse(P('/').is_absolute())
+ self.assertFalse(P('/a').is_absolute())
+ self.assertFalse(P('/a/b/').is_absolute())
+ self.assertFalse(P('c:').is_absolute())
+ self.assertFalse(P('c:a').is_absolute())
+ self.assertFalse(P('c:a/b/').is_absolute())
+ self.assertTrue(P('c:/').is_absolute())
+ self.assertTrue(P('c:/a').is_absolute())
+ self.assertTrue(P('c:/a/b/').is_absolute())
+ # UNC paths are absolute by definition
+ self.assertTrue(P('//a/b').is_absolute())
+ self.assertTrue(P('//a/b/').is_absolute())
+ self.assertTrue(P('//a/b/c').is_absolute())
+ self.assertTrue(P('//a/b/c/d').is_absolute())
+
+ def test_is_reserved(self):
+ P = self.cls
+ self.assertIs(False, P('').is_reserved())
+ self.assertIs(False, P('/').is_reserved())
+ self.assertIs(False, P('/foo/bar').is_reserved())
+ self.assertIs(True, P('con').is_reserved())
+ self.assertIs(True, P('NUL').is_reserved())
+ self.assertIs(True, P('NUL.txt').is_reserved())
+ self.assertIs(True, P('com1').is_reserved())
+ self.assertIs(True, P('com9.bar').is_reserved())
+ self.assertIs(False, P('bar.com9').is_reserved())
+ self.assertIs(True, P('lpt1').is_reserved())
+ self.assertIs(True, P('lpt9.bar').is_reserved())
+ self.assertIs(False, P('bar.lpt9').is_reserved())
+ # Only the last component matters
+ self.assertIs(False, P('c:/NUL/con/baz').is_reserved())
+ # UNC paths are never reserved
+ self.assertIs(False, P('//my/share/nul/con/aux').is_reserved())
+
+
+class PurePathTest(_BasePurePathTest, unittest.TestCase):
+ cls = pathlib.PurePath
+
+ def test_concrete_class(self):
+ p = self.cls('a')
+ self.assertIs(type(p),
+ pathlib.PureWindowsPath if os.name == 'nt' else pathlib.PurePosixPath)
+
+ def test_different_flavours_unequal(self):
+ p = pathlib.PurePosixPath('a')
+ q = pathlib.PureWindowsPath('a')
+ self.assertNotEqual(p, q)
+
+ def test_different_flavours_unordered(self):
+ p = pathlib.PurePosixPath('a')
+ q = pathlib.PureWindowsPath('a')
+ with self.assertRaises(TypeError):
+ p < q
+ with self.assertRaises(TypeError):
+ p <= q
+ with self.assertRaises(TypeError):
+ p > q
+ with self.assertRaises(TypeError):
+ p >= q
+
+
+#
+# Tests for the concrete classes
+#
+
+# Make sure any symbolic links in the base test path are resolved
+BASE = os.path.realpath(TESTFN)
+join = lambda *x: os.path.join(BASE, *x)
+rel_join = lambda *x: os.path.join(TESTFN, *x)
+
+def symlink_skip_reason():
+ if not pathlib.supports_symlinks:
+ return "no system support for symlinks"
+ try:
+ os.symlink(__file__, BASE)
+ except OSError as e:
+ return str(e)
+ else:
+ support.unlink(BASE)
+ return None
+
+symlink_skip_reason = symlink_skip_reason()
+
+only_nt = unittest.skipIf(os.name != 'nt',
+ 'test requires a Windows-compatible system')
+only_posix = unittest.skipIf(os.name == 'nt',
+ 'test requires a POSIX-compatible system')
+with_symlinks = unittest.skipIf(symlink_skip_reason, symlink_skip_reason)
+
+
+ at only_posix
+class PosixPathAsPureTest(PurePosixPathTest):
+ cls = pathlib.PosixPath
+
+ at only_nt
+class WindowsPathAsPureTest(PureWindowsPathTest):
+ cls = pathlib.WindowsPath
+
+
+class _BasePathTest(object):
+ """Tests for the FS-accessing functionalities of the Path classes."""
+
+ # (BASE)
+ # |
+ # |-- dirA/
+ # |-- linkC -> "../dirB"
+ # |-- dirB/
+ # | |-- fileB
+ # |-- linkD -> "../dirB"
+ # |-- dirC/
+ # | |-- fileC
+ # | |-- fileD
+ # |-- fileA
+ # |-- linkA -> "fileA"
+ # |-- linkB -> "dirB"
+ #
+
+ def setUp(self):
+ os.mkdir(BASE)
+ self.addCleanup(shutil.rmtree, BASE)
+ os.mkdir(join('dirA'))
+ os.mkdir(join('dirB'))
+ os.mkdir(join('dirC'))
+ os.mkdir(join('dirC', 'dirD'))
+ with open(join('fileA'), 'wb') as f:
+ f.write(b"this is file A\n")
+ with open(join('dirB', 'fileB'), 'wb') as f:
+ f.write(b"this is file B\n")
+ with open(join('dirC', 'fileC'), 'wb') as f:
+ f.write(b"this is file C\n")
+ with open(join('dirC', 'dirD', 'fileD'), 'wb') as f:
+ f.write(b"this is file D\n")
+ if not symlink_skip_reason:
+ if os.name == 'nt':
+ # Workaround for http://bugs.python.org/issue13772
+ def dirlink(src, dest):
+ os.symlink(src, dest, target_is_directory=True)
+ else:
+ def dirlink(src, dest):
+ os.symlink(src, dest)
+ # Relative symlinks
+ os.symlink('fileA', join('linkA'))
+ os.symlink('non-existing', join('brokenLink'))
+ dirlink('dirB', join('linkB'))
+ dirlink(os.path.join('..', 'dirB'), join('dirA', 'linkC'))
+ # This one goes upwards but doesn't create a loop
+ dirlink(os.path.join('..', 'dirB'), join('dirB', 'linkD'))
+
+ def assertSame(self, path_a, path_b):
+ self.assertTrue(os.path.samefile(str(path_a), str(path_b)),
+ "%r and %r don't point to the same file" %
+ (path_a, path_b))
+
+ def assertFileNotFound(self, func, *args, **kwargs):
+ with self.assertRaises(FileNotFoundError) as cm:
+ func(*args, **kwargs)
+ self.assertEqual(cm.exception.errno, errno.ENOENT)
+
+ def _test_cwd(self, p):
+ q = self.cls(os.getcwd())
+ self.assertEqual(p, q)
+ self.assertEqual(str(p), str(q))
+ self.assertIs(type(p), type(q))
+ self.assertTrue(p.is_absolute())
+
+ def test_cwd(self):
+ p = self.cls.cwd()
+ self._test_cwd(p)
+
+ def test_empty_path(self):
+ # The empty path points to '.'
+ p = self.cls('')
+ self.assertEqual(p.stat(), os.stat('.'))
+
+ def test_exists(self):
+ P = self.cls
+ p = P(BASE)
+ self.assertIs(True, p.exists())
+ self.assertIs(True, (p / 'dirA').exists())
+ self.assertIs(True, (p / 'fileA').exists())
+ if not symlink_skip_reason:
+ self.assertIs(True, (p / 'linkA').exists())
+ self.assertIs(True, (p / 'linkB').exists())
+ self.assertIs(False, (p / 'foo').exists())
+ self.assertIs(False, P('/xyzzy').exists())
+
+ def test_open_common(self):
+ p = self.cls(BASE)
+ with (p / 'fileA').open('r') as f:
+ self.assertIsInstance(f, io.TextIOBase)
+ self.assertEqual(f.read(), "this is file A\n")
+ with (p / 'fileA').open('rb') as f:
+ self.assertIsInstance(f, io.BufferedIOBase)
+ self.assertEqual(f.read().strip(), b"this is file A")
+ with (p / 'fileA').open('rb', buffering=0) as f:
+ self.assertIsInstance(f, io.RawIOBase)
+ self.assertEqual(f.read().strip(), b"this is file A")
+
+ def test_iterdir(self):
+ P = self.cls
+ p = P(BASE)
+ it = p.iterdir()
+ paths = set(it)
+ expected = ['dirA', 'dirB', 'dirC', 'fileA']
+ if not symlink_skip_reason:
+ expected += ['linkA', 'linkB', 'brokenLink']
+ self.assertEqual(paths, { P(BASE, q) for q in expected })
+
+ @with_symlinks
+ def test_iterdir_symlink(self):
+ # __iter__ on a symlink to a directory
+ P = self.cls
+ p = P(BASE, 'linkB')
+ paths = set(p.iterdir())
+ expected = { P(BASE, 'linkB', q) for q in ['fileB', 'linkD'] }
+ self.assertEqual(paths, expected)
+
+ def test_iterdir_nodir(self):
+ # __iter__ on something that is not a directory
+ p = self.cls(BASE, 'fileA')
+ with self.assertRaises(OSError) as cm:
+ next(p.iterdir())
+ # ENOENT or EINVAL under Windows, ENOTDIR otherwise
+ # (see issue #12802)
+ self.assertIn(cm.exception.errno, (errno.ENOTDIR,
+ errno.ENOENT, errno.EINVAL))
+
+ def test_glob_common(self):
+ def _check(glob, expected):
+ self.assertEqual(set(glob), { P(BASE, q) for q in expected })
+ P = self.cls
+ p = P(BASE)
+ it = p.glob("fileA")
+ self.assertIsInstance(it, collections.Iterator)
+ _check(it, ["fileA"])
+ _check(p.glob("fileB"), [])
+ _check(p.glob("dir*/file*"), ["dirB/fileB", "dirC/fileC"])
+ if symlink_skip_reason:
+ _check(p.glob("*A"), ['dirA', 'fileA'])
+ else:
+ _check(p.glob("*A"), ['dirA', 'fileA', 'linkA'])
+ if symlink_skip_reason:
+ _check(p.glob("*B/*"), ['dirB/fileB'])
+ else:
+ _check(p.glob("*B/*"), ['dirB/fileB', 'dirB/linkD',
+ 'linkB/fileB', 'linkB/linkD'])
+ if symlink_skip_reason:
+ _check(p.glob("*/fileB"), ['dirB/fileB'])
+ else:
+ _check(p.glob("*/fileB"), ['dirB/fileB', 'linkB/fileB'])
+
+ def test_rglob_common(self):
+ def _check(glob, expected):
+ self.assertEqual(set(glob), { P(BASE, q) for q in expected })
+ P = self.cls
+ p = P(BASE)
+ it = p.rglob("fileA")
+ self.assertIsInstance(it, collections.Iterator)
+ # XXX cannot test because of symlink loops in the test setup
+ #_check(it, ["fileA"])
+ #_check(p.rglob("fileB"), ["dirB/fileB"])
+ #_check(p.rglob("*/fileA"), [""])
+ #_check(p.rglob("*/fileB"), ["dirB/fileB"])
+ #_check(p.rglob("file*"), ["fileA", "dirB/fileB"])
+ # No symlink loops here
+ p = P(BASE, "dirC")
+ _check(p.rglob("file*"), ["dirC/fileC", "dirC/dirD/fileD"])
+ _check(p.rglob("*/*"), ["dirC/dirD/fileD"])
+
+ def test_glob_dotdot(self):
+ # ".." is not special in globs
+ P = self.cls
+ p = P(BASE)
+ self.assertEqual(set(p.glob("..")), { P(BASE, "..") })
+ self.assertEqual(set(p.glob("dirA/../file*")), { P(BASE, "dirA/../fileA") })
+ self.assertEqual(set(p.glob("../xyzzy")), set())
+
+ def _check_resolve_relative(self, p, expected):
+ q = p.resolve()
+ self.assertEqual(q, expected)
+
+ def _check_resolve_absolute(self, p, expected):
+ q = p.resolve()
+ self.assertEqual(q, expected)
+
+ @with_symlinks
+ def test_resolve_common(self):
+ P = self.cls
+ p = P(BASE, 'foo')
+ with self.assertRaises(OSError) as cm:
+ p.resolve()
+ self.assertEqual(cm.exception.errno, errno.ENOENT)
+ # These are all relative symlinks
+ p = P(BASE, 'dirB', 'fileB')
+ self._check_resolve_relative(p, p)
+ p = P(BASE, 'linkA')
+ self._check_resolve_relative(p, P(BASE, 'fileA'))
+ p = P(BASE, 'dirA', 'linkC', 'fileB')
+ self._check_resolve_relative(p, P(BASE, 'dirB', 'fileB'))
+ p = P(BASE, 'dirB', 'linkD', 'fileB')
+ self._check_resolve_relative(p, P(BASE, 'dirB', 'fileB'))
+ # Now create absolute symlinks
+ d = tempfile.mkdtemp(suffix='-dirD')
+ self.addCleanup(shutil.rmtree, d)
+ os.symlink(os.path.join(d), join('dirA', 'linkX'))
+ os.symlink(join('dirB'), os.path.join(d, 'linkY'))
+ p = P(BASE, 'dirA', 'linkX', 'linkY', 'fileB')
+ self._check_resolve_absolute(p, P(BASE, 'dirB', 'fileB'))
+
+ def test_with(self):
+ p = self.cls(BASE)
+ it = p.iterdir()
+ it2 = p.iterdir()
+ next(it2)
+ with p:
+ pass
+ # I/O operation on closed path
+ self.assertRaises(ValueError, next, it)
+ self.assertRaises(ValueError, next, it2)
+ self.assertRaises(ValueError, p.open)
+ self.assertRaises(ValueError, p.resolve)
+ self.assertRaises(ValueError, p.absolute)
+ self.assertRaises(ValueError, p.__enter__)
+
+ def test_chmod(self):
+ p = self.cls(BASE) / 'fileA'
+ mode = p.stat().st_mode
+ # Clear writable bit
+ new_mode = mode & ~0o222
+ p.chmod(new_mode)
+ self.assertEqual(p.stat().st_mode, new_mode)
+ # Set writable bit
+ new_mode = mode | 0o222
+ p.chmod(new_mode)
+ self.assertEqual(p.stat().st_mode, new_mode)
+
+ # XXX also need a test for lchmod
+
+ def test_stat(self):
+ p = self.cls(BASE) / 'fileA'
+ st = p.stat()
+ self.assertEqual(p.stat(), st)
+ # Change file mode by flipping write bit
+ p.chmod(st.st_mode ^ 0o222)
+ self.addCleanup(p.chmod, st.st_mode)
+ self.assertNotEqual(p.stat(), st)
+
+ @with_symlinks
+ def test_lstat(self):
+ p = self.cls(BASE)/ 'linkA'
+ st = p.stat()
+ self.assertNotEqual(st, p.lstat())
+
+ def test_lstat_nosymlink(self):
+ p = self.cls(BASE) / 'fileA'
+ st = p.stat()
+ self.assertEqual(st, p.lstat())
+
+ @unittest.skipUnless(pwd, "the pwd module is needed for this test")
+ def test_owner(self):
+ p = self.cls(BASE) / 'fileA'
+ uid = p.stat().st_uid
+ name = pwd.getpwuid(uid).pw_name
+ self.assertEqual(name, p.owner())
+
+ @unittest.skipUnless(grp, "the grp module is needed for this test")
+ def test_group(self):
+ p = self.cls(BASE) / 'fileA'
+ gid = p.stat().st_gid
+ name = grp.getgrgid(gid).gr_name
+ self.assertEqual(name, p.group())
+
+ def test_unlink(self):
+ p = self.cls(BASE) / 'fileA'
+ p.unlink()
+ self.assertFileNotFound(p.stat)
+ self.assertFileNotFound(p.unlink)
+
+ def test_rmdir(self):
+ p = self.cls(BASE) / 'dirA'
+ for q in p.iterdir():
+ q.unlink()
+ p.rmdir()
+ self.assertFileNotFound(p.stat)
+ self.assertFileNotFound(p.unlink)
+
+ def test_rename(self):
+ P = self.cls(BASE)
+ p = P / 'fileA'
+ size = p.stat().st_size
+ # Renaming to another path
+ q = P / 'dirA' / 'fileAA'
+ p.rename(q)
+ self.assertEqual(q.stat().st_size, size)
+ self.assertFileNotFound(p.stat)
+ # Renaming to a str of a relative path
+ r = rel_join('fileAAA')
+ q.rename(r)
+ self.assertEqual(os.stat(r).st_size, size)
+ self.assertFileNotFound(q.stat)
+
+ def test_replace(self):
+ P = self.cls(BASE)
+ p = P / 'fileA'
+ size = p.stat().st_size
+ # Replacing a non-existing path
+ q = P / 'dirA' / 'fileAA'
+ p.replace(q)
+ self.assertEqual(q.stat().st_size, size)
+ self.assertFileNotFound(p.stat)
+ # Replacing another (existing) path
+ r = rel_join('dirB', 'fileB')
+ q.replace(r)
+ self.assertEqual(os.stat(r).st_size, size)
+ self.assertFileNotFound(q.stat)
+
+ def test_touch_common(self):
+ P = self.cls(BASE)
+ p = P / 'newfileA'
+ self.assertFalse(p.exists())
+ p.touch()
+ self.assertTrue(p.exists())
+ old_mtime = p.stat().st_mtime
+ # Rewind the mtime sufficiently far in the past to work around
+ # filesystem-specific timestamp granularity.
+ os.utime(str(p), (old_mtime - 10, old_mtime - 10))
+ # The file mtime is refreshed by calling touch() again
+ p.touch()
+ self.assertGreaterEqual(p.stat().st_mtime, old_mtime)
+ p = P / 'newfileB'
+ self.assertFalse(p.exists())
+ p.touch(mode=0o700, exist_ok=False)
+ self.assertTrue(p.exists())
+ self.assertRaises(OSError, p.touch, exist_ok=False)
+
+ def test_mkdir(self):
+ P = self.cls(BASE)
+ p = P / 'newdirA'
+ self.assertFalse(p.exists())
+ p.mkdir()
+ self.assertTrue(p.exists())
+ self.assertTrue(p.is_dir())
+ with self.assertRaises(OSError) as cm:
+ p.mkdir()
+ self.assertEqual(cm.exception.errno, errno.EEXIST)
+ # XXX test `mode` arg
+
+ def test_mkdir_parents(self):
+ # Creating a chain of directories
+ p = self.cls(BASE, 'newdirB', 'newdirC')
+ self.assertFalse(p.exists())
+ with self.assertRaises(OSError) as cm:
+ p.mkdir()
+ self.assertEqual(cm.exception.errno, errno.ENOENT)
+ p.mkdir(parents=True)
+ self.assertTrue(p.exists())
+ self.assertTrue(p.is_dir())
+ with self.assertRaises(OSError) as cm:
+ p.mkdir(parents=True)
+ self.assertEqual(cm.exception.errno, errno.EEXIST)
+ # XXX test `mode` arg
+
+ @with_symlinks
+ def test_symlink_to(self):
+ P = self.cls(BASE)
+ target = P / 'fileA'
+ # Symlinking a path target
+ link = P / 'dirA' / 'linkAA'
+ link.symlink_to(target)
+ self.assertEqual(link.stat(), target.stat())
+ self.assertNotEqual(link.lstat(), target.stat())
+ # Symlinking a str target
+ link = P / 'dirA' / 'linkAAA'
+ link.symlink_to(str(target))
+ self.assertEqual(link.stat(), target.stat())
+ self.assertNotEqual(link.lstat(), target.stat())
+ self.assertFalse(link.is_dir())
+ # Symlinking to a directory
+ target = P / 'dirB'
+ link = P / 'dirA' / 'linkAAAA'
+ link.symlink_to(target, target_is_directory=True)
+ self.assertEqual(link.stat(), target.stat())
+ self.assertNotEqual(link.lstat(), target.stat())
+ self.assertTrue(link.is_dir())
+ self.assertTrue(list(link.iterdir()))
+
+ def test_is_dir(self):
+ P = self.cls(BASE)
+ self.assertTrue((P / 'dirA').is_dir())
+ self.assertFalse((P / 'fileA').is_dir())
+ self.assertFalse((P / 'non-existing').is_dir())
+ if not symlink_skip_reason:
+ self.assertFalse((P / 'linkA').is_dir())
+ self.assertTrue((P / 'linkB').is_dir())
+ self.assertFalse((P/ 'brokenLink').is_dir())
+
+ def test_is_file(self):
+ P = self.cls(BASE)
+ self.assertTrue((P / 'fileA').is_file())
+ self.assertFalse((P / 'dirA').is_file())
+ self.assertFalse((P / 'non-existing').is_file())
+ if not symlink_skip_reason:
+ self.assertTrue((P / 'linkA').is_file())
+ self.assertFalse((P / 'linkB').is_file())
+ self.assertFalse((P/ 'brokenLink').is_file())
+
+ def test_is_symlink(self):
+ P = self.cls(BASE)
+ self.assertFalse((P / 'fileA').is_symlink())
+ self.assertFalse((P / 'dirA').is_symlink())
+ self.assertFalse((P / 'non-existing').is_symlink())
+ if not symlink_skip_reason:
+ self.assertTrue((P / 'linkA').is_symlink())
+ self.assertTrue((P / 'linkB').is_symlink())
+ self.assertTrue((P/ 'brokenLink').is_symlink())
+
+ def test_is_fifo_false(self):
+ P = self.cls(BASE)
+ self.assertFalse((P / 'fileA').is_fifo())
+ self.assertFalse((P / 'dirA').is_fifo())
+ self.assertFalse((P / 'non-existing').is_fifo())
+
+ @unittest.skipUnless(hasattr(os, "mkfifo"), "os.mkfifo() required")
+ def test_is_fifo_true(self):
+ P = self.cls(BASE, 'myfifo')
+ os.mkfifo(str(P))
+ self.assertTrue(P.is_fifo())
+ self.assertFalse(P.is_socket())
+ self.assertFalse(P.is_file())
+
+ def test_is_socket_false(self):
+ P = self.cls(BASE)
+ self.assertFalse((P / 'fileA').is_socket())
+ self.assertFalse((P / 'dirA').is_socket())
+ self.assertFalse((P / 'non-existing').is_socket())
+
+ @unittest.skipUnless(hasattr(socket, "AF_UNIX"), "Unix sockets required")
+ def test_is_socket_true(self):
+ P = self.cls(BASE, 'mysock')
+ sock = socket.socket(socket.SOCK_STREAM, socket.AF_UNIX)
+ self.addCleanup(sock.close)
+ sock.bind(str(P))
+ self.assertTrue(P.is_socket())
+ self.assertFalse(P.is_fifo())
+ self.assertFalse(P.is_file())
+
+ def test_is_block_device_false(self):
+ P = self.cls(BASE)
+ self.assertFalse((P / 'fileA').is_block_device())
+ self.assertFalse((P / 'dirA').is_block_device())
+ self.assertFalse((P / 'non-existing').is_block_device())
+
+ def test_is_char_device_false(self):
+ P = self.cls(BASE)
+ self.assertFalse((P / 'fileA').is_char_device())
+ self.assertFalse((P / 'dirA').is_char_device())
+ self.assertFalse((P / 'non-existing').is_char_device())
+
+ def test_is_char_device_true(self):
+ # Under Unix, /dev/null should generally be a char device
+ P = self.cls('/dev/null')
+ if not P.exists():
+ self.skipTest("/dev/null required")
+ self.assertTrue(P.is_char_device())
+ self.assertFalse(P.is_block_device())
+ self.assertFalse(P.is_file())
+
+ def test_pickling_common(self):
+ p = self.cls(BASE, 'fileA')
+ for proto in range(0, pickle.HIGHEST_PROTOCOL + 1):
+ dumped = pickle.dumps(p, proto)
+ pp = pickle.loads(dumped)
+ self.assertEqual(pp.stat(), p.stat())
+
+ def test_parts_interning(self):
+ P = self.cls
+ p = P('/usr/bin/foo')
+ q = P('/usr/local/bin')
+ # 'usr'
+ self.assertIs(p.parts[1], q.parts[1])
+ # 'bin'
+ self.assertIs(p.parts[2], q.parts[3])
+
+
+class PathTest(_BasePathTest, unittest.TestCase):
+ cls = pathlib.Path
+
+ def test_concrete_class(self):
+ p = self.cls('a')
+ self.assertIs(type(p),
+ pathlib.WindowsPath if os.name == 'nt' else pathlib.PosixPath)
+
+ def test_unsupported_flavour(self):
+ if os.name == 'nt':
+ self.assertRaises(NotImplementedError, pathlib.PosixPath)
+ else:
+ self.assertRaises(NotImplementedError, pathlib.WindowsPath)
+
+
+ at only_posix
+class PosixPathTest(_BasePathTest, unittest.TestCase):
+ cls = pathlib.PosixPath
+
+ def _check_symlink_loop(self, *args):
+ path = self.cls(*args)
+ with self.assertRaises(RuntimeError):
+ print(path.resolve())
+
+ def test_open_mode(self):
+ old_mask = os.umask(0)
+ self.addCleanup(os.umask, old_mask)
+ p = self.cls(BASE)
+ with (p / 'new_file').open('wb'):
+ pass
+ st = os.stat(join('new_file'))
+ self.assertEqual(stat.S_IMODE(st.st_mode), 0o666)
+ os.umask(0o022)
+ with (p / 'other_new_file').open('wb'):
+ pass
+ st = os.stat(join('other_new_file'))
+ self.assertEqual(stat.S_IMODE(st.st_mode), 0o644)
+
+ def test_touch_mode(self):
+ old_mask = os.umask(0)
+ self.addCleanup(os.umask, old_mask)
+ p = self.cls(BASE)
+ (p / 'new_file').touch()
+ st = os.stat(join('new_file'))
+ self.assertEqual(stat.S_IMODE(st.st_mode), 0o666)
+ os.umask(0o022)
+ (p / 'other_new_file').touch()
+ st = os.stat(join('other_new_file'))
+ self.assertEqual(stat.S_IMODE(st.st_mode), 0o644)
+ (p / 'masked_new_file').touch(mode=0o750)
+ st = os.stat(join('masked_new_file'))
+ self.assertEqual(stat.S_IMODE(st.st_mode), 0o750)
+
+ @with_symlinks
+ def test_resolve_loop(self):
+ # Loop detection for broken symlinks under POSIX
+ P = self.cls
+ # Loops with relative symlinks
+ os.symlink('linkX/inside', join('linkX'))
+ self._check_symlink_loop(BASE, 'linkX')
+ os.symlink('linkY', join('linkY'))
+ self._check_symlink_loop(BASE, 'linkY')
+ os.symlink('linkZ/../linkZ', join('linkZ'))
+ self._check_symlink_loop(BASE, 'linkZ')
+ # Loops with absolute symlinks
+ os.symlink(join('linkU/inside'), join('linkU'))
+ self._check_symlink_loop(BASE, 'linkU')
+ os.symlink(join('linkV'), join('linkV'))
+ self._check_symlink_loop(BASE, 'linkV')
+ os.symlink(join('linkW/../linkW'), join('linkW'))
+ self._check_symlink_loop(BASE, 'linkW')
+
+ def test_glob(self):
+ P = self.cls
+ p = P(BASE)
+ self.assertEqual(set(p.glob("FILEa")), set())
+
+ def test_rglob(self):
+ P = self.cls
+ p = P(BASE, "dirC")
+ self.assertEqual(set(p.rglob("FILEd")), set())
+
+
+ at only_nt
+class WindowsPathTest(_BasePathTest, unittest.TestCase):
+ cls = pathlib.WindowsPath
+
+ def test_glob(self):
+ P = self.cls
+ p = P(BASE)
+ self.assertEqual(set(p.glob("FILEa")), { P(BASE, "fileA") })
+
+ def test_rglob(self):
+ P = self.cls
+ p = P(BASE, "dirC")
+ self.assertEqual(set(p.rglob("FILEd")), { P(BASE, "dirC/dirD/fileD") })
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -65,6 +65,8 @@
Library
-------
+- Issue #19673: Add pathlib to the stdlib as a provisional module (PEP 428).
+
- Issue #17916: Added dis.Bytecode.from_traceback() and
dis.Bytecode.current_offset to easily display "current instruction"
markers in the new disassembly API (Patch by Claudiu Popa).
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list