Suggested changed to the transport API.

[Johan Rydberg]

Hi,

I would like to give the Transport API a needed overhaul.  As I see it
there are two major changes needed; 

 (1) get rid of the file-or-string arguments to the methods, replace them 
     with only file-like objects, and

 (2) let methods such as "put" and "append" return file-like objects to
     which data can be written.

My reason to want to do (1) is that it is just plain ugly.

The main reason for (2), to switch from a "pull" to a "push" approach,
is to make it easier for history formats such as knits and history
deltas.  If you are gonna build a file and store it using a transport
you normally have to create a StringIO-object and invoke "put". This
means that the whole file is kept in memory until written.  Not good.

The current methods with current signatures can be renamed to
something like "store" and "store_multi" if the need is there.

Current usage:

   fp = StringIO()
   fp.write(...)
   print >>fp, 'data'
   fp.seek(0, 0)
   transport.put(path, fp)

Would change to:

   fp = transport.put(path)
   fp.write(...)
   print >>fp, 'data'
   fp.close()

The explicit close is needed to signal that we are done with the file
and the actual contents can be stored.  Some transports, like ftp,
might need to keep a the contents in a temporary file until close() is
invoked, but I see no problem with that.

Another issue with the current API is that there is no way of knowing
that the file-like object that "get" returns is seekable.  This is
important for both knits and history deltas.  

I'll write a test that verified that the objects returned by "get" has
a seek-method, and propose we add it to bzrlib.tests, just to keep track
that transports returns sane objects.

~j