libbe/command/help.py

   1 # Copyright (C) 2005-2012 Aaron Bentley <abentley@panoramicfeedback.com>
   2 #                         Chris Ball <cjb@laptop.org>
   3 #                         Gianluca Montecchi <gian@grys.it>
   4 #                         Marien Zwart <marien.zwart@gmail.com>
   5 #                         Thomas Gerigk <tgerigk@gmx.de>
   6 #                         W. Trevor King <wking@tremily.us>
   7 #
   8 # This file is part of Bugs Everywhere.
   9 #
  10 # Bugs Everywhere is free software: you can redistribute it and/or modify it
  11 # under the terms of the GNU General Public License as published by the Free
  12 # Software Foundation, either version 2 of the License, or (at your option) any
  13 # later version.
  14 #
  15 # Bugs Everywhere is distributed in the hope that it will be useful, but
  16 # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  17 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  18 # more details.
  19 #
  20 # You should have received a copy of the GNU General Public License along with
  21 # Bugs Everywhere.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 import libbe
  24 import libbe.command
  25 import libbe.command.util
  26
  27
  28 TOPICS = {
  29     'repo': """A BE repository containing child bugdirs
  30
  31 BE repositories are stored in an abstract `Storage` instance, which
  32 may or may not be versioned.  If you're using BE to track bugs in your
  33 local software, you'll probably be using an on-disk storage based on
  34 the VCS you use to version the storage.  See `be help init` for
  35 details about automatic VCS-detection.
  36
  37 While most users will be using local storage, BE also supports remote
  38 storage servers.  This allows projects to publish their local
  39 repository in a way that's directly accessible to remote users.  The
  40 remote users can then use a local BE client to interact with the
  41 remote repository, without having to create a local copy of the
  42 repository.  The remote server will be running something like:
  43
  44     $ be serve-storage --host 123.123.123.123 --port 54321
  45
  46 And the local client can run:
  47
  48     $ be --repo http://123.123.123.123:54321 list
  49
  50 or whichever command they like.
  51
  52 Because the storage server serves repositories at the `Storage` level,
  53 it can be inefficient.  For example, `be list` will have to transfer
  54 the data for all the bugs in a repository over the wire.  The storage
  55 server can also be harder to lock down, because users with write
  56 access can potentially store data that cannot be parsed by BE.  For a
  57 more efficient server, see `be serve-commands`.
  58 """,
  59 ##
  60     'server': """A server for remote BE command execution
  61
  62 The usual way for a user to interact with a BE bug tracker for a
  63 particular project is to clone the project repository.  They can then
  64 use their local BE client to browse the repository and make changes,
  65 before pushing their changes back upstream.  For the average user
  66 seeking to file a bug or comment, this can be too much work.  One way
  67 to simplify the process is to use a storage server (see `be help
  68 repo`), but this is not always ideal.  A more robust approach is to
  69 use a command server.
  70
  71 The remote server will be running something like:
  72
  73     $ be serve-commands --host 123.123.123.123 --port 54321
  74
  75 And the local client can run:
  76
  77     $ be --server http://123.123.123.123:54321 list
  78
  79 or whichever command they like.  The command line arguments are parsed
  80 locally, and then POSTed to the command server, where the command is
  81 executed.  The output of the command is returned to the client for
  82 display.  This requires much less traffic over the wire than running
  83 the same command via a storage server.
  84 """,
  85         }
  86
  87
  88 class Help (libbe.command.Command):
  89     """Print help for given command or topic
  90
  91     >>> import sys
  92     >>> import libbe.bugdir
  93     >>> io = libbe.command.StringInputOutput()
  94     >>> io.stdout = sys.stdout
  95     >>> ui = libbe.command.UserInterface(io=io)
  96     >>> cmd = Help()
  97
  98     >>> ret = ui.run(cmd, args=['help'])
  99     usage: be help [options] [TOPIC]
 100     <BLANKLINE>
 101     Options:
 102       -h, --help  Print a help message.
 103     <BLANKLINE>
 104       --complete  Print a list of possible completions.
 105     <BLANKLINE>
 106     <BLANKLINE>
 107     Print help for specified command/topic or list of all commands.
 108     """
 109     name = 'help'
 110
 111     def __init__(self, *args, **kwargs):
 112         libbe.command.Command.__init__(self, *args, **kwargs)
 113         self.args.extend([
 114                 libbe.command.Argument(
 115                     name='topic', metavar='TOPIC', default=None,
 116                     optional=True,
 117                     completion_callback=self.complete_topic)
 118                 ])
 119
 120     def _run(self, **params):
 121         if params['topic'] == None:
 122             if hasattr(self.ui, 'help'):
 123                 print >> self.stdout, self.ui.help().rstrip('\n')
 124         elif params['topic'] in libbe.command.commands(command_names=True):
 125             module = libbe.command.get_command(params['topic'])
 126             Class = libbe.command.get_command_class(module,params['topic'])
 127             c = Class(ui=self.ui)
 128             self.ui.setup_command(c)
 129             print >> self.stdout, c.help().rstrip('\n')
 130         elif params['topic'] in TOPICS:
 131             print >> self.stdout, TOPICS[params['topic']].rstrip('\n')
 132         else:
 133             raise libbe.command.UserError(
 134                 '"%s" is neither a command nor topic' % params['topic'])
 135         return 0
 136
 137     def _long_help(self):
 138         return """
 139 Print help for specified command/topic or list of all commands.
 140 """
 141
 142     def complete_topic(self, command, argument, fragment=None):
 143         commands = libbe.command.util.complete_command()
 144         topics = sorted(TOPICS.keys())
 145         return commands + topics