796 lines
63 KiB
HTML
796 lines
63 KiB
HTML
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="color-scheme" content="light dark">
|
||
<title>PEP 355 – Path - Object oriented filesystem paths | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0355/">
|
||
<link rel="stylesheet" href="../_static/style.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
|
||
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
|
||
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
|
||
<meta property="og:title" content='PEP 355 – Path - Object oriented filesystem paths | peps.python.org'>
|
||
<meta property="og:description" content="This PEP describes a new class, Path, to be added to the os module, for handling paths in an object oriented fashion. The “weak” deprecation of various related functions is also discussed and recommended.">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0355/">
|
||
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
|
||
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
|
||
<meta property="og:image:alt" content="Python PEPs">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="description" content="This PEP describes a new class, Path, to be added to the os module, for handling paths in an object oriented fashion. The “weak” deprecation of various related functions is also discussed and recommended.">
|
||
<meta name="theme-color" content="#3776ab">
|
||
</head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Following system colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="9"></circle>
|
||
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected dark colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected light colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
<script>
|
||
|
||
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
|
||
</script>
|
||
<section id="pep-page-section">
|
||
<header>
|
||
<h1>Python Enhancement Proposals</h1>
|
||
<ul class="breadcrumbs">
|
||
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </li>
|
||
<li>PEP 355</li>
|
||
</ul>
|
||
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 355 – Path - Object oriented filesystem paths</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Björn Lindqvist <bjourne at gmail.com></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Formally declined and will not be accepted">Rejected</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">24-Jan-2006</dd>
|
||
<dt class="field-odd">Python-Version<span class="colon">:</span></dt>
|
||
<dd class="field-odd">2.5</dd>
|
||
<dt class="field-even">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-even"><p></p></dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#rejection-notice">Rejection Notice</a></li>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#background">Background</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a></li>
|
||
<li><a class="reference internal" href="#replacing-older-functions-with-the-path-class">Replacing older functions with the Path class</a></li>
|
||
<li><a class="reference internal" href="#deprecations">Deprecations</a></li>
|
||
<li><a class="reference internal" href="#closed-issues">Closed Issues</a></li>
|
||
<li><a class="reference internal" href="#open-issues">Open Issues</a></li>
|
||
<li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li><a class="reference internal" href="#references-and-footnotes">References and Footnotes</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<section id="rejection-notice">
|
||
<h2><a class="toc-backref" href="#rejection-notice" role="doc-backlink">Rejection Notice</a></h2>
|
||
<p>This PEP has been rejected (in this form). The proposed path class
|
||
is the ultimate kitchen sink; but the notion that it’s better to
|
||
implement <strong>all</strong> functionality that uses a path as a method on a single
|
||
class is an anti-pattern. (E.g. why not <code class="docutils literal notranslate"><span class="pre">open()</span></code>? Or <code class="docutils literal notranslate"><span class="pre">execfile()</span></code>?)
|
||
Subclassing from str is a particularly bad idea; many string
|
||
operations make no sense when applied to a path. This PEP has
|
||
lingered, and while the discussion flares up from time to time,
|
||
it’s time to put this PEP out of its misery. A less far-fetched
|
||
proposal might be more palatable.</p>
|
||
</section>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP describes a new class, <code class="docutils literal notranslate"><span class="pre">Path</span></code>, to be added to the <code class="docutils literal notranslate"><span class="pre">os</span></code>
|
||
module, for handling paths in an object oriented fashion. The
|
||
“weak” deprecation of various related functions is also discussed
|
||
and recommended.</p>
|
||
</section>
|
||
<section id="background">
|
||
<h2><a class="toc-backref" href="#background" role="doc-backlink">Background</a></h2>
|
||
<p>The ideas expressed in this PEP are not recent, but have been
|
||
debated in the Python community for many years. Many have felt
|
||
that the API for manipulating file paths as offered in the os.path
|
||
module is inadequate. The first proposal for a <code class="docutils literal notranslate"><span class="pre">Path</span></code> object was
|
||
raised by Just van Rossum on python-dev in 2001 <a class="footnote-reference brackets" href="#id7" id="id1">[2]</a>. In 2003,
|
||
Jason Orendorff released version 1.0 of the “path module” which
|
||
was the first public implementation that used objects to represent
|
||
paths <a class="footnote-reference brackets" href="#id8" id="id2">[3]</a>.</p>
|
||
<p>The path module quickly became very popular and numerous attempts
|
||
were made to get the path module included in the Python standard
|
||
library; <a class="footnote-reference brackets" href="#id9" id="id3">[4]</a>, <a class="footnote-reference brackets" href="#id10" id="id4">[5]</a>, <a class="footnote-reference brackets" href="#id11" id="id5">[6]</a>, <a class="footnote-reference brackets" href="#id12" id="id6">[7]</a>.</p>
|
||
<p>This PEP summarizes the ideas and suggestions people have
|
||
expressed about the path module and proposes that a modified
|
||
version should be included in the standard library.</p>
|
||
</section>
|
||
<section id="motivation">
|
||
<h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2>
|
||
<p>Dealing with filesystem paths is a common task in any programming
|
||
language, and very common in a high-level language like Python.
|
||
Good support for this task is needed, because:</p>
|
||
<ul class="simple">
|
||
<li>Almost every program uses paths to access files. It makes sense
|
||
that a task, that is so often performed, should be as intuitive
|
||
and as easy to perform as possible.</li>
|
||
<li>It makes Python an even better replacement language for
|
||
over-complicated shell scripts.</li>
|
||
</ul>
|
||
<p>Currently, Python has a large number of different functions
|
||
scattered over half a dozen modules for handling paths. This
|
||
makes it hard for newbies and experienced developers to choose
|
||
the right method.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">Path</span></code> class provides the following enhancements over the
|
||
current common practice:</p>
|
||
<ul>
|
||
<li>One “unified” object provides all functionality from previous
|
||
functions.</li>
|
||
<li>Subclassability - the <code class="docutils literal notranslate"><span class="pre">Path</span></code> object can be extended to support
|
||
paths other than filesystem paths. The programmer does not need
|
||
to learn a new API, but can reuse their knowledge of Path
|
||
to deal with the extended class.</li>
|
||
<li>With all related functionality in one place, the right approach
|
||
is easier to learn as one does not have to hunt through many
|
||
different modules for the right functions.</li>
|
||
<li>Python is an object oriented language. Just like files,
|
||
datetimes and sockets are objects so are paths, they are not
|
||
merely strings to be passed to functions. <code class="docutils literal notranslate"><span class="pre">Path</span></code> objects is
|
||
inherently a pythonic idea.</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">Path</span></code> takes advantage of properties. Properties make for more
|
||
readable code:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">imgpath</span><span class="o">.</span><span class="n">ext</span> <span class="o">==</span> <span class="s1">'jpg'</span><span class="p">:</span>
|
||
<span class="n">jpegdecode</span><span class="p">(</span><span class="n">imgpath</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Is better than:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitexit</span><span class="p">(</span><span class="n">imgpath</span><span class="p">)[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="s1">'jpg'</span><span class="p">:</span>
|
||
<span class="n">jpegdecode</span><span class="p">(</span><span class="n">imgpath</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="rationale">
|
||
<h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2>
|
||
<p>The following points summarize the design:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">Path</span></code> extends from string, therefore all code which expects
|
||
string pathnames need not be modified and no existing code will
|
||
break.</li>
|
||
<li>A <code class="docutils literal notranslate"><span class="pre">Path</span></code> object can be created either by using the classmethod
|
||
<code class="docutils literal notranslate"><span class="pre">Path.cwd</span></code>, by instantiating the class with a string representing
|
||
a path or by using the default constructor which is equivalent
|
||
to <code class="docutils literal notranslate"><span class="pre">Path(".")</span></code>.</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">Path</span></code> provides common pathname manipulation, pattern expansion,
|
||
pattern matching and other high-level file operations including
|
||
copying. Basically <code class="docutils literal notranslate"><span class="pre">Path</span></code> provides everything path-related except
|
||
the manipulation of file contents, for which file objects are
|
||
better suited.</li>
|
||
<li>Platform incompatibilities are dealt with by not instantiating
|
||
system specific methods.</li>
|
||
</ul>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<p>This class defines the following public interface (docstrings have
|
||
been extracted from the reference implementation, and shortened
|
||
for brevity; see the reference implementation for more detail):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Path</span><span class="p">(</span><span class="nb">str</span><span class="p">):</span>
|
||
|
||
<span class="c1"># Special Python methods:</span>
|
||
<span class="k">def</span> <span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span> <span class="o">=></span> <span class="n">Path</span>
|
||
<span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> Creates a new path object concatenating the *args. *args</span>
|
||
<span class="sd"> may only contain Path objects or strings. If *args is</span>
|
||
<span class="sd"> empty, Path(os.curdir) is created.</span>
|
||
<span class="sd"> """</span>
|
||
<span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="fm">__add__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">more</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="fm">__radd__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> <span class="o">...</span>
|
||
|
||
<span class="c1"># Alternative constructor.</span>
|
||
<span class="k">def</span> <span class="nf">cwd</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span> <span class="o">...</span>
|
||
|
||
<span class="c1"># Operations on path strings:</span>
|
||
<span class="k">def</span> <span class="nf">abspath</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">=></span> <span class="n">Path</span>
|
||
<span class="w"> </span><span class="sd">"""Returns the absolute path of self as a new Path object."""</span>
|
||
<span class="k">def</span> <span class="nf">normcase</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">normpath</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">realpath</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">expanduser</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">expandvars</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">basename</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">expand</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">splitpath</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">=></span> <span class="p">(</span><span class="n">Path</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
|
||
<span class="w"> </span><span class="sd">"""p.splitpath() -> Return (p.parent, p.name)."""</span>
|
||
<span class="k">def</span> <span class="nf">stripext</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">=></span> <span class="n">Path</span>
|
||
<span class="w"> </span><span class="sd">"""p.stripext() -> Remove one file extension from the path."""</span>
|
||
<span class="k">def</span> <span class="nf">splitunc</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># See footnote [1]</span>
|
||
<span class="k">def</span> <span class="nf">splitall</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">relpath</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">relpathto</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dest</span><span class="p">):</span> <span class="o">...</span>
|
||
|
||
<span class="c1"># Properties about the path:</span>
|
||
<span class="n">parent</span> <span class="o">=></span> <span class="n">Path</span>
|
||
<span class="w"> </span><span class="sd">"""This Path's parent directory as a new path object."""</span>
|
||
<span class="n">name</span> <span class="o">=></span> <span class="nb">str</span>
|
||
<span class="w"> </span><span class="sd">"""The name of this file or directory without the full path."""</span>
|
||
<span class="n">ext</span> <span class="o">=></span> <span class="nb">str</span>
|
||
<span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> The file extension or an empty string if Path refers to a</span>
|
||
<span class="sd"> file without an extension or a directory.</span>
|
||
<span class="sd"> """</span>
|
||
<span class="n">drive</span> <span class="o">=></span> <span class="nb">str</span>
|
||
<span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> The drive specifier. Always empty on systems that don't</span>
|
||
<span class="sd"> use drive specifiers.</span>
|
||
<span class="sd"> """</span>
|
||
<span class="n">namebase</span> <span class="o">=></span> <span class="nb">str</span>
|
||
<span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> The same as path.name, but with one file extension</span>
|
||
<span class="sd"> stripped off.</span>
|
||
<span class="sd"> """</span>
|
||
<span class="n">uncshare</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
|
||
|
||
<span class="c1"># Operations that return lists of paths:</span>
|
||
<span class="k">def</span> <span class="nf">listdir</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">dirs</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">files</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">walk</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">walkdirs</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">walkfiles</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">match</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span><span class="p">)</span> <span class="o">=></span> <span class="nb">bool</span>
|
||
<span class="w"> </span><span class="sd">"""Returns True if self.name matches the given pattern."""</span>
|
||
|
||
<span class="k">def</span> <span class="nf">matchcase</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span><span class="p">)</span> <span class="o">=></span> <span class="nb">bool</span>
|
||
<span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> Like match() but is guaranteed to be case sensitive even</span>
|
||
<span class="sd"> on platforms with case insensitive filesystems.</span>
|
||
<span class="sd"> """</span>
|
||
<span class="k">def</span> <span class="nf">glob</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span><span class="p">):</span>
|
||
|
||
<span class="c1"># Methods for retrieving information about the filesystem</span>
|
||
<span class="c1"># path:</span>
|
||
<span class="k">def</span> <span class="nf">exists</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">isabs</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">isdir</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">isfile</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">islink</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">ismount</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">samefile</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># See footnote [1]</span>
|
||
<span class="k">def</span> <span class="nf">atime</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="w"> </span><span class="sd">"""Last access time of the file."""</span>
|
||
<span class="k">def</span> <span class="nf">mtime</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="w"> </span><span class="sd">"""Last-modified time of the file."""</span>
|
||
<span class="k">def</span> <span class="nf">ctime</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> Return the system's ctime which, on some systems (like</span>
|
||
<span class="sd"> Unix) is the time of the last change, and, on others (like</span>
|
||
<span class="sd"> Windows), is the creation time for path.</span>
|
||
<span class="sd"> """</span>
|
||
<span class="k">def</span> <span class="nf">size</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">access</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mode</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># See footnote [1]</span>
|
||
<span class="k">def</span> <span class="nf">stat</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">lstat</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">statvfs</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># See footnote [1]</span>
|
||
<span class="k">def</span> <span class="nf">pathconf</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># See footnote [1]</span>
|
||
|
||
<span class="c1"># Methods for manipulating information about the filesystem</span>
|
||
<span class="c1"># path.</span>
|
||
<span class="k">def</span> <span class="nf">utime</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">times</span><span class="p">)</span> <span class="o">=></span> <span class="kc">None</span>
|
||
<span class="k">def</span> <span class="nf">chmod</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mode</span><span class="p">)</span> <span class="o">=></span> <span class="kc">None</span>
|
||
<span class="k">def</span> <span class="nf">chown</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">uid</span><span class="p">,</span> <span class="n">gid</span><span class="p">)</span> <span class="o">=></span> <span class="kc">None</span> <span class="c1"># See footnote [1]</span>
|
||
<span class="k">def</span> <span class="nf">rename</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">new</span><span class="p">)</span> <span class="o">=></span> <span class="kc">None</span>
|
||
<span class="k">def</span> <span class="nf">renames</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">new</span><span class="p">)</span> <span class="o">=></span> <span class="kc">None</span>
|
||
|
||
<span class="c1"># Create/delete operations on directories</span>
|
||
<span class="k">def</span> <span class="nf">mkdir</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mode</span> <span class="o">=</span> <span class="mi">0777</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">makedirs</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mode</span> <span class="o">=</span> <span class="mi">0777</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">rmdir</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">removedirs</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
|
||
<span class="c1"># Modifying operations on files</span>
|
||
<span class="k">def</span> <span class="nf">touch</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">remove</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">unlink</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
|
||
<span class="c1"># Modifying operations on links</span>
|
||
<span class="k">def</span> <span class="nf">link</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">newpath</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">symlink</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">newlink</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">readlink</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">readlinkabs</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span>
|
||
|
||
<span class="c1"># High-level functions from shutil</span>
|
||
<span class="k">def</span> <span class="nf">copyfile</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dst</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">copymode</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dst</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">copystat</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dst</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">copy</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dst</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">copy2</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dst</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">copytree</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dst</span><span class="p">,</span> <span class="n">symlinks</span> <span class="o">=</span> <span class="kc">True</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">move</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dst</span><span class="p">):</span> <span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">rmtree</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ignore_errors</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span> <span class="n">onerror</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span> <span class="o">...</span>
|
||
|
||
<span class="c1"># Special stuff from os</span>
|
||
<span class="k">def</span> <span class="nf">chroot</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># See footnote [1]</span>
|
||
<span class="k">def</span> <span class="nf">startfile</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="o">...</span> <span class="c1"># See footnote [1]</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="replacing-older-functions-with-the-path-class">
|
||
<h2><a class="toc-backref" href="#replacing-older-functions-with-the-path-class" role="doc-backlink">Replacing older functions with the Path class</a></h2>
|
||
<p>In this section, “a ==> b” means that b can be used as a
|
||
replacement for a.</p>
|
||
<p>In the following examples, we assume that the <code class="docutils literal notranslate"><span class="pre">Path</span></code> class is
|
||
imported with <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">path</span> <span class="pre">import</span> <span class="pre">Path</span></code>.</p>
|
||
<ul>
|
||
<li>Replacing <code class="docutils literal notranslate"><span class="pre">os.path.join</span></code>:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">getcwd</span><span class="p">(),</span> <span class="s2">"foobar"</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">Path</span><span class="p">(</span><span class="n">Path</span><span class="o">.</span><span class="n">cwd</span><span class="p">(),</span> <span class="s2">"foobar"</span><span class="p">)</span>
|
||
|
||
<span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">,</span> <span class="s2">"baz"</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">Path</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">,</span> <span class="s2">"baz"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Replacing <code class="docutils literal notranslate"><span class="pre">os.path.splitext</span></code>:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fname</span> <span class="o">=</span> <span class="s2">"Python2.4.tar.gz"</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">fname</span><span class="p">)[</span><span class="mi">1</span><span class="p">]</span>
|
||
<span class="o">==></span>
|
||
<span class="n">fname</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="s2">"Python2.4.tar.gz"</span><span class="p">)</span>
|
||
<span class="n">fname</span><span class="o">.</span><span class="n">ext</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Or if you want both parts:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fname</span> <span class="o">=</span> <span class="s2">"Python2.4.tar.gz"</span>
|
||
<span class="n">base</span><span class="p">,</span> <span class="n">ext</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">fname</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">fname</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="s2">"Python2.4.tar.gz"</span><span class="p">)</span>
|
||
<span class="n">base</span><span class="p">,</span> <span class="n">ext</span> <span class="o">=</span> <span class="n">fname</span><span class="o">.</span><span class="n">namebase</span><span class="p">,</span> <span class="n">fname</span><span class="o">.</span><span class="n">extx</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Replacing <code class="docutils literal notranslate"><span class="pre">glob.glob</span></code>:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">lib_dir</span> <span class="o">=</span> <span class="s2">"/lib"</span>
|
||
<span class="n">libs</span> <span class="o">=</span> <span class="n">glob</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">lib_dir</span><span class="p">,</span> <span class="s2">"*s.o"</span><span class="p">))</span>
|
||
<span class="o">==></span>
|
||
<span class="n">lib_dir</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="s2">"/lib"</span><span class="p">)</span>
|
||
<span class="n">libs</span> <span class="o">=</span> <span class="n">lib_dir</span><span class="o">.</span><span class="n">files</span><span class="p">(</span><span class="s2">"*.so"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="deprecations">
|
||
<h2><a class="toc-backref" href="#deprecations" role="doc-backlink">Deprecations</a></h2>
|
||
<p>Introducing this module to the standard library introduces a need
|
||
for the “weak” deprecation of a number of existing modules and
|
||
functions. These modules and functions are so widely used that
|
||
they cannot be truly deprecated, as in generating
|
||
DeprecationWarning. Here “weak deprecation” means notes in the
|
||
documentation only.</p>
|
||
<p>The table below lists the existing functionality that should be
|
||
deprecated.</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head">Path method/property</th>
|
||
<th class="head">Deprecates function</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td>normcase()</td>
|
||
<td>os.path.normcase()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>normpath()</td>
|
||
<td>os.path.normpath()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>realpath()</td>
|
||
<td>os.path.realpath()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>expanduser()</td>
|
||
<td>os.path.expanduser()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>expandvars()</td>
|
||
<td>os.path.expandvars()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>parent</td>
|
||
<td>os.path.dirname()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>name</td>
|
||
<td>os.path.basename()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>splitpath()</td>
|
||
<td>os.path.split()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>drive</td>
|
||
<td>os.path.splitdrive()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>ext</td>
|
||
<td>os.path.splitext()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>splitunc()</td>
|
||
<td>os.path.splitunc()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>__new__()</td>
|
||
<td>os.path.join(), os.curdir</td>
|
||
</tr>
|
||
<tr class="row-even"><td>listdir()</td>
|
||
<td>os.listdir() [fnmatch.filter()]</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>match()</td>
|
||
<td>fnmatch.fnmatch()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>matchcase()</td>
|
||
<td>fnmatch.fnmatchcase()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>glob()</td>
|
||
<td>glob.glob()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>exists()</td>
|
||
<td>os.path.exists()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>isabs()</td>
|
||
<td>os.path.isabs()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>isdir()</td>
|
||
<td>os.path.isdir()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>isfile()</td>
|
||
<td>os.path.isfile()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>islink()</td>
|
||
<td>os.path.islink()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>ismount()</td>
|
||
<td>os.path.ismount()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>samefile()</td>
|
||
<td>os.path.samefile()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>atime()</td>
|
||
<td>os.path.getatime()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>ctime()</td>
|
||
<td>os.path.getctime()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>mtime()</td>
|
||
<td>os.path.getmtime()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>size()</td>
|
||
<td>os.path.getsize()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>cwd()</td>
|
||
<td>os.getcwd()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>access()</td>
|
||
<td>os.access()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>stat()</td>
|
||
<td>os.stat()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>lstat()</td>
|
||
<td>os.lstat()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>statvfs()</td>
|
||
<td>os.statvfs()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>pathconf()</td>
|
||
<td>os.pathconf()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>utime()</td>
|
||
<td>os.utime()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>chmod()</td>
|
||
<td>os.chmod()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>chown()</td>
|
||
<td>os.chown()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>rename()</td>
|
||
<td>os.rename()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>renames()</td>
|
||
<td>os.renames()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>mkdir()</td>
|
||
<td>os.mkdir()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>makedirs()</td>
|
||
<td>os.makedirs()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>rmdir()</td>
|
||
<td>os.rmdir()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>removedirs()</td>
|
||
<td>os.removedirs()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>remove()</td>
|
||
<td>os.remove()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>unlink()</td>
|
||
<td>os.unlink()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>link()</td>
|
||
<td>os.link()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>symlink()</td>
|
||
<td>os.symlink()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>readlink()</td>
|
||
<td>os.readlink()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>chroot()</td>
|
||
<td>os.chroot()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>startfile()</td>
|
||
<td>os.startfile()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>copyfile()</td>
|
||
<td>shutil.copyfile()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>copymode()</td>
|
||
<td>shutil.copymode()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>copystat()</td>
|
||
<td>shutil.copystat()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>copy()</td>
|
||
<td>shutil.copy()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>copy2()</td>
|
||
<td>shutil.copy2()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>copytree()</td>
|
||
<td>shutil.copytree()</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>move()</td>
|
||
<td>shutil.move()</td>
|
||
</tr>
|
||
<tr class="row-even"><td>rmtree()</td>
|
||
<td>shutil.rmtree()</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">Path</span></code> class deprecates the whole of <code class="docutils literal notranslate"><span class="pre">os.path</span></code>, <code class="docutils literal notranslate"><span class="pre">shutil</span></code>, <code class="docutils literal notranslate"><span class="pre">fnmatch</span></code>
|
||
and <code class="docutils literal notranslate"><span class="pre">glob</span></code>. A big chunk of <code class="docutils literal notranslate"><span class="pre">os</span></code> is also deprecated.</p>
|
||
</section>
|
||
<section id="closed-issues">
|
||
<h2><a class="toc-backref" href="#closed-issues" role="doc-backlink">Closed Issues</a></h2>
|
||
<p>A number contentious issues have been resolved since this PEP
|
||
first appeared on python-dev:</p>
|
||
<ul>
|
||
<li>The <code class="docutils literal notranslate"><span class="pre">__div__()</span></code> method was removed. Overloading the / (division)
|
||
operator may be “too much magic” and make path concatenation
|
||
appear to be division. The method can always be re-added later
|
||
if the BDFL so desires. In its place, <code class="docutils literal notranslate"><span class="pre">__new__()</span></code> got an <code class="docutils literal notranslate"><span class="pre">*args</span></code>
|
||
argument that accepts both <code class="docutils literal notranslate"><span class="pre">Path</span></code> and string objects. The <code class="docutils literal notranslate"><span class="pre">*args</span></code>
|
||
are concatenated with <code class="docutils literal notranslate"><span class="pre">os.path.join()</span></code> which is used to construct
|
||
the <code class="docutils literal notranslate"><span class="pre">Path</span></code> object. These changes obsoleted the problematic
|
||
<code class="docutils literal notranslate"><span class="pre">joinpath()</span></code> method which was removed.</li>
|
||
<li>The methods and the properties <code class="docutils literal notranslate"><span class="pre">getatime()/atime</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">getctime()/ctime</span></code>, <code class="docutils literal notranslate"><span class="pre">getmtime()/mtime</span></code> and <code class="docutils literal notranslate"><span class="pre">getsize()/size</span></code> duplicated
|
||
each other. These methods and properties have been merged to
|
||
<code class="docutils literal notranslate"><span class="pre">atime()</span></code>, <code class="docutils literal notranslate"><span class="pre">ctime()</span></code>, <code class="docutils literal notranslate"><span class="pre">mtime()</span></code> and <code class="docutils literal notranslate"><span class="pre">size()</span></code>. The reason they are not
|
||
properties instead, is because there is a possibility that they
|
||
may change unexpectedly. The following example is not
|
||
guaranteed to always pass the assertion:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">p</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="s2">"foobar"</span><span class="p">)</span>
|
||
<span class="n">s</span> <span class="o">=</span> <span class="n">p</span><span class="o">.</span><span class="n">size</span><span class="p">()</span>
|
||
<span class="k">assert</span> <span class="n">p</span><span class="o">.</span><span class="n">size</span><span class="p">()</span> <span class="o">==</span> <span class="n">s</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="open-issues">
|
||
<h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open Issues</a></h2>
|
||
<p>Some functionality of Jason Orendorff’s path module have been
|
||
omitted:</p>
|
||
<ul>
|
||
<li>Function for opening a path - better handled by the builtin
|
||
<code class="docutils literal notranslate"><span class="pre">open()</span></code>.</li>
|
||
<li>Functions for reading and writing whole files - better handled
|
||
by file objects’ own <code class="docutils literal notranslate"><span class="pre">read()</span></code> and <code class="docutils literal notranslate"><span class="pre">write()</span></code> methods.</li>
|
||
<li>A <code class="docutils literal notranslate"><span class="pre">chdir()</span></code> function may be a worthy inclusion.</li>
|
||
<li>A deprecation schedule needs to be set up. How much
|
||
functionality should <code class="docutils literal notranslate"><span class="pre">Path</span></code> implement? How much of existing
|
||
functionality should it deprecate and when?</li>
|
||
<li>The name obviously has to be either “path” or “Path,” but where
|
||
should it live? In its own module or in <code class="docutils literal notranslate"><span class="pre">os</span></code>?</li>
|
||
<li>Due to <code class="docutils literal notranslate"><span class="pre">Path</span></code> subclassing either <code class="docutils literal notranslate"><span class="pre">str</span></code> or <code class="docutils literal notranslate"><span class="pre">unicode</span></code>, the following
|
||
non-magic, public methods are available on <code class="docutils literal notranslate"><span class="pre">Path</span></code> objects:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">capitalize</span><span class="p">(),</span> <span class="n">center</span><span class="p">(),</span> <span class="n">count</span><span class="p">(),</span> <span class="n">decode</span><span class="p">(),</span> <span class="n">encode</span><span class="p">(),</span>
|
||
<span class="n">endswith</span><span class="p">(),</span> <span class="n">expandtabs</span><span class="p">(),</span> <span class="n">find</span><span class="p">(),</span> <span class="n">index</span><span class="p">(),</span> <span class="n">isalnum</span><span class="p">(),</span>
|
||
<span class="n">isalpha</span><span class="p">(),</span> <span class="n">isdigit</span><span class="p">(),</span> <span class="n">islower</span><span class="p">(),</span> <span class="n">isspace</span><span class="p">(),</span> <span class="n">istitle</span><span class="p">(),</span>
|
||
<span class="n">isupper</span><span class="p">(),</span> <span class="n">join</span><span class="p">(),</span> <span class="n">ljust</span><span class="p">(),</span> <span class="n">lower</span><span class="p">(),</span> <span class="n">lstrip</span><span class="p">(),</span> <span class="n">replace</span><span class="p">(),</span>
|
||
<span class="n">rfind</span><span class="p">(),</span> <span class="n">rindex</span><span class="p">(),</span> <span class="n">rjust</span><span class="p">(),</span> <span class="n">rsplit</span><span class="p">(),</span> <span class="n">rstrip</span><span class="p">(),</span> <span class="n">split</span><span class="p">(),</span>
|
||
<span class="n">splitlines</span><span class="p">(),</span> <span class="n">startswith</span><span class="p">(),</span> <span class="n">strip</span><span class="p">(),</span> <span class="n">swapcase</span><span class="p">(),</span> <span class="n">title</span><span class="p">(),</span>
|
||
<span class="n">translate</span><span class="p">(),</span> <span class="n">upper</span><span class="p">(),</span> <span class="n">zfill</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>On python-dev it has been argued whether this inheritance is
|
||
sane or not. Most persons debating said that most string
|
||
methods doesn’t make sense in the context of filesystem paths –
|
||
they are just dead weight. The other position, also argued on
|
||
python-dev, is that inheriting from string is very convenient
|
||
because it allows code to “just work” with <code class="docutils literal notranslate"><span class="pre">Path</span></code> objects without
|
||
having to be adapted for them.</p>
|
||
<p>One of the problems is that at the Python level, there is no way
|
||
to make an object “string-like enough,” so that it can be passed
|
||
to the builtin function <code class="docutils literal notranslate"><span class="pre">open()</span></code> (and other builtins expecting a
|
||
string or buffer), unless the object inherits from either <code class="docutils literal notranslate"><span class="pre">str</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">unicode</span></code>. Therefore, to not inherit from string requires changes
|
||
in CPython’s core.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The functions and modules that this new module is trying to
|
||
replace (<code class="docutils literal notranslate"><span class="pre">os.path</span></code>, <code class="docutils literal notranslate"><span class="pre">shutil</span></code>, <code class="docutils literal notranslate"><span class="pre">fnmatch</span></code>, <code class="docutils literal notranslate"><span class="pre">glob</span></code> and parts of <code class="docutils literal notranslate"><span class="pre">os</span></code>) are
|
||
expected to be available in future Python versions for a long
|
||
time, to preserve backwards compatibility.</p>
|
||
</section>
|
||
<section id="reference-implementation">
|
||
<h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2>
|
||
<p>Currently, the <code class="docutils literal notranslate"><span class="pre">Path</span></code> class is implemented as a thin wrapper around
|
||
the standard library modules <code class="docutils literal notranslate"><span class="pre">fnmatch</span></code>, <code class="docutils literal notranslate"><span class="pre">glob</span></code>, <code class="docutils literal notranslate"><span class="pre">os</span></code>, <code class="docutils literal notranslate"><span class="pre">os.path</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">shutil</span></code>. The intention of this PEP is to move functionality from
|
||
the aforementioned modules to <code class="docutils literal notranslate"><span class="pre">Path</span></code> while they are being
|
||
deprecated.</p>
|
||
<p>For more detail and an implementation see:</p>
|
||
<blockquote>
|
||
<div><a class="reference external" href="http://wiki.python.org/moin/PathModule">http://wiki.python.org/moin/PathModule</a></div></blockquote>
|
||
</section>
|
||
<section id="examples">
|
||
<h2><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h2>
|
||
<p>In this section, “a ==> b” means that b can be used as a
|
||
replacement for a.</p>
|
||
<ul>
|
||
<li>Make all python files in the a directory executable:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">DIR</span> <span class="o">=</span> <span class="s1">'/usr/home/guido/bin'</span>
|
||
<span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">DIR</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">f</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="s1">'.py'</span><span class="p">):</span>
|
||
<span class="n">path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">DIR</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">chmod</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="mi">0755</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">Path</span><span class="p">(</span><span class="s1">'/usr/home/guido/bin'</span><span class="p">)</span><span class="o">.</span><span class="n">files</span><span class="p">(</span><span class="s2">"*.py"</span><span class="p">):</span>
|
||
<span class="n">f</span><span class="o">.</span><span class="n">chmod</span><span class="p">(</span><span class="mi">0755</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Delete emacs backup files:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">delete_backups</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="n">dirname</span><span class="p">,</span> <span class="n">names</span><span class="p">):</span>
|
||
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">names</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">name</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="s1">'~'</span><span class="p">):</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">dirname</span><span class="p">,</span> <span class="n">name</span><span class="p">))</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">walk</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s1">'HOME'</span><span class="p">],</span> <span class="n">delete_backups</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">d</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s1">'HOME'</span><span class="p">])</span>
|
||
<span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">d</span><span class="o">.</span><span class="n">walkfiles</span><span class="p">(</span><span class="s1">'*~'</span><span class="p">):</span>
|
||
<span class="n">f</span><span class="o">.</span><span class="n">remove</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Finding the relative path to a file:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">b</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="s1">'/users/peter/'</span><span class="p">)</span>
|
||
<span class="n">a</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="s1">'/users/peter/synergy/tiki.txt'</span><span class="p">)</span>
|
||
<span class="n">a</span><span class="o">.</span><span class="n">relpathto</span><span class="p">(</span><span class="n">b</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Splitting a path into directory and filename:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">"/path/to/foo/bar.txt"</span><span class="p">)</span>
|
||
<span class="o">==></span>
|
||
<span class="n">Path</span><span class="p">(</span><span class="s2">"/path/to/foo/bar.txt"</span><span class="p">)</span><span class="o">.</span><span class="n">splitpath</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>List all Python scripts in the current directory tree:<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">list</span><span class="p">(</span><span class="n">Path</span><span class="p">()</span><span class="o">.</span><span class="n">walkfiles</span><span class="p">(</span><span class="s2">"*.py"</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="references-and-footnotes">
|
||
<h2><a class="toc-backref" href="#references-and-footnotes" role="doc-backlink">References and Footnotes</a></h2>
|
||
<p>[1] Method is not guaranteed to be available on all platforms.</p>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id7" role="doc-footnote">
|
||
<dt class="label" id="id7">[<a href="#id1">2</a>]</dt>
|
||
<dd>“(idea) subclassable string: path object?”, van Rossum, 2001
|
||
<a class="reference external" href="https://mail.python.org/pipermail/python-dev/2001-August/016663.html">https://mail.python.org/pipermail/python-dev/2001-August/016663.html</a></aside>
|
||
<aside class="footnote brackets" id="id8" role="doc-footnote">
|
||
<dt class="label" id="id8">[<a href="#id2">3</a>]</dt>
|
||
<dd>“path module v1.0 released”, Orendorff, 2003
|
||
<a class="reference external" href="https://mail.python.org/pipermail/python-announce-list/2003-January/001984.html">https://mail.python.org/pipermail/python-announce-list/2003-January/001984.html</a></aside>
|
||
<aside class="footnote brackets" id="id9" role="doc-footnote">
|
||
<dt class="label" id="id9">[<a href="#id3">4</a>]</dt>
|
||
<dd>“Some RFE for review”, Birkenfeld, 2005
|
||
<a class="reference external" href="https://mail.python.org/pipermail/python-dev/2005-June/054438.html">https://mail.python.org/pipermail/python-dev/2005-June/054438.html</a></aside>
|
||
<aside class="footnote brackets" id="id10" role="doc-footnote">
|
||
<dt class="label" id="id10">[<a href="#id4">5</a>]</dt>
|
||
<dd>“path module”, Orendorff, 2003
|
||
<a class="reference external" href="https://mail.python.org/pipermail/python-list/2003-July/174289.html">https://mail.python.org/pipermail/python-list/2003-July/174289.html</a></aside>
|
||
<aside class="footnote brackets" id="id11" role="doc-footnote">
|
||
<dt class="label" id="id11">[<a href="#id5">6</a>]</dt>
|
||
<dd>“PRE-PEP: new Path class”, Roth, 2004
|
||
<a class="reference external" href="https://mail.python.org/pipermail/python-list/2004-January/201672.html">https://mail.python.org/pipermail/python-list/2004-January/201672.html</a></aside>
|
||
<aside class="footnote brackets" id="id12" role="doc-footnote">
|
||
<dt class="label" id="id12">[<a href="#id6">7</a>]</dt>
|
||
<dd><a class="reference external" href="http://wiki.python.org/moin/PathClass">http://wiki.python.org/moin/PathClass</a></aside>
|
||
</aside>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document has been placed in the public domain.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0355.rst">https://github.com/python/peps/blob/main/peps/pep-0355.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0355.rst">2023-09-09 17:39:29 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#rejection-notice">Rejection Notice</a></li>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#background">Background</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a></li>
|
||
<li><a class="reference internal" href="#replacing-older-functions-with-the-path-class">Replacing older functions with the Path class</a></li>
|
||
<li><a class="reference internal" href="#deprecations">Deprecations</a></li>
|
||
<li><a class="reference internal" href="#closed-issues">Closed Issues</a></li>
|
||
<li><a class="reference internal" href="#open-issues">Open Issues</a></li>
|
||
<li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li><a class="reference internal" href="#references-and-footnotes">References and Footnotes</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0355.rst">Page Source (GitHub)</a>
|
||
</nav>
|
||
</section>
|
||
<script src="../_static/colour_scheme.js"></script>
|
||
<script src="../_static/wrap_tables.js"></script>
|
||
<script src="../_static/sticky_banner.js"></script>
|
||
</body>
|
||
</html> |