LaunchpadLib Toolkit (lpltk)
============================
lpltk is a set of classes for interacting with the Launchpad
service API library.  It takes care of certain common chores such as
obtaining and managing login credentials.

By factoring this common code out of individual launchpadlib projects,
it makes them more concise and more compatible with one another.


Basic Usage
===========
For most purposes, simply create the LaunchpadService object, which will
attend to the credentials automatically.  Then retrieve a project object
(such as "ubuntu") and from there you can use all the regular Launchpad
API calls.  In other words:

  import lpltk

  lp   = lpltk.LaunchpadService()
  prj  = lp.load_project("ubuntu")


See example-ls-series.py for a complete working example.  Also try
running it with LPLTK_DEBUG turned on to see how to get debug info:

  $ ./example-ls-series.py

  $ LPLTK_DEBUG=1 ./example-ls-series.py

For more elaborate real-world scripts, refer to the Arsenal project at:

  http://launchpad.net/arsenal


Environment Variables
=====================
Configuration of the LaunchpadService behavior can be done via
environmental variables.  This is done principly to make it easy to
debug issues without needing to tweak source code.

The following environment variables are supported:

  LPLTK_DEBUG   Prints extra debugging messages to stderr if defined.
                If set to a numerical argument, it sets the httpdlib2
                debuglevel to that value; the http debug output will be
                filtered to redact your oauth token and signature, so
                you can attach debug info to public bugs without
                revealing anything sensitive.

  LPSTAGING     Use the staging service root rather than the live (edge)
                service.  This allows testing of your script without
                risking actual changes to the official Launchpad.

  LPCONFIG      Use this directory path for configuration files, rather
                than the default of ~/.config/<consumer>.  The directory
                will be created if it does not already exist.

  LPCACHE       Use this directory path for cache files (such as credentials),
                rather than the default of ~/.cache/<consumer>.  The
                directory will be created if it does not already exist.


API - LaunchpadService
======================

lp = LaunchpadService([config_path], [cache_path], [consumer])

     Creates the Launchpad service object and retrieve credentials from
     Launchpad.  LPSTAGING, LPCONFIG, and LPCACHE must be specified
     prior to instantiating the LaunchpadService object in order to have
     any effect.

     config_path and cache_path allow the calling script to define the
     default paths if not specified by the environment variables.

     On any unrecoverable error an exception is thrown.

lp.load_project(project)

     Loads the named project (such as "ubuntu" distro), returning its
     launchpadapi object.

lp.reset()

     Reloads the credentials and project (if any is specified).  This is
     handy for recovering from Launchpad out-of-service or other such
     transient errors.

lp.name:              The credentialed consumer name (default: lpltk)
lp.launchpad:         The launchpadlib launchpad object
lp.project:           The loaded Launchpad project (default: None)


API - Debug
===========
dbg(msg), err(msg), die(msg)

     Convenience routines for printing error and debug messages to
     stderr.  dbg() only prints if LPLTK_DEBUG is defined.

StdOut, DebugStdOut

     STDOUT overloads for debug output filtering.  Set sys.stdout to
     DebugStdOut to filter out oauth token and signature details.


Wishlist
========
* Unit tests
* API documentation
* Get this package into Main
* Add a framework for storing config elements beyond just credentials
* Integrate into existing launchpadlib scripts/applications
* Wrapper classes for Bugs, SourcePackages, etc.
* Strengthen the fault handling, provide better diagnostics, and be more
  robust against Launchpad service failures

