=======
py.path
=======

.. contents::
.. sectnum::

The 'py' lib provides an elegant, high-level api to deal with filesystems
and filesystem-like interfaces: :api:`py.path`. Here a simple but powerful 
interface to deal with object trees (reading from and writing to nodes, adding
nodes and examining the structure, etc.) in a filesystem-oriented way is
defined, along with a number of readily available implementations.

source: :source:`py/path/`

Path implementations provided by :api:`py.path`
===============================================

:api:`py.path.local`
--------------------

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.

Example usage, here we use the :api:`py.test.ensuretemp()` function to create
a :api:`py.path.local` object for us (which wraps a directory)::

  >>> 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'

:api:`py.path.svnurl` and :api:`py.path.svnwc`
----------------------------------------------

Two other :api:`py.path` implementations that the py lib provides wrap the
popular `Subversion`_ 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.

Some example usage of :api:`py.path.svnurl`::

  >>> 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'

Example usage of :api:`py.path.svnwc`::

  >>> 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

.. _`Subversion`: http://subversion.tigris.org/


Common vs. specific API
=======================

If required, backend-specific extensions are allowed, but the common API is
already quite rich and should be enough for most of the use cases. This
common set includes functions such as 'path.read()' to read data from a node,
'path.write()' to write data, 'path.listdir()' to get a list of a node's
children, 'path.check()' to examine if a node exists, 'path.join()' to get
to a (grand)child, 'path.visit()' to recursively walk through a node's
children, etc. Only things that are not common on filesystems, such as handling
metadata, will require extensions.

Extending the path interface
----------------------------

XXX do we want to go here at all?!? :|

Future plans
============

Not sure here.

Known problems
==============

There are certain known problems, mostly related to cleanups and consistency
issues:

 * XXX find known issues

We hope to have these solved as good as possible in the 1.0 release of the
py lib.