samples directory contains mystifying code

The example code in the samples/ directory is effectively undocumented, and not self-explanatory. Also, sample-person-api.py may contain a mis-assumption in its code.

Steps to reproduce:

I installed launchpadlib from a trunk branch today:

   $ bzr branch lp:launchpadlib
   $ cd launchpadlib
   $ sudo python setup.py install

Looking for example code, I entered the samples/ directory:

   $ cd samples/
   $ ls *.py
   commercial-member-api.py
   lpapi.py
   nopriv-api.py
   _pythonpath.py
   sample-person-api.py
   $

I opened up sample-person-api.py, but the __doc__ string at the top is just a transcript of a Python session, with no obvious connection to the script. I couldn't figure out what it was trying to say. So I tried running the script:

   $ ./sample-person-api.py
   Login as '<email address hidden>' in your browser.
   Press <Enter> when done.
   ### it waited for input here ###

Hmmm. It didn't say a password to use, but I tried logging into http://launchpad.net/ as "<email address hidden>", with both empty password and "test" for the password. Neither worked, of course. I asked around in IRC, and matsubara told me:

   <matsubara> kfogel: test@canonical doesn't exist on lp.net or
   staging.l.n. it's sample data for the development environment.

   <matsubara> kfogel: that sample will only work if you have the full
   LP source code available and the devel environment up and running.

I hit ^C...

  C-c C-cTraceback (most recent call last):
  File "./sample-person-api.py", line 83, in <module>
    raw_input()
  KeyboardInterrupt
  $

...and started looking at the other scripts. None were documented, though some had similar Python command interpreter transcripts at the top. Later I tried sample-person-api.py, but while logged in as myself in Launchpad.net, and the result was just to get a long traceback ending with "socket.error: (111, 'Connection refused')".

So:

1. Can the sample scripts be documented?

2. A user of launchpadlib is not necessarily likely to also be a developer of Launchpad itself, so nothing should depend on the '<email address hidden>' user being available. I think only sample-person-api.py has this problem -- the string "test@" occurs nowhere else in launchpadlib.