SVN authentication support
==========================

This document describes authentication support to both py.path.svnwc and
py.path.svnurl (yet to be implemented). This should allow using the library in
a completely automated situation, without having to provide the credentials
interactively.

Current ideas for implementation
--------------------------------

The credentials are passed to the constructor of the path objects, and are used
(transparently) for every action that accesses the server. Also, when provided,
they are passed recursively to all child objects created by methods such as
join(), ensure(), etc.

It should be configurable in some way whether the credentials should be stored
on disk. Storing them could be nice in certain situations (executive accesses
to the repository will not require the credentials to be passed) but it might
not be desired - for instance if a webserver runs more than one application,
you would not want to pollute the webserver's home directory (if it even has
one). This could be implemented by adding an additional argument to the
constructors, too.

Another addition that I would like to make to the API, which is required to
deal properly with invalid credentials, is add another argument to the
constructors, to specify whether the session should be interactive or not.
This way we can specify whether we want to have the svn client ask for
credentials when the provided credentials are invalid (the current default),
or whether instead an exception should be raised.

Code examples
-------------

So, tying this together, code using this feature would look something like::

  >>> wc = py.path.svnwc(url, username='user', password='pw',
  ...                    interactive=False, cache_auth=False)

Open issues
-----------

* How do we deal with externals properly?

  It looks like the svn command-line client uses the credentials provided for
  all externals, if possible, and either prompts for the password in
  interactive mode, or barfs when --non-interactive is passed. I think it makes
  sense to copy its behaviour here, pass the credentials to any child svn path
  objects (as discussed above), and either let the command-line app ask for
  creds or throw an exception when 'interactive' is set to False (see above).

* Functional testing

  Functional testing is relatively hard, and will not work on all systems. It
  looks like a setup using 'svnserve' is possible, but it will be slow and
  provide relatively little advantages, apart from testing the integration.
  Holger suggested that perhaps functional tests could be skipped in favour
  of only unit tests.

* Many new arguments required

  I think it's not very nice to have so many new arguments to the constructors,
  and especially dislike having an argument that's only useful when other args
  are provided (auth_cache). Not sure how to improve that, though...