README for PLIB Version 0.1
Author: Peter A. Donis
Release Date: 25 January 2008

The PLIB Package
================

The PLIB package provides a top-level namespace for a
number of useful sub-packages and modules, in order to
minimize clutter in the top-level namespace of your
Python installation. Each sub-directory of the plib
directory contains a sub-package, except for the
'test' directory, which contains the PLIB test suite.
The source distribution also contains an examples
directory, which contains example programs using PLIB,
and a scripts directory, which contains a few post-install
scripts.

Installation
------------

To install PLIB, you can simply run

$ python setup.py install

at a shell prompt from the directory into which you
unzipped the source tarball (the same directory that this
README file is in). However, since there are some
post-install scripts that should be run to fully set up
PLIB, a shell script is also provided; just run

$ install-all

at a shell prompt in the source directory. After running
the setup.py installation scripts, this shell script
runs each of the post-install scripts in the scripts
directory.

The Zen of PLIB
===============

There is no single unifying purpose or theme to PLIB, but
like Python itself, it does have a 'Zen' of sorts:

- Express everything possible in terms of built-in Python
  data structures.

- Once you've expressed it that way, what the code is
  going to do with it should be obvious.

- Avoid boilerplate code, *and* boilerplate data. Every
  piece of data your program needs should have one and
  only one source.

The PLIB Sub-Packages
=====================

The individual sub-packages and modules contain docstrings
with more information about their usage; here they are
briefly listed and described.

PLIB.CLASSES
------------

Each of the modules in this sub-package contains a single
class with the same name; the ModuleProxy class (which is
one of the modules) is used to make all the classes appear
in the PLIB.CLASSES namespace. See the sub-package and
ModuleProxy docstrings for more information.

The classes in this sub-package are a miscellaneous group,
included for no other reason than that I have found them
useful.

PLIB.EXTENSIONS
---------------

This sub-package provides a namespace for functions (and
possibly, in the future, other objects) exported from an
extension module written using the Python/C API. The general
philosophy of PLIB is to do everything possible in pure
Python, so the only functions that appear in this sub-package
are those which by their very nature cannot be done in pure
Python.

PLIB.GUI
--------

This is the largest sub-package, and contains a simple GUI
application framework with two main features:

- It makes the same high-level code work with a number of
  different underlying GUI toolkits. Currently supported:
  Qt, KDE, wxWidgets, and GTK. (The original reason for
  writing this sub-package was that wxWidgets doesn't use
  Qt and I like the Qt/KDE widgets better, but I wanted
  code that would run cross-platform.)

- It allows you to express the layout of your GUI almost
  entirely in terms of Python lists and dicts. (See the
  first item in PLIB's Zen above.)

Other than selecting the toolkit (which may not be necessary:
the main module of the sub-package can 'auto-detect' which
toolkit to use, so you only need to override if you don't
like its default), you should not have to worry about any
toolkit internal details; the goal of this sub-package is to
make them all look the same to your code.

Note that the GTK toolkit support in this sub-package is
"experimental" and may be removed if it proves to be more
trouble than it's worth. It's currently included because
wxWidgets' behavior when using GTK as its underlying GUI
framework has some quirks that I haven't been able to work
around yet. However, the GTK implementation of a number of
widgets (particularly tables and list/tree views) is much
less capable than wxWidgets', so the Python code for GTK
ends up relying much more on ugly hacks.

PLIB.INI
--------

This sub-package implements an abstract 'INI file' API that
uses ConfigParser on POSIX systems, and the Windows registry
on Windows systems. As with the PLIB.GUI sub-package, the
goal is to hide the internal details of the configuration
storage from your code, so all you have to do is define
your configuration structure.

PLIB.STDLIB
-----------

This is a namespace for various functions and classes that
extend or emulate the Python standard library. Some,
like the cached_property decorator, are implementations of
patterns that have been known for some time, but which don't
have a "canonical" version in the stdlib yet; rather than
have PLIB depend on some other third-party package, I've
simply provided my own implementations here. Others, like
the abstractcontainer class and its subclasses, are
re-implementations of standard Python data structures,
written to enable PLIB to make as many things as possible
look like those data structures, in accordance with Zen #1
above, without having to subclass the built-ins (which has
some downsides for the use cases I've had thus far--see
the docstrings for more information).

PLIB.UTILS
----------

This sub-packages contains a few miscellaneous useful
functions, and also the OPTIONS module, which provides an
easier-to-use overlay for the optparse module in the Python
standard library. Once again, the point is to allow you
to express your option configuration in the form of Python
lists, tuples, and dicts. It also adds some minimal
argument checking functionality.

PLIB.XML
--------

This sub-package requires the LXML extension, which uses
the very fast libxml2 library but provides a Pythonic API
similar to ElementTree. The reason for using LXML instead
of ElementTree itself is that LXML has two key additional
features:

- Custom element classes: the CLASSES module in this
  sub-package builds on this feature by using metaclasses
  to automate DTD generation and validation, but the
  feature is also great for many XML applications.

- Full and *fast* XPATH support: this was key in the XML
  application that first prompted me to write this sub-package.
  Yes, I know there are plenty of other Python XML packages
  that do XPATH; the point is to have it *plus* the standard
  ElementTree API *plus* the speed of libxml2.

Example Programs
================

PLIB comes with example programs that illustrate key features
of the package. See $PREFIX/share/plib/examples.

Copyright and License
=====================

PLIB is Copyright (C) 2008 by Peter A. Donis. It is released
under the GNU General Public License (GPL), Version 2 (but at
your option, you may release your own modifications to PLIB
under any later GPL version). See the LICENSE file for a copy
of the license.
