[PEAK] Where to start?

[Phillip J. Eby]

At 01:39 AM 11/27/03 -0600, rand at speakeasy.net wrote:
>I am a fairly experienced python programmer, however the
>PEAK package seems fairly daunting to understand.

PEAK is a little easier to grasp if you realize that it's actually two things:

1. A "framework for frameworks", known as the PEAK core framework
2. A collection of task-area frameworks built on the core

So, to use PEAK, you need to be able to understand the core concepts, and 
then you can make use any of the non-core frameworks.

For example, 'peak.running.commands' is a mini-framework focused on 
"command line" applications that have a stdin, stdout, argv, and so 
on.  It's based on components and adaptation, which are facilities provided 
by the core framework.

Another example is 'peak.storage.SQL', a mini-framework for working with 
DBAPI drivers in a uniform way, with persistent connection management, and 
typemaps for converting column types to application datatypes.

The "secret" of the core framework is that it enables extreme modularity 
and reusability, by encouraging a programming style that exposes 
collaboration dependencies and eliminates singletons.

In a typical Python class library, classes reference other classes and 
modules as part of code.  A method of a class might create an instance of 
another class, or refer to a module-level variable.  (The same thing, 
really.)  These references are impossible to customize without changing 
source code, or massive subclassing and overriding of the methods 
involved.  Further, if an option is controlled by a module-level variable, 
the module can't be shared by components that need *different* settings for 
that variable.

In other words, the typical Python class library is *not* a 
"component".  It is not configurable and composable with other components 
because it is a single instance, and its connection points are hidden, 
rather than exposed.

peak.binding, however, makes it ridiculously easy to isolate and expose any 
dependency as an object attribute, that can then be overridden in a variety 
of ways ranging from simple setattr() to constructor keywords to 
configuration declarations.  And, it introduces the idea of components 
having *context* from which they can obtain configuration variables, rather 
than using globals.  Thus, each instance of a component class obtains its 
configuration and connects to collaborator components via its unique context.

Since the typical Python library is not usable as a component, PEAK's 
non-core frameworks do their best to wrap existing Python facilities up as 
useful components, or offer alternative implementations when there's no way 
to componentize existing frameworks or tools, or existing tools don't meet 
PEAK requirements.


>   I have
>read and understand the concepts in the scant tutorial.

Good, because those are the most important basics.  Component hierarchy and 
bindings are key to nearly every other package in PEAK.


>   Can
>somebody point me in some direction to start grokking PEAK
>in it's entirety.  Any help would be appreciated.

The key packages to understand are (in this order):

* protocols - since everything in PEAK uses adaptation for various 
purposes.  (You don't need to understand it thoroughly, just be familiar 
with adapt(), advise(), Interface, and Attribute, as these are the things 
you'll encounter most in PEAK code.)

* peak.binding - because nearly everything in PEAK is a component, and uses 
bindings to connect with other components

* peak.config - because components find each other, and their configuration 
properties, using the configuration system, and you will sometimes want to 
build applications using PEAK's "executable configuration files".

* peak.naming - because many kinds of components (SQL connections, classes, 
loggers, sockets, etc.) are accessed via URL naming or addressing schemes, 
making them extremely useful for configuration.

It isn't necessary to understand how to extend the frameworks provided by 
these packages, just have a basic understanding of the concepts and API 
provided by each one.  The two best things to look at are the 
'interfaces.py' in each 'peak.*' package, and the docstrings for API 
classes and functions.  (API classes and functions are listed by name in 
the '__all__' list at the top of each module in a package.)