| pathlib offers a set of classes to handle filesystem paths. It offers the |
| following advantages over using string objects: |
| |
| * No more cumbersome use of os and os.path functions. Everything can be |
| done easily through operators, attribute accesses, and method calls. |
| |
| * Embodies the semantics of different path types. For example, comparing |
| Windows paths ignores casing. |
| |
| * Well-defined semantics, eliminating any warts or ambiguities (forward vs. |
| backward slashes, etc.). |
| |
| Requirements |
| ------------ |
| |
| Python 3.2 or later is recommended, but pathlib is also usable with Python 2.7 |
| and 2.6. |
| |
| Install |
| ------- |
| |
| In Python 3.4, pathlib is now part of the standard library. For Python 3.3 |
| and earlier, ``easy_install pathlib`` or ``pip install pathlib`` should do |
| the trick. |
| |
| Examples |
| -------- |
| |
| Importing the module classes:: |
| |
| >>> from pathlib import * |
| |
| Listing Python source files in a directory:: |
| |
| >>> list(p.glob('*.py')) |
| [PosixPath('test_pathlib.py'), PosixPath('setup.py'), |
| PosixPath('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' |
| |
| |
| Documentation |
| ------------- |
| |
| The full documentation can be read at `Read the Docs |
| <https://pathlib.readthedocs.org/>`_. |
| |
| |
| Contributing |
| ------------ |
| |
| Main development now takes place in the Python standard library: see |
| the `Python developer's guide <http://docs.python.org/devguide/>`_, and |
| report issues on the `Python bug tracker <http://bugs.python.org/>`_. |
| |
| However, if you find an issue specific to prior versions of Python |
| (such as 2.7 or 3.2), you can post an issue on the |
| `BitBucket project page <https://bitbucket.org/pitrou/pathlib/>`_. |
| |
| |
| History |
| ------- |
| |
| Version 1.0.1 |
| ^^^^^^^^^^^^^ |
| |
| - Pull request #4: Python 2.6 compatibility by eevee. |
| |
| Version 1.0 |
| ^^^^^^^^^^^ |
| |
| This version brings ``pathlib`` up to date with the official Python 3.4 |
| release, and also fixes a couple of 2.7-specific issues. |
| |
| - Python issue #20765: Add missing documentation for PurePath.with_name() |
| and PurePath.with_suffix(). |
| - Fix test_mkdir_parents when the working directory has additional bits |
| set (such as the setgid or sticky bits). |
| - Python issue #20111: pathlib.Path.with_suffix() now sanity checks the |
| given suffix. |
| - Python issue #19918: Fix PurePath.relative_to() under Windows. |
| - Python issue #19921: When Path.mkdir() is called with parents=True, any |
| missing parent is created with the default permissions, ignoring the mode |
| argument (mimicking the POSIX "mkdir -p" command). |
| - Python issue #19887: Improve the Path.resolve() algorithm to support |
| certain symlink chains. |
| - Make pathlib usable under Python 2.7 with unicode pathnames (only pure |
| ASCII, though). |
| - Issue #21: fix TypeError under Python 2.7 when using new division. |
| - Add tox support for easier testing. |
| |
| Version 0.97 |
| ^^^^^^^^^^^^ |
| |
| This version brings ``pathlib`` up to date with the final API specified |
| in :pep:`428`. The changes are too long to list here, it is recommended |
| to read the `documentation <https://pathlib.readthedocs.org/>`_. |
| |
| .. warning:: |
| The API in this version is partially incompatible with pathlib 0.8 and |
| earlier. Be sure to check your code for possible breakage! |
| |
| Version 0.8 |
| ^^^^^^^^^^^ |
| |
| - Add PurePath.name and PurePath.anchor. |
| - Add Path.owner and Path.group. |
| - Add Path.replace(). |
| - Add Path.as_uri(). |
| - Issue #10: when creating a file with Path.open(), don't set the executable |
| bit. |
| - Issue #11: fix comparisons with non-Path objects. |
| |
| Version 0.7 |
| ^^^^^^^^^^^ |
| |
| - Add '**' (recursive) patterns to Path.glob(). |
| - Fix openat() support after the API refactoring in Python 3.3 beta1. |
| - Add a *target_is_directory* argument to Path.symlink_to() |
| |
| Version 0.6 |
| ^^^^^^^^^^^ |
| |
| - Add Path.is_file() and Path.is_symlink() |
| - Add Path.glob() and Path.rglob() |
| - Add PurePath.match() |
| |
| Version 0.5 |
| ^^^^^^^^^^^ |
| |
| - Add Path.mkdir(). |
| - Add Python 2.7 compatibility by Michele Lacchia. |
| - Make parent() raise ValueError when the level is greater than the path |
| length. |