The PEAK Developers' Center   Diff for "IntroToPeak" UserPreferences
 
HelpContents Search Diffs Info Edit Subscribe XML Print View
Ignore changes in the amount of whitespace

Differences between version dated 2003-12-10 19:58:18 and 2005-07-27 14:27:18 (spanning 7 versions)

Deletions are marked like this.
Additions are marked like this.

#pragma section-numbers off
 
 
= An Extended Introduction to PEAK =
 
 
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?
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
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".
 
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
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
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.
 
 
'''Lesson Prerequisites'''
 
 
= Lesson Prerequisites =
 
The examples in the lessons below have been tested
against the latest CVS version of PEAK 0.5 alpha 3.
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
 
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
`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.
 
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
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,
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
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
`INSTALL.txt` file, and make note of its path. You will need to change
`#!` lines that look like: {{{
#!/usr/bin/env peak runIni
}}} to read: {{{
#!/usr/local/bin/invoke peak runIni
}}} instead. (Substituting the correct path to `invoke`, of course.)
 
}}} instead. (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
via `#!invoke` in order to get all of the arguments you need. For
more on this, see [http://peak.telecommunity.com/doc/INSTALL.txt.html PEAK's INSTALL.txt],
under "Scripts, Batch Files, and `#!`".
 
'''The Lessons'''
 
 
= The Lessons =
 
 * /LessonOne - Commands and Configuration
 * /LessonTwo - Domain Models and Data Retrieval
 * /LessonThree - Subcommands and Storing Data
 * /LessonFour - SQL, N2, and peak.naming
 * /LessonFive - Using Logs
 * /ToDo - Not a lesson, just thoughts on future topics, open issues, etc.
 
 * /["Changes"] - Also not a lesson; a record of changes made to the tutorial
 
= Exploring the rest of PEAK =
 
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 [http://peak.telecommunity.com/doc 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.: {{{
 
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 [http://peak.telecommunity.com/doc 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
 | 'Obtain(componentKey,[default=value])' - finds/caches a needed component
 |
 | Usage examples::
 | Usage examples::
 |
 | class someClass(binding.Component):
 | class someClass(binding.Component):
 |
 | thingINeed = binding.Obtain("path/to/service")
 | otherThing = binding.Obtain(IOtherThing)
 | aProperty = binding.Obtain(PropertyName('some.prop'), default=42)
 | 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)'.
 | '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.
 | 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!

PythonPowered
ShowText of this page
EditText of this page
FindPage by browsing, title search , text search or an index
Or try one of these actions: AttachFile, DeletePage, LikePages, LocalSiteMap, SpellCheck