<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title>[path] </title> <meta content="text/html;charset=ISO-8859-1" name="Content-Type"/> <link href="style.css" media="screen" rel="stylesheet" type="text/css"/></head> <body> <div><a href="http://codespeak.net"><img alt="py lib" height="114" id="pyimg" src="http://codespeak.net/img/pylib.png" width="154"/></a></div> <div id="metaspace"> <div class="project_title">[path] </div> <div id="menubar"><a class="menu" href="index.html">index</a> <a class="menu" href="../../apigen/api/index.html">api</a> <a class="menu" href="../../apigen/source/index.html">source</a> <a class="menu" href="contact.html">contact</a> <a class="menu" href="download.html">download</a></div></div> <div id="contentspace"> <div id="docinfoline"> <div style="float: right; font-style: italic;"> </div></div> <div class="document" id="py-path"> <h1 class="title">py.path</h1> <div class="contents topic" id="contents"> <p class="topic-title first">Contents</p> <ul class="auto-toc simple"> <li><a class="reference internal" href="#path-implementations-provided-by-py-path" id="id1">1 Path implementations provided by py.path</a><ul class="auto-toc"> <li><a class="reference internal" href="#py-path-local" id="id2">1.1 py.path.local</a></li> <li><a class="reference internal" href="#py-path-svnurl-and-py-path-svnwc" id="id3">1.2 py.path.svnurl and py.path.svnwc</a></li> </ul> </li> <li><a class="reference internal" href="#common-vs-specific-api" id="id4">2 Common vs. specific API</a><ul class="auto-toc"> <li><a class="reference internal" href="#examples" id="id5">2.1 Examples</a><ul class="auto-toc"> <li><a class="reference internal" href="#searching-txt-files" id="id6">2.1.1 Searching <span class="incremental">.txt</span> files</a></li> <li><a class="reference internal" href="#working-with-paths" id="id7">2.1.2 Working with Paths</a></li> <li><a class="reference internal" href="#checking-path-types" id="id8">2.1.3 Checking path types</a></li> <li><a class="reference internal" href="#setting-svn-properties" id="id9">2.1.4 Setting svn-properties</a></li> <li><a class="reference internal" href="#svn-authentication" id="id10">2.1.5 SVN authentication</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#known-problems-limitations" id="id11">3 Known problems / limitations</a></li> <li><a class="reference internal" href="#future-plans" id="id12">4 Future plans</a></li> </ul> </div> <p>The 'py' lib provides a uniform high-level api to deal with filesystems and filesystem-like interfaces: <a class="reference external" href="../../apigen/api/path.html">py.path</a>. It aims to offer a central object to fs-like object trees (reading from and writing to files, adding files/directories, examining the types and structure, etc.), and out-of-the-box provides a number of implementations of this API.</p> <div class="section" id="path-implementations-provided-by-py-path"> <h1>1 Path implementations provided by <a class="reference external" href="../../apigen/api/path.html">py.path</a></h1> <div class="section" id="py-path-local"> <h2>1.1 <a class="reference external" href="../../apigen/api/path.local.html">py.path.local</a></h2> <p>The first and most obvious of the implementations is a wrapper around a local filesystem. It's just a bit nicer in usage than the regular Python APIs, and of course all the functionality is bundled together rather than spread over a number of modules.</p> <p>Example usage, here we use the <a class="reference external" href="../../apigen/api/test.ensuretemp.html">py.test.ensuretemp()</a> function to create a <a class="reference external" href="../../apigen/api/path.local.html">py.path.local</a> object for us (which wraps a directory):</p> <pre class="literal-block"> >>> import py >>> temppath = py.test.ensuretemp('py.path_documentation') >>> foopath = temppath.join('foo') # get child 'foo' (lazily) >>> foopath.check() # check if child 'foo' exists False >>> foopath.write('bar') # write some data to it >>> foopath.check() True >>> foopath.read() 'bar' >>> foofile = foopath.open() # return a 'real' file object >>> foofile.read(1) 'b' </pre> </div> <div class="section" id="py-path-svnurl-and-py-path-svnwc"> <h2>1.2 <a class="reference external" href="../../apigen/api/path.svnurl.html">py.path.svnurl</a> and <a class="reference external" href="../../apigen/api/path.svnwc.html">py.path.svnwc</a></h2> <p>Two other <a class="reference external" href="../../apigen/api/path.html">py.path</a> implementations that the py lib provides wrap the popular <a class="reference external" href="http://subversion.tigris.org/">Subversion</a> revision control system: the first (called 'svnurl') by interfacing with a remote server, the second by wrapping a local checkout. Both allow you to access relatively advanced features such as metadata and versioning, and both in a way more user-friendly manner than existing other solutions.</p> <p>Some example usage of <a class="reference external" href="../../apigen/api/path.svnurl.html">py.path.svnurl</a>:</p> <pre class="literal-block"> .. >>> import py .. >>> if not getattr(py.test.config.option, 'checkremote', 0): py.test.skip("use --checkremote to enable svn remote doctests") >>> url = py.path.svnurl('http://codespeak.net/svn/py') >>> info = url.info() >>> info.kind 'dir' >>> firstentry = url.log()[-1] >>> import time >>> time.strftime('%Y-%m-%d', time.gmtime(firstentry.date)) '2004-10-02' </pre> <p>Example usage of <a class="reference external" href="../../apigen/api/path.svnwc.html">py.path.svnwc</a>:</p> <pre class="literal-block"> >>> temp = py.test.ensuretemp('py.path_documentation') >>> wc = py.path.svnwc(temp.join('svnwc')) >>> wc.checkout('http://codespeak.net/svn/py/dist/py/path/local') >>> wc.join('local.py').check() True </pre> </div> </div> <div class="section" id="common-vs-specific-api"> <h1><a class="toc-backref" href="#id4">2 Common vs. specific API</a></h1> <p>All Path objects support a common set of operations, suitable for many use cases and allowing to transparently switch the path object within an application (e.g. from "local" to "svnwc"). The common set includes functions such as <span class="incremental">path.read()</span> to read all data from a file, <span class="incremental">path.write()</span> to write data, <span class="incremental">path.listdir()</span> to get a list of directory entries, <span class="incremental">path.check()</span> to check if a node exists and is of a particular type, <span class="incremental">path.join()</span> to get to a (grand)child, <span class="incremental">path.visit()</span> to recursively walk through a node's children, etc. Only things that are not common on 'normal' filesystems (yet), such as handling metadata (e.g. the Subversion "properties") require using specific APIs.</p> <div class="section" id="examples"> <h2><a class="toc-backref" href="#id5">2.1 Examples</a></h2> <p>A quick 'cookbook' of small examples that will be useful 'in real life', which also presents parts of the 'common' API, and shows some non-common methods:</p> <div class="section" id="searching-txt-files"> <h3><a class="toc-backref" href="#id6">2.1.1 Searching <span class="incremental">.txt</span> files</a></h3> <p>Search for a particular string inside all files with a .txt extension in a specific directory.</p> <pre class="literal-block"> >>> dirpath = temppath.ensure('testdir', dir=True) >>> dirpath.join('textfile1.txt').write('foo bar baz') >>> dirpath.join('textfile2.txt').write('frob bar spam eggs') >>> subdir = dirpath.ensure('subdir', dir=True) >>> subdir.join('textfile1.txt').write('foo baz') >>> subdir.join('textfile2.txt').write('spam eggs spam foo bar spam') >>> results = [] >>> for fpath in dirpath.visit('*.txt'): ... if 'bar' in fpath.read(): ... results.append(fpath.basename) >>> results ['textfile1.txt', 'textfile2.txt', 'textfile2.txt'] </pre> </div> <div class="section" id="working-with-paths"> <h3><a class="toc-backref" href="#id7">2.1.2 Working with Paths</a></h3> <p>This example shows the <a class="reference external" href="../../apigen/api/path.html">py.path</a> features to deal with filesystem paths Note that the filesystem is never touched, all operations are performed on a string level (so the paths don't have to exist, either):</p> <pre class="literal-block"> >>> p1 = py.path.local('/foo/bar') >>> p2 = p1.join('baz/qux') >>> p2 == py.path.local('/foo/bar/baz/qux') True >>> sep = py.path.local.sep >>> p2.relto(p1).replace(sep, '/') # os-specific path sep in the string 'baz/qux' >>> p3 = p1 / 'baz/qux' # the / operator allows joining, too >>> p2 == p3 True >>> p4 = p1 + ".py" >>> p4.basename == "bar.py" True >>> p4.ext == ".py" True >>> p4.purebasename == "bar" True </pre> <p>This should be possible on every implementation of <a class="reference external" href="../../apigen/api/path.html">py.path</a>, so regardless of whether the implementation wraps a UNIX filesystem, a Windows one, or a database or object tree, these functions should be available (each with their own notion of path seperators and dealing with conversions, etc.).</p> </div> <div class="section" id="checking-path-types"> <h3><a class="toc-backref" href="#id8">2.1.3 Checking path types</a></h3> <p>Now we will show a bit about the powerful 'check()' method on paths, which allows you to check whether a file exists, what type it is, etc.:</p> <pre class="literal-block"> >>> file1 = temppath.join('file1') >>> file1.check() # does it exist? False >>> file1 = file1.ensure(file=True) # 'touch' the file >>> file1.check() True >>> file1.check(dir=True) # is it a dir? False >>> file1.check(file=True) # or a file? True >>> file1.check(ext='.txt') # check the extension False >>> textfile = temppath.ensure('text.txt', file=True) >>> textfile.check(ext='.txt') True >>> file1.check(basename='file1') # we can use all the path's properties here True </pre> </div> <div class="section" id="setting-svn-properties"> <h3><a class="toc-backref" href="#id9">2.1.4 Setting svn-properties</a></h3> <p>As an example of 'uncommon' methods, we'll show how to read and write properties in an <a class="reference external" href="../../apigen/api/path.svnwc.html">py.path.svnwc</a> instance:</p> <pre class="literal-block"> >>> wc.propget('foo') '' >>> wc.propset('foo', 'bar') >>> wc.propget('foo') 'bar' >>> len(wc.status().prop_modified) # our own props 1 >>> msg = wc.revert() # roll back our changes >>> len(wc.status().prop_modified) 0 </pre> </div> <div class="section" id="svn-authentication"> <h3><a class="toc-backref" href="#id10">2.1.5 SVN authentication</a></h3> <p>Some uncommon functionality can also be provided as extensions, such as SVN authentication:</p> <pre class="literal-block"> >>> auth = py.path.SvnAuth('anonymous', 'user', cache_auth=False, ... interactive=False) >>> wc.auth = auth >>> wc.update() # this should work >>> path = wc.ensure('thisshouldnotexist.txt') >>> try: ... path.commit('testing') ... except py.process.cmdexec.Error, e: ... pass >>> 'authorization failed' in str(e) True </pre> </div> </div> </div> <div class="section" id="known-problems-limitations"> <h1><a class="toc-backref" href="#id11">3 Known problems / limitations</a></h1> <ul class="simple"> <li>The SVN path objects require the "svn" command line, there is currently no support for python bindings. Parsing the svn output can lead to problems, particularly regarding if you have a non-english "locales" setting.</li> <li>While the path objects basically work on windows, there is no attention yet on making unicode paths work or deal with the famous "8.3" filename issues.</li> </ul> </div> <div class="section" id="future-plans"> <h1><a class="toc-backref" href="#id12">4 Future plans</a></h1> <p>The Subversion path implementations are based on the <span class="incremental">svn</span> command line, not on the bindings. It makes sense now to directly use the bindings.</p> <p>Moreover, it would be good, also considering <a class="reference external" href="execnet.html">py.execnet</a> distribution of programs, to be able to manipulate Windows Paths on Linux and vice versa. So we'd like to consider refactoring the path implementations to provide this choice (and getting rid of platform-dependencies as much as possible).</p> <p>There is some experimental small approach (<a class="reference external" href="../../apigen/source/path/gateway/index.html">py/path/gateway/</a>) aiming at having a convenient Remote Path implementation and some considerations about future works in the according <a class="reference external" href="../../apigen/source/path/gateway/TODO.txt.html">py/path/gateway/TODO.txt</a></p> <p>There are various hacks out there to have Memory-Filesystems and even path objects being directly mountable under Linux (via <span class="incremental">fuse</span>). However, the Path object implementations do not internally have a clean abstraction of going to the filesystem - so with some refactoring it should become easier to have very custom Path objects, still offering the quite full interface without requiring to know about all details of the full path implementation.</p> </div> </div> </div></body></html>