[MERGE] Add simple Storage object

[John Arbash Meinel]

Aaron Bentley wrote:
> Robert Collins wrote:
>> On Mon, 2008-01-28 at 23:37 -0500, Aaron Bentley wrote:
>>> -----BEGIN PGP SIGNED MESSAGE-----
>>> Hash: SHA1
>>>
>>> Robert Collins wrote:
>>>> I don't see a functional difference between just making everything in
>>>> the base Repository be defined in the primitives you mention, and what
>>>> you present.
>>> I agree there's no functional difference between those two options.  I
>>> want to structure it this way because I think it has benefits for people
>>> developing the code
>>>
>>> 1. It is very clear what a Storage object must implement.  It would not
>>> be nearly so clear what a Repository derivative must implement.
>> Well, using NotImplementedError & our repository interface tests, I have
>> to disagree with you about the difference in clarity here.
> 
> I still feel that a class with 17 methods, 15 of them requiring
> implementation is clearer than a class with 88 methods, 15 of them
> requiring implementation
> 
> (Repos have 81 public methods, and Storage objects have 7 methods that
> aren't present in repos.)
> 
>> There is overlap because one method is old, with warnings about
>> scalability, and one is newer, and we're still evolving to get the right
>> balance (networks are hard, hmmm).
> 
> I like to think that we're getting ever closer to optimal APIs.  I can't
> imagine a more efficient API for build_tree than iter_files_bytes.
> 
>>> 3. The implementation API is not a very friendly one, so it does not
>>> make sense to expose it on Repository.
>> The implementation API could be a set of _ methods.
> 
> Yes, it's certainly doable.  It does seem to blur the notions of public
> and private APIs a bit.  Repository implementors (e.g. bzr-svn) would be
> defining a bunch of methods that they shouldn't call.
> 

Well the other ways I've seen are things like: "def foo() calling 
do_foo()" as the implementation.

do_ is just a different decorator than _, but it may be a bit clearer 
what is going on.



...

>>> 6. Pack repositories have 81 public methods by my count (see below).
>>> This is large and intimidating, and it does not include
>>> Repository.weave_store or VersionedFile, both of which are arguably part
>>> of the Repository interface.  Adding even more methods would not be nice.
>> KnitPackRepository implements 22 methods however; which is pretty small
>> and minimal.
> 
> That's encouraging, because it suggests that our minimal subset of
> functionality is already becoming clear.  That doesn't really
> addresses the point I was making, which was that adding more public
> methods to repositories would make them more intimidating, but your
> response to 3 does.

Well, it also inherits a rather large portion of the functionality from 
KnitRepository rather than the base Repository. And can only do so 
because it uses a pack => knit adapter for other reasons (VersionedFile 
api, etc).

So I guessing a generic new Repository format would have more than 22 
methods to implement.

John
=:->