GettingStartedWithPeak

UserPreferences

The following is taken from http://www.eby-sarna.com/pipermail/peak/2003-November/000929.html. Note that the slightest of changes were made to conform to a Q/A format.

Q: I am a fairly experienced python programmer, however the PEAK package seems fairly daunting to understand.

A: 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.

Q: I have read and understand the concepts in the tutorial. Can somebody point me in some direction to start grokking PEAK in it's entirety?

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

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.)