View of /PEAK/docs/core_tutorial/intro.tex

Parent Directory

Revision Log

Misc. content corrections in preparation for alpha 2 release.

\chapter{Introduction: Component-Based Development for Enterprise Applications}

\section{What is PEAK?}

PEAK is the ``Python Enterprise Application Kit". If you develop
``enterprise" applications with Python, or indeed almost any sort of
application with Python, PEAK may help you do it faster, easier, on a
larger scale, and with fewer defects than ever before. The key is
component-based development, on a reliable infrastructure.

PEAK is based on several years of hard-won experience developing and
managing mission-critical Python enterprise applications. Its authors
have had to use and administer for some time, virtually all of the
technologies present in PEAK. Although nearly all of PEAK is being
written ``from scratch", it was created to replace existing tools that
we've enjoyed -- or struggled with -- over the years.

Our apps require 24x7 availability for thousands of employees worldwide.
So anything we build has to be ``stone-axe reliable." We want debugging
to be a simple and painless process, so we've designed PEAK to make
applications ``easy to reason about". We use techniques like ``lazy
immutability" to prevent unintended side-effects, and ``complain early
and often" to ensure that broken code announces itself as broken
\emph{before} it causes bugs or data corruption to creep in.  We've learned
our reliability lessons from several previous generations of (mostly
unpublished) application and component frameworks, and applied them to
this new, best-of-breed framework.














\subsection{What PEAK is for: Enterprise Applications}

Enterprise applications are complex, reflecting the complexity of the
environments they exist in and support. The ``enterprise" is often a
large corporation with many subsidiaries, each of which may have been
acquired as a previously-independent company with its own product lines
and business processes. With each acquisition, an enterprise inherits
new ``legacy" systems, which must be integrated or phased out. Databases
and applications are legion, system administration is vital. There are
multiple developers, some inside the company, some outside, some from
different divisions. Repetition is everywhere, but also variation. For
example: the New York database is on the same back-end as the one in
London, but the data model is slightly different, and the time zones on
stored dates are different. One thing doesn't vary, however: the users
want new functionality, and they want it yesterday.

In such an environment, non-functional requirements -- the ``ilities" of
development -- reign supreme. Reusability, configurability, flexibility,
extensibility, reliability, portability: these are the stuff
``enterprise" applications must be made of. The authors of PEAK have
built their professional reputations not only on their applications'
reliabilty, but on their speed of development as well. So PEAK
incorporates their best ideas for making application components highly
reusable, extensible, and configurable, ``right out of the box".

















\subsection{What PEAK is part of: Python Enterprise}

The value proposition of J2EE is that you can have industry standards,
whose implementations are supplied by competing vendors, to address
the ``ilities" across a variety of concerns, such as data storage,
component assembly, messaging systems, and so on.  But J2EE encompasses
over a dozen technologies of varying complexity and immense APIs.  Java
is also not a compact language, nor is it especially suited to rapid
development.  Last, but not least, the sheer scope of J2EE ensures that
implementations are resource-hungry, and complex to install, manage, and
maintain, especially for the smaller enterprise, or small department
within a larger enterprise.  If you wish to do more with less, J2EE is
probably not for you.

Python, on the other hand, is an easy-to-use language that ``fits your
brain", and comes with ``batteries included".  Often an idea that takes
half a dozen classes and several hundred lines of convoluted code to
express in Java, can be expressed in two classes and less than a hundred
lines of crystal-clear Python.  Indeed, Python is so expressive that it
can take far less time for one to write an alternative implementation of
a J2EE technology in Python, than it takes to understand that technology
in the first place!  Many J2EE technology concepts were actually
developed independently in Python applications and libraries, long
before they appeared in Java.  But, compared to Java's marketing
juggernaut, Python tools for the enterprise have had relatively little
market exposure.

And so, there is an increasing movement in the Python world to develop
and/or promote serious alternatives to J2EE technologies for use with
Python, so that developers can leverage Python's lower total cost of
ownership in application development and maintenance. The authors of
PEAK see PEAK as part of this larger ``Python Enterprise" movement, along
with the Zope 3 application server, and other Python APIs and
technologies. Zope 3 can be seen as an alternative to Java servlets,
JSP, and EJB containers for ``session beans" and ``message-driven beans".
PEAK supplies tools for creating the equivalents of ``managed beans" and
``entity beans", and for implementing parallels to other J2EE technologies
such as JNDI and JMS.  It is designed to integrate well with the Zope 3
object publishing architecture, and with other Python Enterprise
technologies. (A detailed comparison of all the technologies in the J2EE
and Python Enterprise worlds is outside the scope of this tutorial, but
may be addressed later in a separate white paper.)


\subsection{What PEAK is made of: Application Kit}

So what are these PEAK technologies? PEAK is an application kit, and
applications are made from components.  PEAK provides you with a
component architecture, component infrastructure, and various
general-purpose components and component frameworks for building
applications. As with J2EE, the idea is to let you stop reinventing
architectural and infrastructure wheels, so you can put more time into
your actual application.

The most basic part of PEAK is the component binding package: a set of
tools for constructing components out of other components, and ``binding"
separate components together. Then, PEAK supplies a component naming
package that provides a common API for associating names with
components, looking them up by name, and handling ``addresses" of objects
like database connections, mail servers, log or lockfiles, and other
infrastructure components. Third, PEAK supplies a component
configuration package, which makes it easy to provide utilities and
configuration data that ``trickle down" through the components of an
application.

PEAK also supplies, or will supply, several other packages dealing with
application domain components, storage, transactions,
internationalization, and system operations such as task scheduling,
logging, and so on. But all of these other packages depend on the three
core packages of binding, naming, and configuration, which are the
subject of this tutorial.  Understanding how to use these core packages
is essential for building PEAK applications.

Luckily, PEAK is compact. At the time we started writing this, the binding,
naming, and config packages consisted of only about 4,000 lines of Python
(including docstrings, comments, and whitespace, but not counting unit
test modules or shared utility modules). So it won't take you long to
master their use, with the help of this tutorial.

\newpage


\section{Using this Document}

\citetitle{Building Component-Based Applications with PEAK} introduces
the basic techniques for using the PEAK binding, naming, and config
packages to build flexible, reusable, and configurable applications from
components. To get the best results from this tutorial, you should:

\begin{itemize}

\item Have a solid grasp of the Python language, version 2.2 (we
recommend checking out \citetitle{What's New in Python 2.2} at
\url{http://www.amk.ca/python/2.2/} if you are familiar with earlier
versions, but not 2.2).

\item Have Python 2.2.2 or greater installed on your computer, along
with PEAK, so that you can try out the sample code and exercises in this
tutorial.

\end{itemize}

\subsection{Formatting Conventions}

This document uses the following formatting conventions:

\begin{itemize}

\item Code samples and the names of actual classes, functions, will be in a
\code{fixed pitch font}.

\item Text intended to be typed at a Python interpreter prompt is prefixed
with the interpreter prompt, \samp{>>>}.

\item When a new, important term is first introduced, it will be marked
in \strong{boldface text}.

\end{itemize}




\newpage
\section{Getting Started with PEAK}

\subsection{Package Layout and API Conventions}

PEAK is installed as a set of Python packages, such as \module{peak.binding},
\module{peak.naming}, and so on, within the top-level \module{peak} package
space.  To help distinguish between the ``public" and ``private" portions of
the code, each subpackage includes an \samp{api} module that exports its API
classes, functions, constants, and interfaces.

The top-level package also includes an API subpackage, \module{peak.api}, which
contains each of the other subpackages' API modules, named for the subpackage.
In other words, \samp{from peak.api import binding} produces essentially the
same result as \samp{import peak.binding.api as binding}.

For convenience, you can also use \samp{from peak.api import *} to import all
the API subpackages.  Then, you can access any \module{peak.binding} API class
such as \class{Once} by simply referring to \class{binding.Once}.  In this
tutorial and all PEAK documentation and code examples, we'll refer to APIs
following this convention: major subpackage followed by a dot and the class
or function name.

In general, it's most useful to use \samp{from peak.api import *} to access
the PEAK API.  Not only does this give you immediate access to all the
subpackage API modules, this will also import several other useful variables,
like the special \samp{NOT_FOUND} and \samp{NOT_GIVEN} objects, and various
logging functions like \function{LOG_CRITICAL} and \function{LOG_DEBUG}.

Experienced Python programmers may wonder whether using this approach
will cause all of PEAK to be imported.  In fact, it won't, because the
\module{peak.api} subpackage uses a ``lazy import" mechanism.  Individual API
subpackages like \module{peak.binding} won't actually be loaded until one of
their attributes are accessed.  This prevents wasteful up-front loading of all
the modules and classes.  See the source for \module{peak.api.__init__} and
the \class{lazyModule} function in \module{peak.binding.imports}, if you'd like
to know more about how it works.





\subsubsection{Interfaces and Exceptions}

In addition to an \samp{api} module, each major subpackage also contains an
\samp{interfaces} module, which defines all of the interfaces used or provided
by classes in that package.  The \samp{interfaces} modules contain almost no
executable code: they are there to document the interfaces only.  This makes
them a good place to start learning about PEAK packages, especially ones that
are frameworks, like \module{peak.naming} or \module{peak.storage}.

Another useful module to know about is \module{peak.exceptions}, which defines
the exception classes used by PEAK's major subpackages.  You probably won't use
it often, though, since there aren't many PEAK exceptions that you'll want to
explicitly catch.  Most PEAK exception types indicate issues with your code or
design, not runtime problems.

\subsubsection{NOT_GIVEN and NOT_FOUND}

Some PEAK API's use the special objects \samp{NOT_GIVEN} and \samp{NOT_FOUND}
to represent special kinds of ``null" values.  \samp{NOT_FOUND} is often
used as a return value that signifies a desired item was ``not found" in a
cache, registry, or other mapping.  This is often done in preference to
raising a \exception{KeyError} for both performance and semantic clarity.  A
\exception{KeyError} could have been caused by some failure internal to an
object, while returning \samp{NOT_FOUND} indicates the method was successfully
executed, but the item was simply not found.

\samp{NOT_GIVEN} is rarely used as a return value; its primary purpose is to be
a default value for argument(s) to a function or method.  It's used in place of
\samp{None} as a default value, when the argument could legitimately have a
value of \samp{None} or even \samp{NOT_FOUND}.  A function can tell whether a
value was supplied, by whether the argument is the \samp{NOT_GIVEN} object.
You'll probably never need to supply this value to a PEAK API call, or
return it from a method, but you may find it useful in defining your own APIs.

Note that you should only compare \samp{NOT_GIVEN} and \samp{NOT_FOUND} using
the Python \samp{is} operator, e.g. \samp{if someParam is NOT_GIVEN:
doSomething()}.

\newpage


\subsubsection{PEAK's Major Subpackages}

\begin{description}

\item[api] \hfill \\
The \module{peak.api} package supplies commonly used classes, functions,
modules, and constants needed by PEAK applications and the PEAK framework
itself.

\item[binding] \hfill \\
The \module{peak.binding} package defines base classes for application
components, and for the attribute bindings used to connect components
together.  These base classes are used throughout PEAK to implement all
sorts of components.

\item[config] \hfill \\
The \module{peak.config} package provides a framework for ``placeful" and
``lazily immutable" lookups of configuration data.  Configuration data can be
arbitrary objects or values, and can be looked up by either a property name,
or by an interface that the desired object supports (similar to the Zope 3
concept of \strong{utilities}).

\item[model] \hfill \\
The \module{peak.model} package provides a framework for creating persistent,
application domain class families.  It provides abstractions such as
"Structural Features" that can define fields and associations based on
metadata, and automatically generate methods for those features based on code
templates.  The resulting persistent objects can be saved or loaded by
subclassing \class{DataManager} classes from the \module{peak.storage} package.

\item[naming] \hfill \\
The \module{peak.naming} package provides services comparable to those of
Java's JNDI system, only easier to use and extend.  Naming services are
a standardized interface for looking up or recording the location of objects,
whether they're database connections, printers, web services, or even
something as simple as log files.

\item[running] \hfill \\
The \module{peak.running} package provides runtime environment tools for
logging, locking, process control, event loops, command line apps, periodic
tasks, CGI/FastCGI web publishing, etc.

\item[storage] \hfill \\
The \module{peak.storage} package provides APIs and components for handling
transactions, database connections, and persistence.

\end{description}

\subsubsection{PEAK's Minor Subpackages and Modules}

\begin{description}

\item[exceptions] \hfill \\
The \module{peak.exceptions} module contains the definitions of all exception
classes used by PEAK's major subpackages.  It doesn't include exceptions from
minor subpackages such as \module{peak.util}.

\item[metamodels] \hfill \\
The \module{peak.metamodels} package contains metamodels; that is to say,
class families representing metadata for object models.  For example,
\module{peak.metamodels.UML13} contains classes implementing the UML 1.3
specification, \module{peak.metamodels.MOF131} implements the MOF 1.3.1
specification, and so on.  The packages here are mainly useful for creating
tools that work with XMI files from CASE tools, or creating CASE tools of your
own.  It usually isn't needed for applications that aren't themselves CASE
tools.

\item[tests] \hfill \\
The \module{peak.tests} package controls the execution of PEAK's unit tests.
In addition, many major and minor subpackages contain subpackages named
\module{tests}, which contain the unit tests for that section of PEAK.  The
\function{test_suite} function in each \module{tests} module returns a
\class{unittest.TestSuite} for its parent package.

\item[util] \hfill \\
The \module{peak.util} package is a collection of generally useful modules
that don't rely on anything else in PEAK, and thus could potentially be used
independently of PEAK.  Includes modules for dealing with Python bytecode,
XML handling, simple table-like data structures, UUID/GUID handling, and more.

\end{description}