HelloWorld

UserPreferences

By R. David Murray (rdmurray at bitdance.com) (w/edits by PJE)

Preface

There's a long tradition of teaching programmers how to use programming systems via "Hello, World!" examples. Why should PEAK be left out? I'm going to try to develop a series of stripped-to-the-essentials examples here that provide complete working PEAK programs that demonstrate some of the basic services provided by PEAK. Don't expect to find deep knowledge here; this article is intended to help you get over the first hump of using PEAK, while giving you a little bit of its "flavor".

We'll be using a Unixish command shell for our examples. The percent sign (%) will be used to indicate a command prompt.

(Note to Windows users: if you're not using a Unix-like shell (e.g. Cygwin/Bash), you'll need to change the command lines used here. For example, peak foo bar will become something like c:\Python22\Python.exe c:\Python22\peak foo bar. None of the #! lines will work for you, either, and to set environment variables like PYTHONPATH, you'll need to use SET instead of export, and so on. However, there's nothing Unix-specific about the framework or examples, and your applications will still run on Windows. It's just that the standard Windows shell doesn't offer as many conveniences in these areas. If you have trouble running the examples on Windows, write up your question on the PEAK mailing list, and we'll try to get these examples updated with more Windows-specific command lines.)

Table of Contents

1. Basic Configuration
1. Introduction
2. Running helloworld under PEAK
3. ".ini" Files and the "runIni" Command
4. Executable Configuration Files
5. Making the Application Object Configurable
6. Binding attributes to configuration
7. Points to Remember
2. Command Arguments and Simple Database Access
1. Command Arguments
2. Domain Models
3. Data Managers
1. Loading data from the flat file
2. Building the Data Manager subclass
4. Putting it all Together
5. Points to Remember
6. Exploring the rest of PEAK

1 Basic Configuration

1.1 Introduction

At base, a PEAK program is a Python program. PEAK is a toolkit and framework, which means it provides stuff you can use in your Python programs to get things done more easily and more quickly, and usually more elegantly.

So, the simplest PEAK "Hello, world!" program is also, in a trivial sense, the Python "Hello, world!" program:

    1     print "Hello, World!"

One of the things PEAK provides is a framework for giving application programs easy access to their associated configuration data. The goal of this first chapter will be to show how to turn the output of the simple "Hello, world!" program into a configured string. I'm going to get us there step by step, keeping the program in a runnable state at each step (except the first!)

1.2 Running helloworld under PEAK

Let's start by introducing the peak command. For convenience in starting PEAK applications, the peak.running package provides a peak command-line script, that is installed alongside Python when you install PEAK. We'll use the peak script to invoke our application. First, just type:

peak 

 
Usage: peak NAME_OR_URL arguments... 
 
The 'peak' script bootstraps and runs a specified command object or command 
class.  The NAME_OR_URL argument may be a shortcut name defined in the 
'peak.running.shortcuts' property namespace, or a URL of a type 
supported by 'peak.naming'.  For example, if you have a class 'MyAppClass' 
defined in 'MyPackage', you can use: 
 
    peak import:MyPackage.MyAppClass 
 
to invoke it.  Arguments to the found object are shifted left one position, 
so in the example above it will see 'import:MyPackage.MyAppClass' as its 
'argv[0]'. 
 
The named object must implement one of the 'peak.running' command interfaces, 
or be callable.  See the 'Bootstrap' class in 'peak.running.commands' for 
more details on creating command objects for use with 'peak'.  For the 
list of available shortcut names, see '/usr/lib/python/site-packages/peak/peak.ini'. 
 

(The last line will list the actual path to peak.ini on your system.)

Okay, that looks helpful, although the stuff about command interfaces and shortcuts is perhaps a little intimidating. For now, we'll stick to the easy part, where it said we could use a callable! Let's make a helloworld module, with a HelloWorld function, in helloworld.py:

    1     def HelloWorld():
    2         print "Hello, world!"

Can we run it with the peak script now? Let's try it:

 
% peak import:helloworld.HelloWorld 
Traceback (most recent call last): 
  File "C:\Python22\Scripts\peak", line 7, in ? 
    sys.exit( 
  File "C:\cygwin\home\pje\PEAK\src\peak\running\commands.py", line 303, in __call__ 
    return cmd.interpret(cmd.argv[1]) 
  File "C:\cygwin\home\pje\PEAK\src\peak\running\commands.py", line 624, in interpret 
    raise InvocationError("Name not found: %s" % name) 
peak.running.commands.InvocationError: Name not found: import:helloworld:HelloWorld 
 

Oops. What's wrong? Oh, wait, since helloworld is a module, not a script, it needs to be on the PYTHONPATH. Let's fix that:

 
% export PYTHONPATH=. 
% peak import:helloworld.HelloWorld 
Hello, world! 
 

Nice! But we said we were going to make the message configurable. To do that, we're going to use the peak runIni command.

1.3 ".ini" Files and the "runIni" Command

runIni is one of the built-in "shortcut" commands that were alluded to in the peak script's usage message. It takes the argument following runIni, and loads it as a configuration file. Take a moment now to type peak runIni, and look at the usage message:

 
Usage: peak runIni CONFIG_FILE arguments... 
 
CONFIG_FILE should be a file in the format used by 'peak.ini'.  (Note that 
it does not have to be named with an '.ini' extension.)  The file should 
define a 'running.IExecutable' for the value of its 'peak.running.app' 
property.  The specified 'IExecutable' will then be run with the remaining 
command-line arguments. 
 

Okay, there's that business about executable command interfaces again, but we won't let that put us off because we know we can get away with using a function for now.

So, now we know we need an .ini-format file, with a peak.running.app property. But it doesn't have to actually be named with .ini, so let's just call our configuration file helloworld:

 
[peak.running] 
app = importString("helloworld.HelloWorld") 
 

(Note to experienced Pythonistas: PEAK does not use the Python ConfigParser module to parse .ini files, so don't assume that you can use ConfigParser syntax or semantics here. To meet PEAK's configuration requirements, both the syntax and semantics needed to be different from those supplied by ConfigParser.)

How did we know to format the file this way? Well, we looked at the peak.ini file, of course, and learned by example. Here we've defined a configuration rule for the property named peak.running.app. The rule says (in effect), "when someone asks for the peak.running.app property, call the PEAK importString function on the string "helloworld.HelloWorld", and return the value.

The importString() function acts like a Python import statement, such that importString("x.y.z") is equivalent to from x.y import z. Thus, the importString() line of the config file shown above is roughly equivalent to:

 
    from helloworld import HelloWorld as app 
 

The reason we say "roughly" is that PEAK configuration files aren't executed the way Python code is. Properties in the configuration file are not Python assignment statements: they're rules that supply a Python expression whose value is computed only when the property is looked up. When the configuration file is loaded, the expressions are read, but not executed. Indeed, if the property is never looked up, the expression is never evaluated at all.

This can be a big advantage over using a Python script for configuration, since you can create a shared .ini file that describes properties used by several applications. Even if some of those properties might involve a time-consuming operation such as opening a database connection, only the applications that actually use the property will pay the cost of computing it.

Indeed, this allows you to use a single site-wide configuration file to provide configuration for all of your PEAK-based applications, using the PEAK_CONFIG environment variable to point to the file. Of course, the applications can't use property names that conflict with other applications' property names. But, there are many configuration properties used by PEAK that you may wish to share across multiple applications, such as logging rules, naming services, and command shortcuts, to name just a few. Property definitions supplied by application-specific configuration files will of course override any definitions in the site-wide configuration defaults.

Anyway, we now have a configuration file for our application, trivial as it is so far. Let's try it out:

 
% peak runIni helloworld 
Hello, world! 
 

Looks like it still works.

By the way, just as a side note, if an application object like our HelloWorld function returns a value, that value has significance. If the value is an integer (or None), it will be used as the return code from the peak script, and of our command line as a whole. If it is not an integer, it will be echoed to the terminal, and 1 will be used as the return code from the peak script. If you want, try this out now by adding various return statements to your helloworld.py and checking the exit code from the peak script in your shell.

1.4 Executable Configuration Files

The configuration file for a complex application is often central to that application. Under Unix-like command shells, PEAK allows configuration files to be the "executable" file of the application, the file whose name is entered at the console to invoke the program. This is done using the "magic cookie" of the unix shell:

 
#!/usr/bin/env peak runIni 
 
[peak.running] 
app = importString('helloworld:HellowWorld') 
 

Python still needs imported modules to be on the PYTHONPATH, though, so you have to call this helloworld file like this:

 
% PYTHONPATH=. ./helloworld 
 

In a real application, you could of course install your modules in a directory on the system PYTHONPATH (such as in the Python site-packages directory), thus enabling your command to simply be called by name, without setting any pesky environment variables.

If you can't arrange for the package to be on the system PYTHONPATH, or you don't want it to be there, you have a couple of different options. For example, you might change the "magic cookie" line to read:

#!/usr/bin/env PYTHONPATH=/where/my/modules/are peak runIni 

But this doesn't work on operating systems that treat the entire #! line as a single command argument. For those operating systems, you might write a short shell script instead. In this case you might call the config file helloworld.ini, since the shell script will be called helloworld. If helloworld.ini and helloworld.py are in the same directory as the helloworld script, the script might look like this:

 
#!/bin/sh 
here=`dirname $0` 
PYTHONPATH=$here peak runIni $here/helloworld.ini 
 

We're going to assume from here on out that you've got your system configured to run the helloworld example when you type ./helloworld. You can do that by making helloworld an executable in one of the ways we've described, or you can just cheat and type peak runIni helloworld everywhere we say to type ./helloworld.

1.5 Making the Application Object Configurable

Okay, enough messing around with application deployment issues, and on to configuration. Let's move the "Hello world" message into the configuration file.

The configration file follows .ini format, which means you have "sections" in square brackets followed by lines that set values for various names within the section. PEAK doesn't place many restrictions on what sections or property names can appear in an .ini file, so we can pretty much choose whatever section name and property names we want, as long as they're valid Python identifiers.

We'll be very unoriginal and call our configuration section helloworld. (It's generally a good idea to have an application's properties grouped under names that begin with the application name, so they won't conflict with those of other applications.) The text of our message will be placed in the message configuration property:

 
#!/usr/bin/env peak runIni 
 
[peak.running] 
app = importString('helloworld:HellowWorld') 
 
[helloworld] 
message = "Hello, world!" 
 

To use the configuration information we need to obtain it via the PEAK configuration framework. At this point we are actually starting to use PEAK facilities directly in our Python code, so we'll need to import them from the PEAK package. PEAK provides a simple way to access the vast majority of the PEAK facilities through its api module:

 
from peak.api import * 
 

In addition, we can no longer use a simple, dumb function object as our application. In order to access the configuration information, the application object must participate in the appropriate PEAK frameworks.

In this case, the framework for a simple command line command such as our helloworld is provided by the AbstractCommand class of the peak.running.commands module (lazily imported for us by peak.api):

 
class HelloWorld(commands.AbstractCommand): 
 

In the case of AbstractCommand, there is only one method we need to override: the _run method, which will do the actual work of our application (and optionally return an exit code, just like our function could). So, without getting into the configurability yet, our complete helloworld.py file would now look like this:

    1 from peak.api import *
    2 
    3 class HelloWorld(commands.AbstractCommand):
    4 
    5     def _run(self):
    6         print "Hello, world!"

1.6 Binding attributes to configuration

Specifically, we will use the Obtain class from the peak.binding package. Obtain, coupled with the PropertyName class, allows us to pull values out of the configuration file:

 
    message = binding.Obtain(PropertyName('helloworld.message')) 
 

Note that this code does not mean, "set message to the configuration property helloworld.message. Instead it means, "when the message attribute of an instance of this class is accessed, obtain the helloworld.message property, and use that as the attribute's value from then on." (See? We told you lazy loading was a recurring theme in PEAK!)

Notice that this means bindings like Obtain are Python "descriptors", similar to the Python built-in type property. So, in order for a binding to be used, it must be placed in a class, and then used from an instance of the class.

Obtain can find things using mechanisms other than PropertyName, but PropertyName is the one we are interested in here. PropertyName is a string subclass, and its constructor takes as its argument the fully qualified property name. By "fully qualified", I mean the name of the section the property is found in, followed by a dot, followed by the rest of the property name. So the message property from our helloworld section becomes the PropertyName helloworld.message.

The PropertyName class ensures that its instances are of valid syntax for use in a configuration file, but that's not the only reason we need to use it. If we gave Obtain an ordinary string, it would not look it up in our configuration file. Instead, it would try to use the string as a URL or a component path -- two ideas we don't need or want to get into right now.

Anyway, when we access our HelloWorld object's message attribute in the _run() method, the binding.Obtain descriptor will look up the configuration property for us. It does this by searching the context in which the instance is located. The peak.running.commands framework will provide us with with such a context automatically, when it creates an instance of our HelloWorld class. (We won't deal with the specifics of this mechanism here; suffice to say that some code we inherit from AbstractCommand will take care of the details for us.)

Let's look at the revised program:

    1 from peak.api import *
    2 
    3 class HelloWorld(commands.AbstractCommand):
    4 
    5     message = binding.Obtain(PropertyName('helloworld.message'))
    6 
    7     def _run(self):
    8         print self.message

 
% ./helloworld 
Hello, world! 
 

 
#!/usr/bin/env peak runIni 
 
[peak.running] 
app = importString('helloworld.HelloWorld') 
 
[helloworld] 
message = "Hello, new world!" 
 

 
% ./hellonewworld 
 

 
Hello, new world! 
 

1.7 Points to Remember

Before we move on to the next chapter, let's recap the concepts we've covered so far:

• Running applications
• The peak script can be used to execute applications, by telling it to import either a function, or a subclass of commands.AbstractCommand (among many other possibilities we're not covering here).
• A commands.AbstractCommand subclass must define a _run() method to do the actual work of the command.
• The return value of an executed function (or _run() method) will become the exit code for the entire program, when it is run by the peak script.
• Configuration files
• PEAK's configuration framework supports .ini-style configuration files, using property names as section headings, and Python expressions for supplied values. (Note: PEAK also supports other configuration formats, but the .ini format is most useful for configuration done by developers. Other formats (such as ZConfig) may be more suitable for end-users.)
• The PEAK_CONFIG environment variable can name a configuration file that will be used to supply configuration defaults, before application-specific configuration is loaded.
• Properties are defined in .ini files with Python expressions that are "lazily evaluated" when the property is looked up. Simply loading the file does not execute the expressions.
• The peak runIni command can "execute" a configuration file, by looking for its peak.running.app property. The property can be any "executable" just as could be run directly by the peak script.
• With Unix-like shells, a configuration file can be made executable, by using peak runIni as part of the file's #! "magic cookie" line.
• An application executed via peak runIni will be supplied a "configuration context" or "parent component", that offers access to the properties defined by the configuration file.
• Attribute bindings and configuration keys
• binding.Obtain is an attribute descriptor that can be used to automatically set attributes to values found in a configuration context.
• PropertyName is a string subclass that can be used with binding.Obtain to look up configuration properties. A PropertyName must be syntactically valid, such that it can be used in an .ini-style configuration file.

2 Command Arguments and Simple Database Access

Now its time to go a tiny step beyond the triviality of the "Hello, world!" example. In this chapter I'll expand the example to handle saying hello to an arbitrary variety of things. Since we want to be flexible. we'll get the greeting message for each thing from a database table. Well, really just a flat file, but that's so we don't get distracted with SQL connections and all that just yet.

In a "real" application, we'd be using SQL or some other robust storage as our "back end". But here we want to focus on the issues of creating an "object-relational mapping", without getting bogged down in the relational part. Unfortunately, this makes the tutorial a bit lopsided, because we'll be building a sophisticated object-relational mapping over data that would've been trivial to use in its original form!

So, try to ignore that part, and focus on the ideas, which scale up to vastly larger applications than what we're showing here.

2.1 Command Arguments

To greet more than one thing, we'll need to be able to tell our command what to greet. Let's rename our command to hello, and give what we want to say hello to as the command argument, e.g.:

 
% hello world 
% hello fred 
% hello Klause 
 

If all we want to do is say hello in the same boring way every time, we could revise our helloworld.py file as follows:

    1 from peak.api import *
    2 
    3 class HelloWorld(commands.AbstractCommand):
    4 
    5     message = binding.Obtain(PropertyName('helloworld.message'))
    6 
    7     def _run(self):
    8         print self.message % self.argv[1]

 
#!/usr/bin/env peak runIni 
 
[peak.running] 
app = importString('helloworld.HelloWorld') 
 
[helloworld] 
message = "Hello, %s.  How are you today?" 
 

 
% export PYTHONPATH=. 
% ./hello world 
Hello, world.  How are you today? 
% ./hello fred 
Hello, fred.  How are you today? 
% ./hello, Klause 
Hello, Klause.  How are you today? 
 

2.2 Domain Models

When working with application data, PEAK uses the concept of a "domain model" for that data. A "domain model" describes the kinds of "problem domain" (i.e. "real-world") objects you're working with, and their relationships to other kinds of objects. In PEAK-speak, the objects are called "Elements", and the relationships are called "Features". Features are implemented as object attributes, using custom descriptors.

To facilitate grabbing data from our database, we'll define a simple Element class, in a hello_model.py file:

    1 from peak.api import *
    2 
    3 class Message(model.Element):
    4 
    5     class forname(model.Attribute):
    6         referencedType = model.String
    7 
    8     class text(model.Attribute):
    9         referencedType = model.String

You probably noticed immediatly that we are defining classes inside classes here. The nested classes actually create attribute descriptors, similar to the Python built-in property type. However, instead of having to define functions and then wrap them into property object, we can simply subclass a predefined "Feature" type such as model.Attribute, and provide parameters such as referencedType, or define methods to control the feature's behavior.

(Note, by the way, that referencedType does not necessarily refer to the class of the objects or values that will be stored in the attribute. It can also reference an object like model.String, that simply provides metadata describing what values are acceptable for the attribute. For more extensive examples of using Model types, see the bulletins example in the examples directory of the PEAK CVS tree.)

2.3 Data Managers

The domain model by itself is simply a schema, perhaps with some behavior. (For example, we might add a hello() method to our Message class, so that an instance of Message could actually deliver its message directly.)

But, a domain model by itself doesn't know anything about storage. (This is so that we can reuse the domain model with different kinds of storages.) To store and retrieve instances of our domain model classes, we need a Data Manager. Data Managers are responsible for loading and storing the data described by the domain model classes.

For the present example we're only interested in loading data from a "database table". So we'll subclass QueryDM, a peak.storage class that provides a read-only interface to a datastore:

 
from peak.api import * 
 
class MessageDM(storage.QueryDM): 
 

To keep our example simple, we'll use a flat file as our external data store. In keeping with PEAK design principles, we won't hardcode the filename into our Data Manager, but will instead make it configurable:

 
    filename = binding.Obtain(PropertyName('helloworld.messagefile')) 
 

 
[helloworld] 
messagefile = config.fileNearModule('helloworld', 'hello.list') 
 

Since we're only using a QueryDM in this example, we only have to worry about reading data from the datastore, not writing it (That's a later example). To specify how to do this, we override the _load method of QueryDM. Our _load method needs to return a dictionary of names and values, which will get used through a __setstate__ call to load the data into our Message instances.

2.3.1 Loading data from the flat file

Now we need to whip up a data format for our messagefile. Let's have the thing we are saying hello to be first, and the actual message second, separated by a "|" character.

So we'll create a hello.list file like this:

 
world  | Hello, world! 
Fred   | Greetings, good sir. 
Klause | Guten Aben, Herr Klause. 
 

Because this is going to be a read-only file, we're going to cheat and load the file only once, the first time it's used. We'll use another peak.binding tool to accomplish this:

    1     def data(self):
    2         data = {}
    3         file = open(self.filename)
    4         for line in file:
    5             fields = [field.strip() for field in line.split('|',1)]
    6             forname, text = fields
    7             data[forname] = {'forname': forname, 'text': text}
    8         file.close()
    9         return data
   10 
   11     data = binding.Make(data)

binding.Make is similar to binding.Obtain, in that it's used inside a class body to create a property-like descriptor for the class' instances. It's different, in that it takes a function as its argument, rather than a configuration key. The function should take at least one parameter (self), and return the value to be used for an attribute. In this way, it's very similar to the property built-in, but with a key difference: a property's fget function is called every time it is used, but the result of a binding.Make function is cached and reused for subsequent accesses of the attribute.

So, here's what will happen. The first time an instance of our QueryDM subclass accesses its data attribute, the function above will be called, and the result stored in the instance's data attribute. It will then be immediately available for use, and won't be computed again for that instance unless the attribute is deleted.

(Of course, in the case of our current hello program, we'll only ever make one query on the database. If we were going to make a longer-running program, or allow the database to be modified, using this sort of caching might be a bad idea. However, this design decision affects only our data manager's implementation, and not the rest of the application. Our main, command-line application will not be affected, and neither will our Message class, if we decide to change how or where the messages are stored.)

2.3.2 Building the Data Manager subclass

Here's the complete contents of the last new file we need for our expanded hello application, the hello_storage.py file. This also adds the _load method to the QueryDM:

    1 from peak.api import *
    2 from hello_model import Message
    3 
    4 class MessageDM(storage.QueryDM):
    5 
    6     defaultClass = Message
    7     filename = binding.Obtain(PropertyName('helloworld.messagefile'))
    8 
    9     def data(self):
   10         data = {}
   11         file = open(self.filename)
   12         for line in file:
   13             fields = [field.strip() for field in line.split('|',1)]
   14             forname, text = fields
   15             data[forname] = {'forname': forname, 'text': text}
   16         file.close()
   17         return data
   18 
   19     data = binding.Make(data)
   20 
   21     def _load(self, oid, ob):
   22         return self.data[oid]

A data manager is like a container for application objects. It's keyed by the notion of an oid: an "object ID" for objects of this kind. So, when we use a MessageDM instance, we'll retrieve objects from it like this:

 
        aMessage = myMessageDM[someName] 
 

When we do this, the MessageDM will return what's called a "ghost". It will be an instance of Message that contains no data, but knows its object ID, and knows that it's not yet loaded. As soon as we try to use the Message (by accessing any attributes or methods), it will "phone home" to the data manager it was retrieved from, asking for its data to be loaded.

At this point, the MessageDM._load() method is going to get called. It'll be given the object ID that was used to access the object originally (the oid parameter), and the applicable "ghost" object (ob). The data that _load() returns will be used to fill in the ghost's instance dictionary so that it will become a "real" object, and the attribute access that triggered the _load call can finally be satisfied.

(Notice, by the way, that if we were using a relational database, the _load method is probably where we'd put an SQL query to retrieve the data for the given object ID.)

2.4 Putting it all Together

All that remains, then, is to use our new data manager from our main application program:

    1 from peak.api import *
    2 from hello_model import Message
    3 
    4 class HelloWorld(commands.AbstractCommand):
    5 
    6     Messages = binding.Make(
    7         'hello_storage.MessageDM',
    8         offerAs=[storage.DMFor(Message)]
    9     )
   10 
   11     def _run(self):
   12         storage.beginTransaction(self)
   13         print self.Messages[self.argv[1]].text
   14         storage.commitTransaction(self)

In our revised HelloWorld class, we see another use of binding.Make, this time taking an import string that specifies a class that should be instantiated. Previously, we used binding.Make with a function, but it also accepts classes, or strings that say where to import classes or functions from. (Indeed, it takes anything that implements or adapts to the binding.IRecipe interface, but that's more than you need to know right now.)

When used with a class (or an import string that names a class), binding.Make will call it once, the first time the named attribute is used. In this case, that means that it will automatically create a new MessageDM as the Messages attribute of the HelloWorld instance it's contained in. So, in effect, we are declaring that each HelloWorld instance should have its own MessagesDM instance, stored in its Messages attribute.

Here we also use an additional keyword argument (offerAs) to binding.Make. offerAs is a list of "configuration keys" under which the created component will be "offered" to child components (via the configuration system). In this case, we're saying that any child components of a HelloWorld instance should use its Messages attribute, if they are looking for a data manager that provides storage services for Message instances.

The PEAK configuration system offers many kinds of "configuration keys" under which components or configuration properties can be found. We've previously worked with PropertyName, which is one kind of configuration key. And here we work with another, storage.DMFor(), that creates a configuration key denoting a data manager for a particular element type. PEAK does not limit you to using its predefined kinds of configuration keys, however. You can also create your own key types for specialized purposes, by implementing the config.IConfigKey interface.

Once you "offer" an attribute as the source of a configuration key, it can then be referenced by other uses of binding.Obtain by child components. For example, if we had another class that needed to use a data manager for Message instances, we could add something like this to that class:

 
    Messages = binding.Obtain(storage.DMFor(Message)) 
 

This would use the configuration system to find an appropriate data manager. And, if an instance of this other class were contained within an instance of HelloWorld, it would use the HelloWorld object's Messages attribute to fill its own Messages attribute. (Note that the similarity in names has nothing to do with how it works; we could have called one of the attributes "foobar" and it would make no difference.)

The big advantage of this is that it allows us to create "loosely coupled" reusable components. A component that needs some service can simply Obtain it via a suitable key, and a higher-level application component can "offer" an appropriate service implementation. What's more, even binding.Obtain can use the offerAs argument, thereby specifying that an obtained component will be available to the containing component's children, perhaps under another configuration key as well as the key that was used to obtain the service.

Anyway, once we've got the data manager to be used for Message instances, we can look up any Message instance in it by using the instance's object id (in this case, its forname) as a key. In our case, that key is the string passed in as an argument to our command (self.argv[1], supplied to us by the peak script). As previously discussed, this gives us a Message instance, which we can then display by printing its text attribute.

Our last addition to HelloWorld is the use of beginTransaction and commitTransaction to enclose our data manipulation in a transaction. For our simple read-only application here, a transaction is of relatively little importance, but transaction management will matter a great deal when you use read/write databases.

Anyway, our program now works like this:

 
% export PYTHONPATH=. 
% ./hello world 
Hello, world! 
% ./hello Fred 
Greetings, good sir. 
% ./hello Klause 
Guten Aben, Herr Klause. 
 

2.5 Points to Remember

Let's recap some of the key topics we've covered in this chapter:

• Bindings
• Bindings are attribute descriptors, like property, but execute only once per instance unless the attribute is deleted.
• binding.Obtain obtains a configuration value or component by searching parent components for "offered" values.
• binding.Make invokes a function or class constructor (possibly after importing them) to create an attribute value.
• Bindings can have an offerAs keyword, that "offers" the attribute under one or more "configuration keys", that then can be looked up by child components using Obtain.
• Domain Model
• Elements are persistent "problem domain" objects
• Features are attributes representing a relationship between elements and other elements or values. They're defined using classes nested within the element class, and they specify (among other things) the type of related element or value to be used.
• Data Managers
• A data manager is a "virtual container" for elements, that retrieves and stores their data for them
• Data managers initially return "ghost" elements, then populate them with data when actually used. (So that retrieving one element doesn't cause all related elements to be retrieved at once.)
• By defining the _load method in a data manager subclass, you can implement whatever data retrieval is needed to populate an element
• Data managers should be used within the scope of a transaction
• Commands
• An AbstractCommand receives its arguments in self.argv, a list similar to sys.argv

Whew! That's a lot of things, but we're still only scratching the surface. Each of the major topic areas listed above could be expanded into entire tutorials of their own. But, for now, you may want to simply experiment a bit with what you've seen so far, before delving deeper into the PEAK API documentation and source code.

2.6 Exploring the rest of PEAK

One important topic we haven't covered here is the "component hierarchy", although we've alluded to it on occasion by talking about "parent" and "child" components. Generally speaking, a component contained within another component is a "child" component of the container, and PEAK provides mechanisms for components to access their containers to "obtain" configuration or other components. It's also possible to treat the component hierarchy like a kind of file system, using paths to navigate from one component to another.

As you begin to build more sophisticated applications, you'll probably want to have more understanding of how components are attached to their parent components, and how they can receive notification that they've been attached. And, if you want to create applications that run without using the peak script, you'll also want to know about "root components" and how to create them with config.makeRoot.

In the meantime, to get you started on your journey, you may wish to explore the current API documentation. There, you'll find a list of some of the major features provided by other PEAK frameworks, and quick-reference documentation for them. Also, if you want to look up an API feature like PropertyName or binding.Obtain, you can use the peak help command, e.g.:

% peak help binding.Obtain 
 
Help on class Obtain in module peak.binding.components: 
 
class Obtain(peak.binding.once.Attribute) 
 |  'Obtain(componentKey,[default=value])' - finds/caches a needed component 
 | 
 |  Usage examples:: 
 | 
 |      class someClass(binding.Component): 
 | 
 |          thingINeed = binding.Obtain("path/to/service") 
 |          otherThing = binding.Obtain(IOtherThing) 
 |          aProperty  = binding.Obtain(PropertyName('some.prop'), default=42) 
 | 
 |  'someClass' instances can then refer to their attributes, such as 
 |  'self.thingINeed', instead of repeatedly calling 
 |  'self.lookupComponent(someKey)'. 
 | 
 |  The initial argument to the 'Obtain' constructor must be adaptable to 
 |  'binding.IComponentKey'.  If a 'default' keyword argument is supplied, 
 |  it will be used as the default in case the specified component key is not 
 |  found. 
 | 
 ... etc. 

So have fun with PEAK, and I'll see you at the top!