Re: [Gnu-arch-users] PyArch newbie observations/questions

[David Allouche]

On Tue, May 25, 2004 at 09:54:39AM -0400, Aaron Bentley wrote:
> David Allouche wrote:
> >Yeah! Feedback on PyArch :-)
> 
> Here's more :-)
> 
> >>Are there mappings to changes/what-changed? (If nothing else, I'm
> >>frequently going to want to know if a working tree has uncommitted
> >>changes; I may or may not care what they are).
> >
> >
> >No there are not. Patches welcome.
> >
> >That should be a method in WorkingTree, something like:
> >
> >def changes(self, link=False, output=None)
> 
> I'd rather see delta as a command than changes, since changes can 
> (mostly) be implemented in terms of delta.
> 
> Presumably, it can take a DirName or a revision type for either parameter.

I think DELTA would rather be a top-level function like:

  arch.delta
      a: Revision|ArchSourceTree
      b: Revision|ArchSourceTree
      out: DirName
  => Changeset


In my understanding, CHANGES is different from DELTA in several
ways:

   1. CHANGES can save its output changeset under a default name in the
      tree-root, named after the master revision.

   2. CHANGES can accept a "limit file set" (oh! that needs to be
      supported too) in a way similar to COMMIT.

   3. CHANGES uses the tree-revision by default.

   4. CHANGES is used in different contexts than DELTA, and though it is
      essentially based on a subset of the functionality of DELTA, I
      consider it as an important "library" operation.
      
      On the other hand, DELTA _is_ a fundamental operation of the
      archive layer (unlike CHANGESET which is a fundamental operation
      of the changeset layer) because it is an extension point for
      transparent optimizations (pristines cache, revlib, smart server).

You are welcome to debunk my arguments, so far I think providing a
WorkingTree.changes method would be generally useful and convenient.

> >If output is set, it should be a string, and the changeset will be saved
> >under this name. On normal termination, the method returns a Changeset
> >object whose string value (remember, changesets are DirName objects, so
> >they are string objects) is equal to output.
> 
> What about the stuff changes dumps to stdout, and the diffs output?

The Changeset class should provide all that information in a convenient
and efficient way. The diffs output looks like a CLI convenience feature
to me, not to be supported explicitely in PyArch.

If you can find an use for the incremental and diff output, in
addition to what the Changeset class can provide, please tell me. Right
now I'd rather save only the incremental output for error messages.

Well, I can imagine the incremental output being useful to provide
visual feedback, but it would not really fit the bill (it cannot be used
to provide an ETA) and I do not see offhand how to make it fit in the
current framework.

That could be supported using an extended version of
arch.util.StringOutput (passed as a keword argument to
arch.WorkingTree.changes and arch.delta), but that would need much more
reflexion to get it right.

> >Obviously, the "link" option enable source tree relinking with the
> >revision library.
> 
> Yeah, although that's logically distinct functionality, so it wouldn't 
> be terrible to provide a different function for it.  There was 
> considerable wailing and gnashing of teeth when I made it an option to 
> "changes" in the first place.

I admit I am not sure about that choice. The reason why it was done that
way in tla was because relinking requires doing the greatest part of the
work of CHANGES, and doing it in one place prevented code duplication.
It is a feature of libtla that CHANGES is used to perform relinking.

Whether PyArch should mimick that or not is decided by the following
considerations:

  -- Do we want to stay close of the API provided by libtla?
     I think we agree on yes. So there's a reason to make relinking an
     option of arch.WorkingTree.changes.

  -- Is it in agreement with the Python Zen?
     
     "Explicit is better than implicit", and "There should be one-- and
     preferably only one --obvious way to do it".

     My interpretation is that the Python Zen suggests defining a
     different method arch.WorkingTree.relink (explicit) and not making
     it an option of arch.WorkingTree.changes (only one obvious way).

  -- Practicality beats purity.

     Is it a common occurence for scripts to take the opportunity of
     computing the changes to perform relinking? That's a good question,
     and one I am unable to answer.

     By the way, why does "tla commit" not support relinking?

As you can see, I have not quite made up my mind yet...


On second thought, the correct signature for CHANGES could be:

  arch.WorkingTree.changes
      [output: DirName, default: to the ,,what-changed-* name]
      [master: Revision, default: tree-revision]
      [file_list: iterable of PathName, default: empty]
      [link: bool, default: False]
  => Changeset

It could also raise a TreeLintError if the tree is not commitable, and a
"strict" boolean keyword argument to control when to raise such an
exception. But that would require multiple tree inventories, and that
would be a big performance penalty.

For the sake of expressiveness and to support future optimizations, we
also need a companion method:

  arch.WorkingTree.has_changes
      [master: Revision, default: tree-revision]
      [file_list: iterable of PathName, default: empty]
  => bool

This is a common operation to check only for the _presence_ of any
change, it could be implemented more efficiently, since the outcome is
known once any change is detected, and it does not required the creation
of a changeset on the disk. Currently, that would be implemented using
"tla changes" without --keep or --output.


> >tree-lint is a big problem...
> >
> >Without any option, the output is difficult to parse and is prone to
> >changes, so that's not really reliable.

Frankly, I do not even have a clear idea of what the output of tree-lint
looks like in the general case.

> There's also the option of adding an easily&reliably-parsed output 
> representation to tree-lint.  We could ape "inventory"'s leading-letters 
> scheme, or produce a directory:
> 
> lint-output/untagged-source/foo.c
> lint-output/unsourced-tag/.arch-inventory/bar.c.id
> lint-output/naming-violation/.lala
> etc...

I consider that making changes to tla itself is outside of my scope.
There are already plenty enough of useful things to do in PyArch (and my
other projects) to keep me busy for the forseeable future.

Yet I would really welcome the changes your are proposing.

> That could be factored out into the
> >RevisionIterable, VersionIterable, BranchIterable, and CategoryIterable
> >mixins.
> 
> I don't understand why these are inherited from each other, since all 
> they do is redefine inherited functions to throw exceptions.  But I'm 
> just a grasshopper when it comes to Python.

I admit this class hierarchy is a bit hairy (and actually, those
features needed inheritance in the other direction than the *Iterable
classes). Next thing I'm doing for PyArch is making sure it is correct
and documenting it in the docstring of the arch module.

> Also, I'm a bit confused about how I should be importing pyarch into 
> pyaba.  Should I be adding pyarch/arch to my PYTHONPATH?  Sticking it 
> into my pyaba directory as a nested tree?

That's not a PyArch specific issue.

There are mostly three ways:

  -- Install pyarch system wide with "python setup.py install".

     There might be a way to install it user-locally too, with setup.py,
     check the documentation for distutils:
     
     http://docs.python.org/inst/inst.html
  
  -- Put a (precious) symbolic link to the $(PYARCH)/arch directory in the
     directory containing the pyaba sources.

  -- Add some logic to the main script of pyaba to add the directory
     $(PYARCH)/arch in sys.path.

-- 
                                                            -- ddaa