NAME

       withlist - General framework for interacting with a Mailman mailing list object.

SYNOPSIS

       withlist [options] listname [args ...]

       There  are  two  ways  to  use  this  script: interactively or programmatically.  Using it
       interactively allows you to play with, examine and modify a MailList object from  Python's
       interactive interpreter.  When running interactively, a MailList object called `m' will be
       available in the global namespace.  It also loads  the  class  MailList  into  the  global
       namespace.

       Programmatically,  you  can  write  a  function  to operate on a MailList object, and this
       script will take care of the housekeeping (see below for examples).   In  that  case,  the
       general usage syntax is:

OPTIONS

       -l, --lock
              Lock  the  list when opening.  Normally the list is opened unlocked (e.g. for read-
              only operations).  You can always lock the file after the fact by typing `m.Lock()'

              Note that if you use this  option,  you  should  explicitly  call  m.Save()  before
              exiting,  since  the  interpreter's  clean up procedure will not automatically save
              changes to the MailList object (but it will unlock the list).

       -i, --interactive
              Leaves you at an interactive prompt after all other processing is  complete.   This
              is the default unless the -r option is given.

       -r [module.]callable, --run [module.]callable
              This  can  be  used to run a script with the opened MailList object.  This works by
              attempting to import module (which must already be accessible  on  your  sys.path),
              and then calling callable from the module.  callable can be a class or function; it
              is called with the MailList object as the first argument.  If additional  args  are
              given  on  the  command  line, they are passed as subsequent positional args to the
              callable.

              Note that module. is optional; if it  is  omitted  then  a  module  with  the  name
              callable will be imported.

              The global variable `r' will be set to the results of this call.

       -a, --all
              This  option  only  works  with the -r option.  Use this if you want to execute the
              script on all mailing lists.  When you use -a you should  not  include  a  listname
              argument on the command line.  The variable `r' will be a list of all the results.

       -q, --quiet
              Suppress all status messages.

       -h, --help
              Print a small help text and exit.

EXAMPLES

       Here's  an  example  of  how  to  use  the  -r option.  Say you have a file in the Mailman
       installation directory called `listaddr.py', with the following two functions:

         def listaddr(mlist):
             print mlist.GetListEmail()

         def requestaddr(mlist):
             print mlist.GetRequestEmail()

       Now, from the command line you can  print  the  list's  posting  address  by  running  the
       following from the command line:

         % bin/withlist -r listaddr mylist
         Loading list: mylist (unlocked)
         Importing listaddr ...
         Running listaddr.listaddr() ...
         mylist@example.com

       And you can print the list's request address by running:

         % bin/withlist -r listaddr.requestaddr mylist
         Loading list: mylist (unlocked)
         Importing listaddr ...
         Running listaddr.requestaddr() ...
         mylist-request@example.com

       As  another  example,  say  you  wanted  to change the password for a particular user on a
       particular list.  You could put the following function in a file called `changepw.py':

         from Mailman.Errors import NotAMemberError

         def changepw(mlist, addr, newpasswd):
             try:
                 mlist.setMemberPassword(addr, newpasswd)
                 mlist.Save()
             except NotAMemberError:
                 print 'No address matched:', addr

        and run this from the command line:
        % bin/withlist -l -r changepw mylist somebody@example.org foobar

AUTHOR

       Author of Mailman is the Mailman Cabal, see  http://www.list.org/  for  information.  This
       manpage  is  written  for Debian by Bernd S. Brentrup <bsb@debian.org>, but may be used by
       others.

SEE ALSO

       Mailman documentation on http://www.list.org/ and in /usr/share/doc/mailman.

                                            2007-07-14                                withlist(8)