E&S CVS Commit: pylib - Another big refactoring, this one to tighten up on "correctness" by making

[pje at eby-sarna.com]

Module Name:	pylib
Committed By:	pje
Date:		Sun Dec 30 19:36:55 UTC 2001

Modified Files:
	pylib/TW: Builders.py Components.py Interfaces.py __init__.py

Log Message:
Another big refactoring, this one to tighten up on "correctness" by making
errors more uniform, adding stricter checking of parameters, fixing
long-outstanding minor bugs, etc.  Another goal was to further shrink
Components.py, especially by simplifying the 'ComponentBuilder' class where
possible.  This led to some inlining of private methods that were called in
only one place, and the like.  Also, certain items were moved from one file
to another, but this should not be externally visible if you're importing
from the top-level package.

Externally Visible Changes (but which still shouldn't impact most users):

* Removed deprecated & unused 'Ref' builder

* 'SpecificationError' is now the standard error for all TW-detected
  specification problems.  (Previously, 'KeyError', 'NameError', and
  'TypeError' could be thrown.)

* "Vertical inheritance" now *only* includes inheritance from the
  immediately enclosing namespace; previously it could incorrectly
  search further-out namespaces as well.

* The implementation of 'qualifyPath()' is now more "correct" for most
  users.  Specifically, 'qualifyPath()' used to match a path fragment
  based solely on the first name in the path.  Now, the matching is
  based on the *entire* path, which is both more and less strict.
  Previously, such a partial match could fail later in the build
  process, when you tried to use the rest of the qualified path.
  Now, if there is no match at all, 'qualifyPath()' will fail
  immediately, but if only a partial match is made, the search will
  continue up the builder tree.  This means that searching for a
  path '("foo","bar")' will not bind to a parent builder 'foo' unless
  it has a sub-builder 'bar', preventing "false positives" that would
  otherwise interfere with using partial or relative paths to classes.

* Builder APIs and implementations have changed again; this generally
  shouldn't affect you unless you have implemented your own builders
  that either do *not* derive from 'AbstractBuilder', or which assume
  that builder paths include the root builder's name.  (Root
  builder's paths no longer include their own name; this was done to
  simplify handling of relative paths all around.)  Please check the
  diffs if you have implemented builders of your own.

  API change details:

   * Added 'NullParentBuilder' singleton to allow recursive methods to
     "top out" without the need to check whether they have a parent
     builder.

   * New IBuilder methods: 'hasSubpath()', 'getSubBuilder()'

   * New IBuilder attributes: 'name', 'isNotNull'  (Note: 'name' was
     always required, but previously wasn't documented.)

   * New or changed IParentBuilder methods: 'qualifyPath()',
     'getPathFor()', and 'getOutput()'.  (Also, 'getDataForPath()' has been
     removed.)


To view diffs of this commit, you can use the following URL(s):
http://cvs.eby-sarna.com/pylib/TW/Builders.py.diff?r1=1.22&r2=1.23
http://cvs.eby-sarna.com/pylib/TW/Components.py.diff?r1=1.33&r2=1.34
http://cvs.eby-sarna.com/pylib/TW/Interfaces.py.diff?r1=1.8&r2=1.9
http://cvs.eby-sarna.com/pylib/TW/__init__.py.diff?r1=1.7&r2=1.8

To generate a diff of this commit:
cvs rdiff -r1.22 -r1.23 pylib/TW/Builders.py
cvs rdiff -r1.33 -r1.34 pylib/TW/Components.py
cvs rdiff -r1.8 -r1.9 pylib/TW/Interfaces.py
cvs rdiff -r1.7 -r1.8 pylib/TW/__init__.py

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.