1
# Copyright (C) 2006 Canonical Ltd
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18
# TODO: probably should say which arguments are candidates for glob
19
# expansion on windows and do that at the command level.
21
# TODO: Define arguments by objects, rather than just using names.
22
# Those objects can specify the expected type of the argument, which
23
# would help with validation and shell completion. They could also provide
24
# help/explanation for that argument in a structured way.
26
# TODO: Specific "examples" property on commands for consistent formatting.
28
# TODO: "--profile=cum", to change sort order. Is there any value in leaving
29
# the profile output behind so it can be interactively examined?
34
from bzrlib.lazy_import import lazy_import
35
lazy_import(globals(), """
38
from warnings import warn
51
from bzrlib import registry
53
from bzrlib.option import Option
59
def register_command(cmd, decorate=False):
60
"""Utility function to help register a command
62
:param cmd: Command subclass to register
63
:param decorate: If true, allow overriding an existing command
64
of the same name; the old command is returned by this function.
65
Otherwise it is an error to try to override an existing command.
69
if k.startswith("cmd_"):
70
k_unsquished = _unsquish_command_name(k)
73
if k_unsquished not in plugin_cmds:
74
plugin_cmds[k_unsquished] = cmd
75
## trace.mutter('registered plugin command %s', k_unsquished)
76
if decorate and k_unsquished in builtin_command_names():
77
return _builtin_commands()[k_unsquished]
79
result = plugin_cmds[k_unsquished]
80
plugin_cmds[k_unsquished] = cmd
83
trace.log_error('Two plugins defined the same command: %r' % k)
84
trace.log_error('Not loading the one in %r' % sys.modules[cmd.__module__])
85
trace.log_error('Previously this command was registered from %r' %
86
sys.modules[plugin_cmds[k_unsquished].__module__])
89
def _squish_command_name(cmd):
90
return 'cmd_' + cmd.replace('-', '_')
93
def _unsquish_command_name(cmd):
94
return cmd[4:].replace('_','-')
97
def _builtin_commands():
98
import bzrlib.builtins
100
builtins = bzrlib.builtins.__dict__
101
for name in builtins:
102
if name.startswith("cmd_"):
103
real_name = _unsquish_command_name(name)
104
r[real_name] = builtins[name]
108
def builtin_command_names():
109
"""Return list of builtin command names."""
110
return _builtin_commands().keys()
113
def plugin_command_names():
114
return plugin_cmds.keys()
117
def _get_cmd_dict(plugins_override=True):
118
"""Return name->class mapping for all commands."""
119
d = _builtin_commands()
121
d.update(plugin_cmds)
125
def get_all_cmds(plugins_override=True):
126
"""Return canonical name and class for all registered commands."""
127
for k, v in _get_cmd_dict(plugins_override=plugins_override).iteritems():
131
def get_cmd_object(cmd_name, plugins_override=True):
132
"""Return the canonical name and command class for a command.
135
If true, plugin commands can override builtins.
138
return _get_cmd_object(cmd_name, plugins_override)
140
raise errors.BzrCommandError('unknown command "%s"' % cmd_name)
143
def _get_cmd_object(cmd_name, plugins_override=True):
144
"""Worker for get_cmd_object which raises KeyError rather than BzrCommandError."""
145
from bzrlib.externalcommand import ExternalCommand
147
# We want only 'ascii' command names, but the user may have typed
148
# in a Unicode name. In that case, they should just get a
149
# 'command not found' error later.
150
# In the future, we may actually support Unicode command names.
152
# first look up this command under the specified name
153
cmds = _get_cmd_dict(plugins_override=plugins_override)
155
return cmds[cmd_name]()
159
# look for any command which claims this as an alias
160
for real_cmd_name, cmd_class in cmds.iteritems():
161
if cmd_name in cmd_class.aliases:
164
cmd_obj = ExternalCommand.find_command(cmd_name)
168
# look for plugins that provide this command but aren't installed
169
for provider in command_providers_registry:
171
plugin_metadata = provider.plugin_for_command(cmd_name)
172
except errors.NoPluginAvailable:
175
raise errors.CommandAvailableInPlugin(cmd_name,
176
plugin_metadata, provider)
181
class Command(object):
182
"""Base class for commands.
184
Commands are the heart of the command-line bzr interface.
186
The command object mostly handles the mapping of command-line
187
parameters into one or more bzrlib operations, and of the results
190
Commands normally don't have any state. All their arguments are
191
passed in to the run method. (Subclasses may take a different
192
policy if the behaviour of the instance needs to depend on e.g. a
193
shell plugin and not just its Python class.)
195
The docstring for an actual command should give a single-line
196
summary, then a complete description of the command. A grammar
197
description will be inserted.
200
Other accepted names for this command.
203
List of argument forms, marked with whether they are optional,
208
['to_location', 'from_branch?', 'file*']
210
'to_location' is required
211
'from_branch' is optional
212
'file' can be specified 0 or more times
215
List of options that may be given for this command. These can
216
be either strings, referring to globally-defined options,
217
or option objects. Retrieve through options().
220
If true, this command isn't advertised. This is typically
221
for commands intended for expert users.
224
Command objects will get a 'outf' attribute, which has been
225
setup to properly handle encoding of unicode strings.
226
encoding_type determines what will happen when characters cannot
228
strict - abort if we cannot decode
229
replace - put in a bogus character (typically '?')
230
exact - do not encode sys.stdout
232
NOTE: by default on Windows, sys.stdout is opened as a text
233
stream, therefore LF line-endings are converted to CRLF.
234
When a command uses encoding_type = 'exact', then
235
sys.stdout is forced to be a binary stream, and line-endings
242
encoding_type = 'strict'
247
"""Construct an instance of this command."""
248
if self.__doc__ == Command.__doc__:
249
warn("No help message set for %r" % self)
250
# List of standard options directly supported
251
self.supported_std_options = []
253
def _maybe_expand_globs(self, file_list):
254
"""Glob expand file_list if the platform does not do that itself.
256
:return: A possibly empty list of unicode paths.
258
Introduced in bzrlib 0.18.
262
if sys.platform == 'win32':
263
file_list = win32utils.glob_expand(file_list)
264
return list(file_list)
267
"""Return single-line grammar for this command.
269
Only describes arguments, not options.
271
s = 'bzr ' + self.name() + ' '
272
for aname in self.takes_args:
273
aname = aname.upper()
274
if aname[-1] in ['$', '+']:
275
aname = aname[:-1] + '...'
276
elif aname[-1] == '?':
277
aname = '[' + aname[:-1] + ']'
278
elif aname[-1] == '*':
279
aname = '[' + aname[:-1] + '...]'
281
s = s[:-1] # remove last space
284
def get_help_text(self, additional_see_also=None, plain=True,
285
see_also_as_links=False):
286
"""Return a text string with help for this command.
288
:param additional_see_also: Additional help topics to be
290
:param plain: if False, raw help (reStructuredText) is
291
returned instead of plain text.
292
:param see_also_as_links: if True, convert items in 'See also'
293
list to internal links (used by bzr_man rstx generator)
297
raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
299
# Extract the summary (purpose) and sections out from the text
300
purpose,sections = self._get_help_parts(doc)
302
# If a custom usage section was provided, use it
303
if sections.has_key('Usage'):
304
usage = sections.pop('Usage')
306
usage = self._usage()
308
# The header is the purpose and usage
310
result += ':Purpose: %s\n' % purpose
311
if usage.find('\n') >= 0:
312
result += ':Usage:\n%s\n' % usage
314
result += ':Usage: %s\n' % usage
318
options = option.get_optparser(self.options()).format_option_help()
319
if options.startswith('Options:'):
320
result += ':' + options
321
elif options.startswith('options:'):
322
# Python 2.4 version of optparse
323
result += ':Options:' + options[len('options:'):]
328
# Add the description, indenting it 2 spaces
329
# to match the indentation of the options
330
if sections.has_key(None):
331
text = sections.pop(None)
332
text = '\n '.join(text.splitlines())
333
result += ':%s:\n %s\n\n' % ('Description',text)
335
# Add the custom sections (e.g. Examples). Note that there's no need
336
# to indent these as they must be indented already in the source.
338
labels = sorted(sections.keys())
340
result += ':%s:\n%s\n\n' % (label,sections[label])
342
# Add the aliases, source (plug-in) and see also links, if any
344
result += ':Aliases: '
345
result += ', '.join(self.aliases) + '\n'
346
plugin_name = self.plugin_name()
347
if plugin_name is not None:
348
result += ':From: plugin "%s"\n' % plugin_name
349
see_also = self.get_see_also(additional_see_also)
351
if not plain and see_also_as_links:
353
for item in see_also:
355
# topics doesn't have an independent section
356
# so don't create a real link
357
see_also_links.append(item)
359
# Use a reST link for this entry
360
see_also_links.append("`%s`_" % (item,))
361
see_also = see_also_links
362
result += ':See also: '
363
result += ', '.join(see_also) + '\n'
365
# If this will be rendered as plain text, convert it
367
import bzrlib.help_topics
368
result = bzrlib.help_topics.help_as_plain_text(result)
372
def _get_help_parts(text):
373
"""Split help text into a summary and named sections.
375
:return: (summary,sections) where summary is the top line and
376
sections is a dictionary of the rest indexed by section name.
377
A section starts with a heading line of the form ":xxx:".
378
Indented text on following lines is the section value.
379
All text found outside a named section is assigned to the
380
default section which is given the key of None.
382
def save_section(sections, label, section):
384
if sections.has_key(label):
385
sections[label] += '\n' + section
387
sections[label] = section
389
lines = text.rstrip().splitlines()
390
summary = lines.pop(0)
392
label,section = None,''
394
if line.startswith(':') and line.endswith(':') and len(line) > 2:
395
save_section(sections, label, section)
396
label,section = line[1:-1],''
397
elif (label is not None) and len(line) > 1 and not line[0].isspace():
398
save_section(sections, label, section)
399
label,section = None,line
402
section += '\n' + line
405
save_section(sections, label, section)
406
return summary, sections
408
def get_help_topic(self):
409
"""Return the commands help topic - its name."""
412
def get_see_also(self, additional_terms=None):
413
"""Return a list of help topics that are related to this command.
415
The list is derived from the content of the _see_also attribute. Any
416
duplicates are removed and the result is in lexical order.
417
:param additional_terms: Additional help topics to cross-reference.
418
:return: A list of help topics.
420
see_also = set(getattr(self, '_see_also', []))
422
see_also.update(additional_terms)
423
return sorted(see_also)
426
"""Return dict of valid options for this command.
428
Maps from long option name to option object."""
429
r = Option.STD_OPTIONS.copy()
431
for o in self.takes_options:
432
if isinstance(o, basestring):
433
o = option.Option.OPTIONS[o]
435
if o.name in std_names:
436
self.supported_std_options.append(o.name)
439
def _setup_outf(self):
440
"""Return a file linked to stdout, which has proper encoding."""
441
# Originally I was using self.stdout, but that looks
442
# *way* too much like sys.stdout
443
if self.encoding_type == 'exact':
444
# force sys.stdout to be binary stream on win32
445
if sys.platform == 'win32':
446
fileno = getattr(sys.stdout, 'fileno', None)
449
msvcrt.setmode(fileno(), os.O_BINARY)
450
self.outf = sys.stdout
453
output_encoding = osutils.get_terminal_encoding()
455
self.outf = codecs.getwriter(output_encoding)(sys.stdout,
456
errors=self.encoding_type)
457
# For whatever reason codecs.getwriter() does not advertise its encoding
458
# it just returns the encoding of the wrapped file, which is completely
459
# bogus. So set the attribute, so we can find the correct encoding later.
460
self.outf.encoding = output_encoding
462
def run_argv_aliases(self, argv, alias_argv=None):
463
"""Parse the command line and run with extra aliases in alias_argv."""
465
warn("Passing None for [] is deprecated from bzrlib 0.10",
466
DeprecationWarning, stacklevel=2)
468
args, opts = parse_args(self, argv, alias_argv)
470
# Process the standard options
471
if 'help' in opts: # e.g. bzr add --help
472
sys.stdout.write(self.get_help_text())
474
trace.set_verbosity_level(option._verbosity_level)
475
if 'verbose' in self.supported_std_options:
476
opts['verbose'] = trace.is_verbose()
477
elif opts.has_key('verbose'):
479
if 'quiet' in self.supported_std_options:
480
opts['quiet'] = trace.is_quiet()
481
elif opts.has_key('quiet'):
484
# mix arguments and options into one dictionary
485
cmdargs = _match_argform(self.name(), self.takes_args, args)
487
for k, v in opts.items():
488
cmdopts[k.replace('-', '_')] = v
490
all_cmd_args = cmdargs.copy()
491
all_cmd_args.update(cmdopts)
495
return self.run(**all_cmd_args)
498
"""Actually run the command.
500
This is invoked with the options and arguments bound to
503
Return 0 or None if the command was successful, or a non-zero
504
shell error code if not. It's OK for this method to allow
505
an exception to raise up.
507
raise NotImplementedError('no implementation of command %r'
511
"""Return help message for this class."""
512
from inspect import getdoc
513
if self.__doc__ is Command.__doc__:
518
return _unsquish_command_name(self.__class__.__name__)
520
def plugin_name(self):
521
"""Get the name of the plugin that provides this command.
523
:return: The name of the plugin or None if the command is builtin.
525
mod_parts = self.__module__.split('.')
526
if len(mod_parts) >= 3 and mod_parts[1] == 'plugins':
532
def parse_args(command, argv, alias_argv=None):
533
"""Parse command line.
535
Arguments and options are parsed at this level before being passed
536
down to specific command handlers. This routine knows, from a
537
lookup table, something about the available options, what optargs
538
they take, and which commands will accept them.
540
# TODO: make it a method of the Command?
541
parser = option.get_optparser(command.options())
542
if alias_argv is not None:
543
args = alias_argv + argv
547
options, args = parser.parse_args(args)
548
opts = dict([(k, v) for k, v in options.__dict__.iteritems() if
549
v is not option.OptionParser.DEFAULT_VALUE])
553
def _match_argform(cmd, takes_args, args):
556
# step through args and takes_args, allowing appropriate 0-many matches
557
for ap in takes_args:
561
argdict[argname] = args.pop(0)
562
elif ap[-1] == '*': # all remaining arguments
564
argdict[argname + '_list'] = args[:]
567
argdict[argname + '_list'] = None
570
raise errors.BzrCommandError("command %r needs one or more %s"
571
% (cmd, argname.upper()))
573
argdict[argname + '_list'] = args[:]
575
elif ap[-1] == '$': # all but one
577
raise errors.BzrCommandError("command %r needs one or more %s"
578
% (cmd, argname.upper()))
579
argdict[argname + '_list'] = args[:-1]
585
raise errors.BzrCommandError("command %r requires argument %s"
586
% (cmd, argname.upper()))
588
argdict[argname] = args.pop(0)
591
raise errors.BzrCommandError("extra argument to command %s: %s"
596
def apply_coveraged(dirname, the_callable, *args, **kwargs):
597
# Cannot use "import trace", as that would import bzrlib.trace instead of
598
# the standard library's trace.
599
trace = __import__('trace')
601
tracer = trace.Trace(count=1, trace=0)
602
sys.settrace(tracer.globaltrace)
604
ret = the_callable(*args, **kwargs)
607
results = tracer.results()
608
results.write_results(show_missing=1, summary=False,
612
def apply_profiled(the_callable, *args, **kwargs):
616
pffileno, pfname = tempfile.mkstemp()
618
prof = hotshot.Profile(pfname)
620
ret = prof.runcall(the_callable, *args, **kwargs) or 0
623
stats = hotshot.stats.load(pfname)
625
stats.sort_stats('cum') # 'time'
626
## XXX: Might like to write to stderr or the trace file instead but
627
## print_stats seems hardcoded to stdout
628
stats.print_stats(20)
635
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
636
from bzrlib.lsprof import profile
637
ret, stats = profile(the_callable, *args, **kwargs)
643
trace.note('Profile data written to "%s".', filename)
647
def shlex_split_unicode(unsplit):
649
return [u.decode('utf-8') for u in shlex.split(unsplit.encode('utf-8'))]
652
def get_alias(cmd, config=None):
653
"""Return an expanded alias, or None if no alias exists.
656
Command to be checked for an alias.
658
Used to specify an alternative config to use,
659
which is especially useful for testing.
660
If it is unspecified, the global config will be used.
664
config = bzrlib.config.GlobalConfig()
665
alias = config.get_alias(cmd)
667
return shlex_split_unicode(alias)
672
"""Execute a command.
675
The command-line arguments, without the program name from argv[0]
676
These should already be decoded. All library/test code calling
677
run_bzr should be passing valid strings (don't need decoding).
679
Returns a command status or raises an exception.
681
Special master options: these must come before the command because
682
they control how the command is interpreted.
685
Do not load plugin modules at all
691
Only use builtin commands. (Plugins are still allowed to change
695
Run under the Python hotshot profiler.
698
Run under the Python lsprof profiler.
701
Generate line coverage report in the specified directory.
704
trace.mutter("bzr arguments: %r", argv)
706
opt_lsprof = opt_profile = opt_no_plugins = opt_builtin = \
707
opt_no_aliases = False
708
opt_lsprof_file = opt_coverage_dir = None
710
# --no-plugins is handled specially at a very early stage. We need
711
# to load plugins before doing other command parsing so that they
712
# can override commands, but this needs to happen first.
720
elif a == '--lsprof':
722
elif a == '--lsprof-file':
724
opt_lsprof_file = argv[i + 1]
726
elif a == '--no-plugins':
727
opt_no_plugins = True
728
elif a == '--no-aliases':
729
opt_no_aliases = True
730
elif a == '--builtin':
732
elif a == '--coverage':
733
opt_coverage_dir = argv[i + 1]
735
elif a.startswith('-D'):
736
debug.debug_flags.add(a[2:])
743
from bzrlib.builtins import cmd_help
744
cmd_help().run_argv_aliases([])
747
if argv[0] == '--version':
748
from bzrlib.builtins import cmd_version
749
cmd_version().run_argv_aliases([])
752
if not opt_no_plugins:
753
from bzrlib.plugin import load_plugins
756
from bzrlib.plugin import disable_plugins
761
if not opt_no_aliases:
762
alias_argv = get_alias(argv[0])
764
user_encoding = osutils.get_user_encoding()
765
alias_argv = [a.decode(user_encoding) for a in alias_argv]
766
argv[0] = alias_argv.pop(0)
769
# We want only 'ascii' command names, but the user may have typed
770
# in a Unicode name. In that case, they should just get a
771
# 'command not found' error later.
773
cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
774
run = cmd_obj.run_argv_aliases
775
run_argv = [argv, alias_argv]
778
# We can be called recursively (tests for example), but we don't want
779
# the verbosity level to propagate.
780
saved_verbosity_level = option._verbosity_level
781
option._verbosity_level = 0
785
'--coverage ignored, because --lsprof is in use.')
786
ret = apply_lsprofiled(opt_lsprof_file, run, *run_argv)
790
'--coverage ignored, because --profile is in use.')
791
ret = apply_profiled(run, *run_argv)
792
elif opt_coverage_dir:
793
ret = apply_coveraged(opt_coverage_dir, run, *run_argv)
796
if 'memory' in debug.debug_flags:
797
trace.debug_memory('Process status after command:', short=False)
800
# reset, in case we may do other commands later within the same
801
# process. Commands that want to execute sub-commands must propagate
802
# --verbose in their own way.
803
option._verbosity_level = saved_verbosity_level
805
def display_command(func):
806
"""Decorator that suppresses pipe/interrupt errors."""
807
def ignore_pipe(*args, **kwargs):
809
result = func(*args, **kwargs)
813
if getattr(e, 'errno', None) is None:
815
if e.errno != errno.EPIPE:
816
# Win32 raises IOError with errno=0 on a broken pipe
817
if sys.platform != 'win32' or (e.errno not in (0, errno.EINVAL)):
820
except KeyboardInterrupt:
827
from bzrlib.ui.text import TextUIFactory
828
bzrlib.ui.ui_factory = TextUIFactory()
830
# Is this a final release version? If so, we should suppress warnings
831
if bzrlib.version_info[3] == 'final':
832
from bzrlib import symbol_versioning
833
symbol_versioning.suppress_deprecation_warnings(override=False)
835
user_encoding = osutils.get_user_encoding()
836
argv = [a.decode(user_encoding) for a in argv[1:]]
837
except UnicodeDecodeError:
838
raise errors.BzrError(("Parameter '%r' is unsupported by the current "
840
ret = run_bzr_catch_errors(argv)
841
trace.mutter("return code %d", ret)
845
def run_bzr_catch_errors(argv):
846
# Note: The except clause logic below should be kept in sync with the
847
# profile() routine in lsprof.py.
850
except (KeyboardInterrupt, Exception), e:
851
# used to handle AssertionError and KeyboardInterrupt
852
# specially here, but hopefully they're handled ok by the logger now
853
exitcode = trace.report_exception(sys.exc_info(), sys.stderr)
854
if os.environ.get('BZR_PDB'):
855
print '**** entering debugger'
857
pdb.post_mortem(sys.exc_traceback)
861
def run_bzr_catch_user_errors(argv):
862
"""Run bzr and report user errors, but let internal errors propagate.
864
This is used for the test suite, and might be useful for other programs
865
that want to wrap the commandline interface.
870
if (isinstance(e, (OSError, IOError))
871
or not getattr(e, 'internal_error', True)):
872
trace.report_exception(sys.exc_info(), sys.stderr)
878
class HelpCommandIndex(object):
879
"""A index for bzr help that returns commands."""
882
self.prefix = 'commands/'
884
def get_topics(self, topic):
885
"""Search for topic amongst commands.
887
:param topic: A topic to search for.
888
:return: A list which is either empty or contains a single
891
if topic and topic.startswith(self.prefix):
892
topic = topic[len(self.prefix):]
894
cmd = _get_cmd_object(topic)
901
class Provider(object):
902
'''Generic class to be overriden by plugins'''
904
def plugin_for_command(self, cmd_name):
905
'''Takes a command and returns the information for that plugin
907
:return: A dictionary with all the available information
908
for the requested plugin
910
raise NotImplementedError
913
class ProvidersRegistry(registry.Registry):
914
'''This registry exists to allow other providers to exist'''
917
for key, provider in self.iteritems():
920
command_providers_registry = ProvidersRegistry()
923
if __name__ == '__main__':
924
sys.exit(main(sys.argv))
added
removed
bzrlib/commands.py
