Log of /PEAK/src/peak/binding/once.py

Parent Directory

No default branch
Bookmark a link to HEAD: (view) (download) (as text)

Added a 'binding.initAttrs()' function that can be used to initialize
an object's attributes from e.g. constructor keyword arguments, similar to
how the 'binding.Component' and 'binding.Attribute' constructors work.
(Also, refactored them to use this new function instead of harcoding their
own versions.)

DEPRECATED 'permissionNeeded' attribute of descriptors, and removed
'security.IGuardedDescriptor'.  Please see CHANGES.txt for more details,
and information on upgrading.  Now 'peak.security' is decoupled from the
PEAK core frameworks, or more precisely, there are no "forward references"
from the PEAK core to 'peak.security', except for the temporary vestigial
implementations of 'permissionNeeded' that will be removed in the next
release.

Added a new "attribute metadata" mini-framework to 'peak.binding'.  This
framework makes it possible to declare arbitrary metadata about attributes,
using either a class advisor ('binding.metadata()', similar in form and
function to the existing 'security.allow()') or using a 'metadata' attribute
of attribute bindings (which is the second positional parameter in all
the standard bindings like 'Make', 'Obtain', etc.).  Over time, existing
metadata mechanisms will be refactored to use this new mini-framework,
instead of the various integrated ad-hoc mechanisms that exist now (like
the 'permissionNeeded' attribute).  For more information on how the new
metadata hooks work, including doctest examples, see the 'attributes.txt'
file in the 'peak.binding' package, under the heading "Attribute Metadata".

Tentative workaround for Singleton bootstrap under Python 2.3.  (Problem
reported by Radek Kanovsky.)

Added a new function, 'binding.activateClass()', that can be used to
activate any bindings in the class.  This can now be used in place of
subclassing a PEAK base class or using a PEAK metaclass.  In future, this
will be integrated into PEAK attribute descriptors such that defining a
descriptor within a class' body is sufficient to cause this function to be
invoked.

This is the first part of a refactoring to implement the attribute metadata
framework for PEAK.

'binding.IBindingNode' was REMOVED, consolidated into 'binding.IComponent',
as its various individual methods have been replaced with generic functions
in the existing 'binding' API. For example, 'binding.getParentComponent(x)'
should be used in preference to 'x.getParentComponent()' unless it is
a requirement that 'x' implement the full 'binding.IComponent' interface.
This makes it easier to define what 'binding.getParentComponent()' and
'binding.getComponentName()' will mean for non-component types, as you do
not have to define an adapter class with all of the 'IBindingNode' methods.
Also, this makes PEAK itself cleaner, as we often weren't bothering to
properly implement the full 'IBindingNode' interface anyway.

In addition, 'binding.suggestParentComponent()' is now also a generic
function, dispatching on the target (i.e. child) object.

Change all adapter factories to use only a single argument.

Remove items that were deprecated during alpha 3 development.  If you've
got code that breaks with this version, check HISTORY.txt for replacements,
or ask on the mailing list.

Configuration system cleanups and new features:

 - Replaced the "[Provide Utilities]" section of .ini files with
   "[Component Factories]".  The new section type is easier to use, much
   more versatile, and does all registration and imports lazily.  See the
   'peak.ini' file for docs.  "[Provide Utilities]" and
   'config.ProvideInstance()' are now DEPRECATED, so please convert ASAP.

 - 'binding.Make()' now accepts configuration keys, using them to look up a
   factory object that's then invoked to create the attribute.  This makes
   it a lot easier to define a component with its own transaction service,
   'IBasicReactor', or other normally "global" component.  It also makes it
   easier to globally specify a factory class for some interface.
   Factories are looked up under the 'config.FactoryFor(key)' configuration
   key.  (See below.)

 - Added 'config.FactoryFor(key)', a 'config.IConfigKey' implementation
   that provides a configuration namespace for factories.

   When you use 'binding.Make(ISomething)', it's roughly equivalent to::

        binding.Make(
            lambda self,d,a:
                binding.lookupComponent(
                    self, config.FactoryFor(ISomething),
                    adaptTo = binding.IRecipe
                )(self,d,a)
        )

   That is, the 'config.FactoryFor(ISomething)' is looked up and invoked.

 - Added 'config.CreateViaFactory(key)', a 'config.IRule' implementation
   that creates an implementation of 'key', by looking up
   'config.FactoryFor(key)'and invoking it.

 - Added 'config.ruleForExpr(name,expr)', that returns a 'config.IRule'
   that computes the Python expression in the string 'expr'.  This is the
   mechanism used by configuration files to create rules, factored out into
   an API call so that configuration extensions can use it, too.

Clean up __repr__'s for bindings, for convenient use of help() and other
documentation tools.

Misc. doc fixes.

Removed all uses of deprecated binding APIs.

First phase of the binding API simplification, including detailed docs
for 'Descriptor' and 'Attribute'.  (Second phase will be mass
search-and-replace of the API's usage in PEAK, third will be additional
tests and docs.)

Added 'binding.Require', 'binding.Obtain', 'binding.Make', and
'binding.Delegate'.  *ALL* other binding types are now DEPRECATED, and will
go away before 0.5 beta is released.  Please see CHANGES.txt for a detailed
mapping of how to translate from the old to new API, and let me know if
anything's missing.

Note that the new 'Make' and 'Obtain' bindings also support sequences of
recipes and keys, and in those cases will produce a sequence of the results
from those recipes or keys.  Also, 'Make' will accept no-argument and
one-argument callables,  where 'Once' always required three-argument
functions.  This should make it a lot easier to write short binding
functions.

Also, note that the 'activateUponAssembly' keyword is now 'uponAssembly',
and 'isVolatile' is now 'noCache'.  (The old names will work as keyword
arguments until the alpha 4 development cycle begins.)  The
'binding.IActiveDescriptor' interface also changed as a result of this.
Last, but not least, a 'binding.IRecipe' interface was added, to support
the new 'binding.Make' type.

Fix typo.

Got rid of worst remaining 'isinstance()' occurrences in binding and
naming; updated TODO.

Added security.Denial() and changed permissionsNeeded -> permissionNeeded,
as described in:

  http://www.eby-sarna.com/pipermail/transwarp/2003-August/000678.html

This is just the security portion; the web and error handling portions of
the proposal are not implemented yet.  Nonetheless, the changes are quite
widespread.  If you are using peak.security or peak.web, please take note
of the interface and implementation changes in this checkin.

Fixed a potential inconsistency in permission handling for base classes, if
permissions weren't queried on the base before permissions on the subclass
were queried.  Also, fixed a problem with 'binding.getInheritedRegistries'
not working on classic classes.  Last, but not least, made simple
'permissionsNeeded' declarations work for peak.model types as well as
binding.Component.

Flesh out security API a little: descriptors and methods can now set
'permissionsNeeded', without needing 'security.allow()', as long as a base
class has used it, or the class derives from binding.Component.  Also,
fixed an issue where subclassing from two different types would not merge
their permissions in the subclass, unless the subclass used
'security.allow()'.

Fix missing interface declaration for ActiveClass; this was causing
problems w/Diagrams.GraphViz.

There is now an interface for "Active Descriptors":
'binding.IActiveDescriptor'.  'peak.binding' now uses this interface to
identify active descriptors, so you can now create your own.  (Previously,
'peak.binding' used 'isinstance()' to detect active descriptors.)

All 'peak.binding' APIs now only accept positional parameters for items
unique to that API.  Items common to multiple APIs (such as 'offerAs',
'doc', 'attrName', etc.) should now be supplied as keyword arguments.

Bindings also now automatically "suggest" the containing object as a parent
component for the contained object, whenever a value is assigned to them or
computed.  If a non-None 'adaptTo' is set on the binding, the value assigned
or computed will be adapted to the specified protocol before the parent
component is suggested.  'binding.New()' no longer relies on the
'IComponentFactory' interface, but instead uses the new adapt/suggest
mechanisms.

Previously, parent components were only "suggested" when a binding was set
via component constructor keyword arguments.  Now, this is done at any time
bindings are set, but *not* for non-binding keyword arguments.  In other
words, ordinary attributes of a component do not receive "suggested parent"
notices, even when set via constructor keyword arguments.  If you want an
attribute to do this, you must define the attribute with the binding API;
e.g. via 'requireBinding()' or 'binding.Constant()'.

The 'provides' keyword argument to various 'peak.binding' APIs has been
renamed to 'offerAs', and it must be a sequence of configuration keys.
(Previously, it accepted either a single key or a tuple of keys.)
The signature of 'binding.Constant()' was changed as well; the first
positional argument is now the constant value, and 'offerAs' is now a
keyword argument.  (Previously, 'provides' was the first positional
argument of 'binding.Constant()'.)  The 'registerProvider()' method of
'config.IConfigurable()' also now accepts only a single configuration key,
as does 'EigenRegistry.register()'.

Fixed up error checking; bindings now can tell again if they're used with
the wrong name in a class that doesn't support them.  But, now they should
also be usable at multiple metalevels without conflict, since the usage
checking only occurs when used in non-supporting classes.  (Don't know what
that means?  Me, either!  It's one of those things that you don't expect
to be a problem, but is.  Or was, now.  I think.  Need to add some tests.)

First phase of descriptor refactoring.  Once bindings now place a proxy for
themselves in a class when activated in that class.  This avoids the need
for Once-derivatives to "copy" themselves when they are found under more
than one name (e.g in the same class or when they are created without a
name initially).  Eventually this will let us do something similar with
model.StructuralFeature objects.  Added hooks to the Once class family to
allow an 'onSet()' method to be called that can alter a value being
setattr'd.  This will let us do automatic 'adapt()' and
'setParentComponent()' when attributes are set or looked up.

Also, simplified the structure of the Pyrex OnceDescriptor base, using
Pyrex 0.7.2's ability to declare C-level attributes visible from Python.
(Previously, we used a custom descriptor to deal with this.)

NOTE: Error checking of bindings is partly BROKEN right now; bindings do
not verify that they haven't been placed in a class that doesn't support
them; they only verify that they have been told what name to use.  This
needs a little review, and the tutorial may need to be adjusted as well.

Moved mixin of ProviderMixin from Activator to MethodExporter, since it is
currently only needed by FeatureClass.  This avoids an extra Python frame
setup when calling adapt() on (non-feature) classes.  Not that a lot of
that happens in PEAK currently, but the AOP tool I'm prototyping does it
a lot.

Removed custom '__conform__' implementations, replace w/support from
'protocols' package.  Fixed a 'supertype()' hole.

Finished switchover to using protocols.advise() API to declare interfaces.

Made interfaces thread-safe for registration.  Added more interfaces to
explain the interface of the interface package.  :)  Refined adapter
comparison algorithm to better understand the "distance" between protocols.
Removed classic-class adapter, since protocols now do reasonable caching
for classic MRO's and subtypes.

And so we bid a fond farewell to introspection as well.  'isImplementedBy'
is now a thing of the past.  Refactored anything that used it, to now
use adapt(), which has now opened up a lot of extension possibilities in
places that were previously not extensible without modifying PEAK core
code.  See below.  Also, the interface module has been refactored to support
'classProvides()' in a clean and kludge-free fashion, along with support for
faster adaptation of old and new-style classes (by caching lookups, and by
safely adding '__conform__' methods to classic classes), and the ability for
classes to manage their own "implements" information.  The core interface
code is now quite elegant in the way it uses its own adaptation system as
the basis for implementing adaptation.  :)

'binding.Acquire()' now accepts a 'default' value argument, and
'binding.New()' no longer accepts the 'bindToOwner' flag.

There is a new 'binding.IComponentKey' interface that is used to implement
'IComponent.lookupComponent()'.  Now you can implement this interface,
or create an adapter for it, in order to make an object usable as an
argument to 'binding.lookupComponent()' - and therefore usable as a key
for 'binding.bindTo()' or 'binding.bindToSequence()'.  Not that it's
necessarily very useful to do so; you're probably better off simply
creating a naming scheme.  But it might be useful for lookups done
in the context of classes, since naming schemes aren't usable there.
(It was actually added in order to factor out all the type testing that
'lookupComponent' used to do, so it doesn't matter if it's useful for
much else.)

PEAK has been refactored to avoid the use of 'isImplementedBy()' and
similar introspection, in favor of 'adapt()'.  As a result, some
'peak.naming' interfaces have changed.  This should not affect you
if you are only subclassing PEAK-provided naming components and not
implementing these interfaces "from scratch".  However, the various
'isAddress', 'isAddressClass', 'isResolver', and 'isName' APIs have
also been removed, as they were based on 'isImplementedBy()'.

The ability to use 'isImplementedBy()' with interfaces declared by PEAK is
REMOVED.  You can still use 'isImplementedBy()' with Zope interfaces, of
course, but we recommend you switch to 'adapt()', which will work with both
PEAK and Zope interfaces.

Added transitive adaptation: declaring an adapter "AB" from A to B, and
"BC" from B to C, automatically implies adaptation from A to C via
BC(AB()).  Used it to simplify the mechanism for adapting an IExecutable
to an ICmdLineAppFactory.  Refactored some of the interface package's
initial kludges to cleaner mechanisms based on adaptation.

Learned some interesting things along the way...  Classic classes don't
have __mro__, which made adapt() break on them.  The technique I was using
in the hopes of suppressing unwanted TypeErrors suppressed wanted ones, and
meanwhile there weren't any unwanted ones in PEAK.  Finally, Python 2.2
doesn't support 'super()' access to properties, and metamethods are
properties, so you have to use my new 'supermeta' to work around this when
you need to call a super() metamethod.  This is supposed to be fixed in
Python 2.3, but not backported 2.2 because Guido considers it a "feature".
Ah well.

__implements__ is dead, long live implements()!  We are also no longer
using 'zope.interface', but instead using a complete, interoperable
replacement for it.  Also, tweaked a few things so that using pydoc or
'help()' on PEAK component classes and interfaces now works halfway
decently, as opposed to producing tracebacks (or dumping core!).

'zope.interface' will soon be removed from the PEAK distribution
altogether.  See CHANGES.txt for details of why this replacement was
created.

Removed unused imports, found by Martijn Faassen's clever 'importchecker'
script. (http://www.zope.org/Members/faassen/importchecker)

Finally got rid of 'x.__class__.foo(x,...)' hacks!  Now, if a metaclass
needs to have a method that one of its instances might also have as an
instance method, you can wrap it with 'binding.metamethod(foo)'.  This
is nice and clean because it doesn't force every caller of the 'foo'
method to try and guess whether it's working with a class or an instance.
Even nicer, this solution requires no special work by the person writing
these methods, unless the method is going into a metaclass, and even then
they need only wrap it with 'metamethod'.

Last, but not least, this cleans up some of our __class__ usage so that
we'll be able to work correctly with 'zope.security'.  As far as I know,
the 'x.__class__.foo(x,..)' trick wouldn't have worked consistently when
'x' was a proxied object, whereas a normal call to 'foo' would properly
pass through the proxy barrier as long as the caller had permission to
access 'foo'.

(Note: at the moment 'foo' translates to the 'getParentComponent',
'_getConfigData', 'getComponentName', and 'notifyUponAssembly' methods.)

Paramegeddon!  Adjusted API signatures so that all calls that have a
context component, have it as the first parameter.  Changed functions,
methods, and classes are:

* binding.acquireComponent()

* binding.lookupComponent()

* config.getProperty()

* config.findUtility()

* config.findUtilities()

* config.PropertyMap.getValueFor()

* config.IConfigSource._getConfigData()

* config.PropertySet()

* naming.lookup()

* naming.parseURL()

Also, renamed 'config.LazyLoader' -> 'config.LazyRule' to reduce confusion
with 'storage.LazyLoader', which has a very different purpose/function.

Stamp out '_provides', replace with 'declareAsProviderOf'.  Removed
extraneous '_provides' declarations left over from the days when classes
could effectively be their own 'binding.New'.  I decided not to document
the interface of attribute binding objects at this time, because the
implementation is tied to the classes right now anyway.

Also, misc. TODO edits.

Replace uses of the deprecated 'binding.Base' with 'binding.Component'.
Updated tutorial for this and other binding.interfaces name changes; note
that the tutorial has *not* been fully reviewed for semantic issues yet.

Added ability to designate standard bindings as 'activateUponAssembly'; you
can now supply this as a keyword argument to just about everything but
'bindToParent()', 'bindToSelf()', 'requireBinding()' and 'delegateTo()'.
(There's no point in activating them, that I can think of.)  Removed
checking for overridden 'uponAssembly()' method, since the standard way to
do things upon assembly is to use a once binding with the new keyword
argument.

Initial implementation of "assembly events" framework.  Components now have
'uponAssembly()' method that gets called as soon as the component's
hierarchy -- that is, all its parents up to the root -- are known.  Some
binding package interfaces were renamed or revised to accomodate this.

This is still a work-in-progress: there are no tests for the new functions,
there needs to be a way to designate bindings as "activate upon assembly",
and this needs to be integrated with the systems that need it (e.g.
periodic tasks, config.Application, etc.)

Refactoring prep for "assembly events".  Deprecated 'binding.Base' in favor
of 'binding.Component'; adjustments to binding interfaces, change 'model'
bases to use a new "superlight" attribute handling base.  Added support
for 'lookupComponent()' to take a default value, so that it's now the most
convenient way to look up *anything*, be it property, utility, URL, or
component name.  Dropped the pointless 'binding.globalLookup()' API, as it
was just syntactic sugar for a 'naming.lookup()'.  Made __class_provides__
a Once binding on the metaclass of 'binding.Component', instead of a
hard-wired collaboration between Once and Activator, so that it doesn't get
computed unless it's needed.  Note that 'peak.model' objects of primitive
or immutable types will now no longer participate in component hierarchies;
this didn't make much sense for value types, anyway.

Partial cleanup of '__class_provides__'; now it's supplied by the most
basic metaclass (Activator), instead of being poked in by 'Once' attributes
after the fact.  There probably really should be a 'registerAttribute'
interface method or something for this, but at least now it's not *too*
unbearably ugly.

Re-added 'binding.Singleton', this time with proper component and metaclass
support.  The new singleton implementation "promotes" all attributes to the
class' metaclass, so that attribute bindings work correctly, and all
methods effectively become class methods.  It also ensures that
'aSingletonClass()' returns 'aSingletonClass' for any singleton class (i.e.
instantiating a singleton returns the singleton).

Minor performance adjustment to previous change; since most attributes of
most classes aren't special, changed introspection code to take less time
for the common case.

Added 'binding.classAttr()' - a wrapper that lets you use bindings as
class attributes, *without* having to manually create a metaclass (one is
automatically generated for you behind the scenes).  Replaced many existing
uses of metaclasses in 'peak.model' with class attributes, although there
are some left that still need to be stomped out.  Added tests for class
attribute functionality.

Update docs and error messages for the departure of 'ActiveDescriptor' base
and 'ActiveDescriptors' metaclass.

Completed conversion to C of the base class descriptor methods for 'Once'
attributes.  Due to constraints in how Pyrex creates extension types, it
was not possible to continue support for the (deprecated anyway) 'OnceClass'
and 'AutoCreatable' metaclasses.  This is now cleaned up pretty decently
and runs the tests at least as fast as before I began the metadata
refactoring yesterday (~4.1 seconds on my Windows PC).

Note that if you want to build from Pyrex source or have Pyrex installed,
you *must* patch Pyrex.Compiler.TypeSlots so that these two lines:

descrgetfunc = Signature("TOO", "O")       # typedef ...
descrsetfunc = Signature("TOO", "O")       # typedef ...

Look like *this* instead:

descrgetfunc = Signature("Tpp", "O")       # typedef ...
descrsetfunc = Signature("TOp", "i")       # typedef ...

This is a work-around for improper generation of descriptor __get__/__set__
code by Pyrex.

Refactored to allow "lazy" metadata computation, using bindings.
This means that you can use attribute bindings in metaclasses to assemble
metadata registries, such as those needed for XMI.

Unfortunately, for this to work on types, I had to change the fundamental
implementation of attribute bindings to a new implementation in Pyrex/C.
The problem is that only *data* descriptors from a metaclass are invoked
if there is an attribute value available in the type's dictionary or the
dictionary of one of its base types.  This means that trying to have
'Once' bindings that attach to classes via their metaclass, is inherently
unstable unless you make use of the bindings in strict reverse __mro__
order!  This problem has actually existed ever since I added the ability
to use bindings in metaclasses, but because of the way things were being
used, it "just happened" to look like it was working.

So I had to make 'Once' a data descriptor; unfortunately this means that
it has to check whether the value appears in the object's dictionary
*every* time the attribute is accessed.  That's still doable from Python,
but the bigger problem is that type dictionaries aren't accessible from
pure Python code, and the only way to implement the __set__ function on
a 'Once' descriptor is by writing to the dictionary.  So I wrote a Pyrex
extension type to support getting at the object's true dictionary, and
to implement a (relatively) fast __get__ method.  The result seems to
perform about as well as the old version, although I'm tempted to redo
some of it in pure C to get rid of a lot of overhead that would be
avoidable if Pyrex properly supported the '__get__' signature for
extension types.

Up next: standardizing the metaclass naming convention, documenting all this
stuff, then maybe on to XMI writing...

Removed all known usage of AutoCreated et al, and marked the appropriate
docstrings as "DEPRECATED".  There really weren't that many places where
we relied on AutoCreated behavior, and making them explicit with
binding.New() actually does seem to improve the clarity of the code.

Note to self: NEVER mix 'object'-derivatives in the bases of a metaclass!
It can cause Python 2.2.x (yes, even 2.2.2) to coredump in the 'help()'
function, when it tries to access the screwed-up '__weakref__' member of
instances of the metaclass.  Prior to this check-in, the following code::

 >>> class foo(binding.Base):
         pass

 >>> help(foo)

would cause a coredump in 2.2.2!  'binding.OnceClass' and
'binding.AutoCreated' are probably still broken in the same way, but I
think maybe we should get rid of them anyway.  I'll post a proposal to the
mailing list for this.

Note that this bug has absolutely nothing to do with PEAK -- it's a known
Python 2.2.x problem with new-style classes which I keep bumping my head
into.  But the last few times I didn't successfully learn the full range
of things that can cause it.  Now I think I've got the hang of it.  In
theory, Python 2.3 doesn't have these issues, but 2.3 won't be our target
for several months yet.  Though perhaps it would be good to verify the
fixing of this little snafu...  Another way to cause the same coredump is::

 >>> class x(object): pass

 >>> class y(type,x): pass

 >>> class z: __metaclass__ = x

 >>> help(z)

Ugh.

Fixed some interface declaration issues.

Refactored TraversableClass + ActiveDecscriptors -> ActiveClass, creating
a uniform metaclass heterarchy (whatever that means).  ActiveClasses don't
need setupModule() to tell them their parents; they assume that if they're
activated inside a class from the same module, then that class is their
parent.  So I was able to put back in the optimization of skipping class
re-creation when a module is first loaded.  Anyway, ActiveClass is now the
base metaclass for pretty much everything in PEAK, and so all PEAK classes
are now valid components in much the same way that their instances are.

Refactored to remove peak.metamodels.xmi.Reading as a mixin module.  There
is now a peak.model.xmi module (accessible as 'model.xmi') that provides
XMI loading services, and XMI metadata is now generated automatically by
model classes.  Note that this change also changes the signature of
'ActiveDescriptor.activate()' to better support 'super()' calls between
co-operative descriptor mixins.

Changes to allow "once" bindings to be used in metaclasses and applied to
classes, just as they previously were used in classes and applied to
instances.

Fixed problems with running help() on a class with attribute bindings.

Components now support names and paths:

* Objects created by naming system lookup, binding.New(), or
  AutoCreated, can all now automatically receive information
  about their name as well as their parent component.

* binding.getComponentName() gets an object's name or 'None'

* binding.getComponentPath(c, relativeTo=None) gets an object's
  path from its root component, or as a relative path from
  'relativeTo' (assumes 'relativeTo' is a parent of 'c').
  Unknown names are rendered as '*' in the path.

* Added 'binding.Acquire' after all.

* Improved management of _p_jar/_p_oid by model.Element, using
  _p_jar as the parent component, and _p_oid as the component
  name for elements.

* Added unit tests for name and path support.

Reorgs and and misc. cleanups; updated TODO for 0.5a1 vs 0.5final

Moved ActiveDescriptor(s) classes from binding.meta to binding.once and the
rest of binding.meta to model.method_exporter.  Moved the method-exporter
tests that lived in metamodels.tests.General to model.tests, where they
really belonged, and added model.tests to the install and API test suite.

* Added 'binding.Constant(key, value)', which allows you to specify
  a constant value to be used as a property or utility in that
  component subtree.

* Added storage.get/begin/commit/abortTransaction() APIs for ease
  of use in short scripts.  Defined a default provider for
  ITransactionService in peak.ini that provides each component root
  with its own TransactionService instance.  It's easily replaceable
  with other allocation strategies, if it should be needed.  I may
  change this later to a per-root strategy, since the current strategy
  requires creating localConfigs for each component root.  We'll see
  what actual use has to say about the best way of doing it.

* Fixed a problem with local/global config object startup that could
  cause "phantom" configuration objects to appear via recursion of
  getLocal() or getGlobal().

* Got rid of binding.meta.assertInterfaces, which is no longer needed
  because the Interface package now correctly handles metaclass
  instances.

* Got rid of Singleton, since it's not used for anything and I could
  neither think of any use cases nor remember why I added it in the
  first place!

* Made it possible for CachingProviders to cache per-localConfig as well
  as per-object.  This is handy for implementing per-hierarchy services,
  like the TransactionService provider mentioned above.

* Misc. TODO updates.

Re-org/refactoring of many items from the TODO list for 0.5, including:

* moved peak.binding.imports -> peak.util.imports, added importSuite()

* Decided not to do binding.Acquire, it should just be a documented idiom

* Moved LDAP and lockfile URLs to peak.storage.LDAP and
  peak.running.lockfiles, respectively

* Moved factories.getObjectInstance -> spi, updated peak.ini to load
  naming.spi as the provider.

* Consolidated naming.references into naming.names

* Made ParsedURLs compile their pattern strings, and automatically make
  their 'fromX()' methods classmethods (and the same is true for other
  'struct' types.

* Refactored cursors and connections out into distinct SQLCursor/LDAPCursor
  types, based on a common AbstractCursor.

* Added TooManyResults/TooFewResults errors to peak.exceptions

Properties and utilities are unified at last!  Both properties and
utilities are now handled by the __instance_provides__ and
__class_provides__ attributes of component classes.  This simplified the
code and interfaces for both PropertyMap and for registering dynamic
utility providers.

Property names now have an additional syntax form: 'some.prop?' which is
used as a default value that is checked after 'some.prop', 'some.*', and
'some.prop' (a second time).  This is handled transparently for you by
way of the 'setDefault()' method of 'IPropertyMap', so effectively it's an
implementation detail.

Documentation is still a little sketchy, but it should now be
straightforward to get the naming system using properties and utilities in
a harmonious way.


ALSO:

Fixed config.getLocal() to ensure it's working with a root component.
binding.New() can now use an import string instead of a
class/type/callable.  The object referenced by the import string will be
loaded and called as though the object itself had been used.  GlobalConfig
and LocalConfig now have 'setup()' methods that can be overridden to
create default rule and provider registrations.  This'll be handy for
making LocalConfig register a default transaction service provider, for
example.

Fixed the attributes-as-utilities problems.  Also unified AutoCreatable
and OnceClass, as they should've been a long time ago.

This is what I was trying to do last night, when the Python bug raised its
ugly head out of the murky swamp that was peak.metamodels.FeatureObject!

Now that all this cruft's out of the way, I can start in on actually
testing the peak.config properties system!

Ported TW.Caching to peak.storage.caches.  (Also misc. code/formatting
fixes.)

Added __name__ and __doc__ capability for most attribute bindings, so that
Python's help() can give more meaningful info.  (Mostly, though, bindings
confuse the heck out of help(), as it thinks that only methods have
descriptors that have '__get__' without '__set__'.)

Eliminated __volatile_attrs__ support.  We wouldn't have been able to do
much with it, anyway.  If you're going to make application components
persistent, you're going to have a lot of other issues to handle besides
your Once attributes being saved.  Chances are good that you'll actually
*want* many of your Once attributes to be saved, anyway.  Most likely,
we'll need a different Component class implementation for persistent
components.

Killed off remaining weakref binding facilities.  We now only use weakrefs
in caches, and even then only via WeakKeyDictionary and
WeakValueDictionary.

Changes to help the tutorial be clearer, when I write it:

bindToNames() -> bindSequence()    # emphasize/clarify its nature
WeakBinding() -> WeakRefBinding()  # ditto
New function: bindToUtilities(iface)  # [x for x in findUtilities(iface)]

Also, some fixes to Once.usageError() and the code that calls it, to
improve usability with non-ActiveDescriptors instances (e.g. old-style
classes).  This'll make the first part of the binding tutorial work better.

Refactored bindings to support 'provides=' keyword argument: an interface
(or nested tuple thereof) specifying what interface(s) that attribute
should be considered a utility for.  Also fixed Once and its derivatives,
plus all component lookup algorithms, to use a single recursion guard
value: peak.api.NOT_FOUND.  None of the new functionality has been tested,
although all the old tests still pass.

Refactored struct metaclass for cleaner construction.  Misc. doc additions.

Added binding.New() and binding.Copy(), which are handy for creating
auto-initializing mutable instance variables, e.g.::

    class MyThing(binding.Component):

        aDict = binding.New(dict)

        aList = binding.Copy( [1,2,'buckle your shoe'] )

Also did a little minor cleanup in peak.model.api.

Hacked on it until all tests pass...  But still a lot of re-name, re-doc,
re-org to go.  Still need to move Caching over, and there are some test
package splits that need to be done (metamodels->model).  Need to make the
Once and other peak.binding package import idioms consistent, too.  But
at least the tests run.  The repository is not yet stable, however.

Refactoring to allow subclasses to reuse error message code

Changed MethodExporter to use a concise and centralized definition of verbs
instead of 'namingConvention' attributes on every function.  This should
make it easier to override method templates in subclasses and in derived
modules, as well as reducing typing when there are multiple variants of
a verb.

The MethodExporter documentation has been lightly updated, but really needs
an overhaul before release, especially with respect to terminology.

Established new API idiom for **kw/mapping/items variants of API calls.

Specifically, the new preferred API parameter form is to accept a list of
key/value pairs (e.g. 'dict.items()'), as that is generally the most
efficient format for non-trivial manipulation.  In essence, if an API
call previously took '**' keyword arguments (and perhaps a mapping as
well), it probably now takes an item list.  The exceptions are things
like constructors for infrequently created objects, and calls which pass
keyword arguments through to outside functions (e.g. in TW.Callbacks).

For situations where the old syntactic sugar is desired, there is now an
'Items()' API call which converts an optional mapping and keyword
arguments into an itmes list for you.  See the docs for the TW.API.Misc
module for details.

Changed 'NamedDescriptors' to 'ActiveDescriptors', making them a bit more
flexible, adding a bit of interface documentation, and adding support for
classes to keep a set of '__volatile_attrs__' for filtering '__getstate__'
data to avoid persisting cached/computed attributes, without needing
everything to use '_v_' names.

Further refinements to Once/OnceClass.  Moved TransactionalCache to
Database.Transactions module, and added TransactionNotifier, now shared
by TransactionManager and TransactionalCache.  Refactoring in DataModel
and TransactionManager to take advantage of Once attributes.  I still need
to get Records to do version checking, and I think that queueForUpdate()
and friends probably needs refactoring to use Once as well.  Proper use of
'bindTo()' in DataModel should also make version checking easy, by watching
'TransactionManager.writeCounter'.  The invalidation machinery needs to be
checked over a bit, too.

Refinements and docs for Once and OnceClass.  Changed OnceClass to "copy"
itself by returning an instance of 'Once' that wraps itself, instead of
creating a subclass, since that's much cleaner.

Refactored to separate the notions of Once and OnceClass from the notion
of a NamedDescriptor.  Now TW.API includes a Once() descriptor that wraps
a function for computing a cached attribute value, and a OnceClass
metaclass for creating classes that do the same.