[Subversion] / PEAK / docs / core_tutorial / binding.tex |
No default branch
Bookmark a link to HEAD:
(view)
(download)
(as text)
MAJOR API REFACTORING for 'peak.config', to support iterating over configuration keys, 'n2' navigability of properties, and much more. Many APIs are now DEPRECATED or renamed; please see CHANGES.txt for a complete description. A few highlights: - 'config.lookup()' replaces 'findUtility' and 'getProperty' - 'config.iterValues()' replaces 'findUtilities' - 'config.iterKeys()' finds keys in a specific namespace - NEW: 'config.parentProviding()' and 'config.parentsProviding()' APIs to find parent components that support a protocol. - NEW: You can now use 'peak n2 config:' to explore the default property namespace. For example 'ls -l peak.naming.schemes' will list all defined naming schemes. Please see CHANGES.txt for the list of deprecated or removed APIs.
Semi-futile attempt to fix up the tutorial for the new binding API. We're probably going to have to scrap the tutorial altogether soon, it's aging far too rapidly relative to the capabilities of the codebase. :(
Update misc. notes re: deprecated binding APIs.
Doc fixes: name -> attrName.
Fixup interfaces/docs to reflect 'offerAs' API changes.
Fixed spelling error.
Tweak tutorial error message to match current reality.
Updated tutorial to cite PyProtocols manual, and added info about Twisted interfaces. Cleaned up "see alsos" related to interfaces, and added a link to a Twisted "howto" document on interfaces and adapters.
Misc. content corrections in preparation for alpha 2 release.
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.
Farewell, 'zope.interface'. You served us well.
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.
Tutorial edits to sync w/current API.
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.
Fixed typos/other errors found by Radek Kanovsky and Vladimir Bormotov. I guess there's something to this whole "many eyes make shallow bugs" theory after all... :)
Fixed errors in example code.
Fixed %&)(#&%$ tabs and other errors in copying transcripts from IDLE.
Added a couple pages to tutorial chapter two, covering various ways to hook into the binding framework without using the supplied base classes, to define alternative behavior for getComponentName()/getParentComponent(), etc.
Update docs and error messages for the departure of 'ActiveDescriptor' base and 'ActiveDescriptors' metaclass.
Remove references to deprecated or moved classes
Minor edits/fixes to tutorial.
Started new tutorial section on working with component hierarchies; misc. other edits.
Misc. typo fixes
Fleshed out "Creating Attribute Bindings" section, added more outline text.
Fleshed out "Getting Started With PEAK" with more API and package details. Also, misc. formatting and cosmetic cleanups.
Moved "Getting Started with PEAK" from Chapter 2 to Chapter 1
Fleshed out package overviews. This entire section (Getting Started with PEAK) should probably be moved to chapter 1, as it's sort of interrupting the flow of chapter 2.
Fix typo; add more outlining for work to be done
Misc. phrasing edits; additonal outlining
Added tutorial sections for binding.Once and on how bindings really work.
Fixed misc. awkward turns of phrase. Fixed formatting of double-quoted phrases. Added document formatting convention subsection. Changed car make names to 'aCar' and 'anotherCar' to avoid needing to include trademark disclaimer. :)
Some proofing, editing, and commenting out of stuff to run drafts faster, but mainly added 2 new pages of (very) rough draft material on the basics of attribute bindings. My main worry about this new material is that it goes into way too much detail about some things, at least for people who just want to get in and do stuff. When I try to be less detailed, I end up worrying about the people like me who insist on knowing exactly how things work. Sigh. I think I'll just have to get outside opinions on it. Anyway, once again, this is new and unproofed material.
Added another 2.5 (printed) pages of material, on composing applications, the Service-Element-Feature pattern, and an introduction to the PEAK package layout and API conventions. Standardized on combining \citetitle and \url to cite online references, since in printed form you can't click on hyperlinks, and they don't seem to be working in .PDF versions either. This set of additions still needs more proofreading, but I'd just as soon check things in after every few pages for safety's sake.
Added subsection on component interface concepts, and citations for the Zope Interface package's documentation and the Zope 3 Component Architecture tutorial. Went back and marked the first appearance of important terms with \strong{}. This makes things clearer to the reader, and it should also help tracking down index terms later! I should probably add a document conventions section to the intro chapter, but that's really the only convention that exists so far, so I'll wait until there's more to say about the subject.
Started a basic concepts introduction for the "binding" chapter of the tutorial.
cvs-admin@eby-sarna.com Powered by ViewCVS 1.0-dev |
ViewCVS and CVS Help |