1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
.. image:: https://img.shields.io/pypi/v/path.py.svg
:target: https://pypi.org/project/path.py
.. image:: https://img.shields.io/pypi/pyversions/path.py.svg
.. image:: https://img.shields.io/travis/jaraco/path.py/master.svg
:target: https://travis-ci.org/jaraco/path.py
.. image:: https://img.shields.io/appveyor/ci/jaraco/path-py/master.svg
:target: https://ci.appveyor.com/project/jaraco/path-py/branch/master
.. image:: https://readthedocs.org/projects/pathpy/badge/?version=latest
:target: https://pathpy.readthedocs.io/en/latest/?badge=latest
``path.py`` implements path objects as first-class entities, allowing
common operations on files to be invoked on those path objects directly. For
example:
.. code-block:: python
from path import Path
d = Path('/home/guido/bin')
for f in d.files('*.py'):
f.chmod(0o755)
# Globbing
for f in d.files('*.py'):
f.chmod(0o755)
# Changing the working directory:
with Path("somewhere"):
# cwd in now `somewhere`
...
# Concatenate paths with /
foo_txt = Path("bar") / "foo.txt"
``path.py`` is `hosted at Github <https://github.com/jaraco/path.py>`_.
Find `the documentation here <https://pathpy.readthedocs.io>`_.
Guides and Testimonials
=======================
Yasoob wrote the Python 101 `Writing a Cleanup Script
<http://freepythontips.wordpress.com/2014/01/23/python-101-writing-a-cleanup-script/>`_
based on ``path.py``.
Installing
==========
Path.py may be installed using ``setuptools``, ``distribute``, or ``pip``::
pip install path.py
The latest release is always updated to the `Python Package Index
<http://pypi.python.org/pypi/path.py>`_.
You may also always download the source distribution (zip/tarball), extract
it, and run ``python setup.py`` to install it.
Advantages
==========
Python 3.4 introduced
`pathlib <https://docs.python.org/3/library/pathlib.html>`_,
which shares many characteristics with ``path.py``. In particular,
it provides an object encapsulation for representing filesystem paths.
One may have imagined ``pathlib`` would supersede ``path.py``.
But the implementation and the usage quickly diverge, and ``path.py``
has several advantages over ``pathlib``:
- ``path.py`` implements ``Path`` objects as a subclass of
``str`` (unicode on Python 2), and as a result these ``Path``
objects may be passed directly to other APIs that expect simple
text representations of paths, whereas with ``pathlib``, one
must first cast values to strings before passing them to
APIs unaware of ``pathlib``. This shortcoming was `addressed
by PEP 519 <https://www.python.org/dev/peps/pep-0519/>`_,
in Python 3.6.
- ``path.py`` goes beyond exposing basic functionality of a path
and exposes commonly-used behaviors on a path, providing
methods like ``rmtree`` (from shlib) and ``remove_p`` (remove
a file if it exists).
- As a PyPI-hosted package, ``path.py`` is free to iterate
faster than a stdlib package. Contributions are welcome
and encouraged.
- ``path.py`` provides a uniform abstraction over its Path object,
freeing the implementer to subclass it readily. One cannot
subclass a ``pathlib.Path`` to add functionality, but must
subclass ``Path``, ``PosixPath``, and ``WindowsPath``, even
if one only wishes to add a ``__dict__`` to the subclass
instances. ``path.py`` instead allows the ``Path.module``
object to be overridden by subclasses, defaulting to the
``os.path``. Even advanced uses of ``path.Path`` that
subclass the model do not need to be concerned with
OS-specific nuances.
Alternatives
============
In addition to
`pathlib <https://docs.python.org/3/library/pathlib.html>`_, the
`pylib project <https://pypi.org/project/py/>`_ implements a
`LocalPath <https://github.com/pytest-dev/py/blob/72601dc8bbb5e11298bf9775bb23b0a395deb09b/py/_path/local.py#L106>`_
class, which shares some behaviors and interfaces with ``path.py``.
Development
===========
To install a development version, use the Github links to clone or
download a snapshot of the latest code. Alternatively, if you have git
installed, you may be able to use ``pip`` to install directly from
the repository::
pip install git+https://github.com/jaraco/path.py.git
Testing
=======
Tests are continuously run by Travis-CI: |BuildStatus|_
.. |BuildStatus| image:: https://secure.travis-ci.org/jaraco/path.py.png
.. _BuildStatus: http://travis-ci.org/jaraco/path.py
To run the tests, refer to the ``.travis.yml`` file for the steps run on the
Travis-CI hosts.
Releasing
=========
Tagged releases are automatically published to PyPI by Travis-CI, assuming
the tests pass.
|
