|
| IntroToPeak |
UserPreferences |
| The PEAK Developers' Center | FrontPage | RecentChanges | TitleIndex | WordIndex | SiteNavigation | HelpContents |
By R. David Murray (rdmurray at bitdance.com), with assistance from Phillip J. Eby (pje at telecommunity.com)
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; these lessons are intended to help you get over the first hump of using PEAK, while giving you a little bit of its "flavor".
The examples all revolve around a simple "Hello, World!" application concept. We'll start with a basic "Hello, World!" command-line application, then make it configurable, use various kinds of database access with transactions and logging, all the way up through a web UI and XML-RPC "web service", among other things. In the process, you'll be able to see how easy it is to create, re-use, and re-purpose component-driven applications with PEAK.
The examples in the lessons below have been tested against the latest CVS version of PEAK 0.5 alpha 3. The examples will not work with earlier versions of PEAK. (There could also be synchronization errors between the examples and my test code, so if you find something that doesn't work as advertised when run against current CVS, please let me know.)
We'll be using a Unixish command shell for our examples. The percent sign (%) will be used to indicate a command prompt.
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.
Note, however, that 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 the examples updated with more Windows-specific command lines.
Non-BSD Unix users: The #! lines in this tutorial are written for BSD-like Unixes that treat #! lines as having space-separated arguments. On other unixes, you will need to rewrite the #! lines to use the invoke program included with PEAK. Build and install the invoke program according to the instructions in PEAK's INSTALL.txt file, and make note of its path. You will need to change #! lines that look like:
#!/usr/bin/env peak runInito read:
#!/usr/local/bin/invoke peak runIniinstead. (Substituting the correct path to invoke, of course.)
invoke doesn't support setting the environment like env does, so you'll need to use something like:
`#!/usr/local/bin/invoke env WHATEVER=whatever peak whatever`if a #! line needs to set something in the environment.
Unfortunately, some operating systems have extremely limited lengths
for #! lines, and you may have to create a shell script and invoke it
via #!invoke in order to get all of the arguments you need. For
more on this, see ![[WWW]](/wiki/img/moin-www.gif){kind=small}
PEAK's INSTALL.txt,
under "Scripts, Batch Files, and #!".
One important topic we haven't covered in the lessons above 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.
(Also, this tutorial doesn't cover how to make your command objects support options like --help; for that, you can check out options.txt in the peak.running package, or have a look at the OptionsHowTo, which is the same thing but in HTML.)
So have fun with PEAK, and I'll see you at the top!
