51
from bzrlib import registry
50
from bzrlib.symbol_versioning import (
53
from bzrlib.hooks import HookPoint, Hooks
54
57
from bzrlib.option import Option
57
class CommandInfo(object):
58
"""Information about a command."""
60
def __init__(self, aliases):
61
"""The list of aliases for the command."""
62
self.aliases = aliases
65
def from_command(klass, command):
66
"""Factory to construct a CommandInfo from a command."""
67
return klass(command.aliases)
70
class CommandRegistry(registry.Registry):
73
def _get_name(command_name):
74
if command_name.startswith("cmd_"):
75
return _unsquish_command_name(command_name)
79
def register(self, cmd, decorate=False):
80
"""Utility function to help register a command
82
:param cmd: Command subclass to register
83
:param decorate: If true, allow overriding an existing command
84
of the same name; the old command is returned by this function.
85
Otherwise it is an error to try to override an existing command.
88
k_unsquished = self._get_name(k)
90
previous = self.get(k_unsquished)
92
previous = _builtin_commands().get(k_unsquished)
93
info = CommandInfo.from_command(cmd)
95
registry.Registry.register(self, k_unsquished, cmd,
96
override_existing=decorate, info=info)
98
trace.log_error('Two plugins defined the same command: %r' % k)
99
trace.log_error('Not loading the one in %r' %
100
sys.modules[cmd.__module__])
101
trace.log_error('Previously this command was registered from %r' %
102
sys.modules[previous.__module__])
105
def register_lazy(self, command_name, aliases, module_name):
106
"""Register a command without loading its module.
108
:param command_name: The primary name of the command.
109
:param aliases: A list of aliases for the command.
110
:module_name: The module that the command lives in.
112
key = self._get_name(command_name)
113
registry.Registry.register_lazy(self, key, module_name, command_name,
114
info=CommandInfo(aliases))
117
plugin_cmds = CommandRegistry()
120
63
def register_command(cmd, decorate=False):
64
"""Utility function to help register a command
66
:param cmd: Command subclass to register
67
:param decorate: If true, allow overriding an existing command
68
of the same name; the old command is returned by this function.
69
Otherwise it is an error to try to override an existing command.
121
71
global plugin_cmds
122
return plugin_cmds.register(cmd, decorate)
73
if k.startswith("cmd_"):
74
k_unsquished = _unsquish_command_name(k)
77
if k_unsquished not in plugin_cmds:
78
plugin_cmds[k_unsquished] = cmd
79
## trace.mutter('registered plugin command %s', k_unsquished)
80
if decorate and k_unsquished in builtin_command_names():
81
return _builtin_commands()[k_unsquished]
83
result = plugin_cmds[k_unsquished]
84
plugin_cmds[k_unsquished] = cmd
87
trace.log_error('Two plugins defined the same command: %r' % k)
88
trace.log_error('Not loading the one in %r' % sys.modules[cmd.__module__])
125
91
def _squish_command_name(cmd):
291
227
encoding_type = 'strict'
295
231
def __init__(self):
296
232
"""Construct an instance of this command."""
297
233
if self.__doc__ == Command.__doc__:
298
234
warn("No help message set for %r" % self)
299
# List of standard options directly supported
300
self.supported_std_options = []
302
def _maybe_expand_globs(self, file_list):
303
"""Glob expand file_list if the platform does not do that itself.
305
:return: A possibly empty list of unicode paths.
307
Introduced in bzrlib 0.18.
311
if sys.platform == 'win32':
312
file_list = win32utils.glob_expand(file_list)
313
return list(file_list)
316
"""Return single-line grammar for this command.
318
Only describes arguments, not options.
320
s = 'bzr ' + self.name() + ' '
321
for aname in self.takes_args:
322
aname = aname.upper()
323
if aname[-1] in ['$', '+']:
324
aname = aname[:-1] + '...'
325
elif aname[-1] == '?':
326
aname = '[' + aname[:-1] + ']'
327
elif aname[-1] == '*':
328
aname = '[' + aname[:-1] + '...]'
330
s = s[:-1] # remove last space
333
def get_help_text(self, additional_see_also=None, plain=True,
334
see_also_as_links=False, verbose=True):
335
"""Return a text string with help for this command.
337
:param additional_see_also: Additional help topics to be
339
:param plain: if False, raw help (reStructuredText) is
340
returned instead of plain text.
341
:param see_also_as_links: if True, convert items in 'See also'
342
list to internal links (used by bzr_man rstx generator)
343
:param verbose: if True, display the full help, otherwise
344
leave out the descriptive sections and just display
345
usage help (e.g. Purpose, Usage, Options) with a
346
message explaining how to obtain full help.
350
raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
352
# Extract the summary (purpose) and sections out from the text
353
purpose,sections,order = self._get_help_parts(doc)
355
# If a custom usage section was provided, use it
356
if sections.has_key('Usage'):
357
usage = sections.pop('Usage')
359
usage = self._usage()
361
# The header is the purpose and usage
363
result += ':Purpose: %s\n' % purpose
364
if usage.find('\n') >= 0:
365
result += ':Usage:\n%s\n' % usage
367
result += ':Usage: %s\n' % usage
371
options = option.get_optparser(self.options()).format_option_help()
372
if options.startswith('Options:'):
373
result += ':' + options
374
elif options.startswith('options:'):
375
# Python 2.4 version of optparse
376
result += ':Options:' + options[len('options:'):]
382
# Add the description, indenting it 2 spaces
383
# to match the indentation of the options
384
if sections.has_key(None):
385
text = sections.pop(None)
386
text = '\n '.join(text.splitlines())
387
result += ':%s:\n %s\n\n' % ('Description',text)
389
# Add the custom sections (e.g. Examples). Note that there's no need
390
# to indent these as they must be indented already in the source.
393
if sections.has_key(label):
394
result += ':%s:\n%s\n' % (label,sections[label])
397
result += ("See bzr help %s for more details and examples.\n\n"
400
# Add the aliases, source (plug-in) and see also links, if any
402
result += ':Aliases: '
403
result += ', '.join(self.aliases) + '\n'
404
plugin_name = self.plugin_name()
405
if plugin_name is not None:
406
result += ':From: plugin "%s"\n' % plugin_name
407
see_also = self.get_see_also(additional_see_also)
409
if not plain and see_also_as_links:
411
for item in see_also:
413
# topics doesn't have an independent section
414
# so don't create a real link
415
see_also_links.append(item)
417
# Use a reST link for this entry
418
see_also_links.append("`%s`_" % (item,))
419
see_also = see_also_links
420
result += ':See also: '
421
result += ', '.join(see_also) + '\n'
423
# If this will be rendered as plain text, convert it
425
import bzrlib.help_topics
426
result = bzrlib.help_topics.help_as_plain_text(result)
430
def _get_help_parts(text):
431
"""Split help text into a summary and named sections.
433
:return: (summary,sections,order) where summary is the top line and
434
sections is a dictionary of the rest indexed by section name.
435
order is the order the section appear in the text.
436
A section starts with a heading line of the form ":xxx:".
437
Indented text on following lines is the section value.
438
All text found outside a named section is assigned to the
439
default section which is given the key of None.
441
def save_section(sections, order, label, section):
443
if sections.has_key(label):
444
sections[label] += '\n' + section
447
sections[label] = section
449
lines = text.rstrip().splitlines()
450
summary = lines.pop(0)
453
label,section = None,''
455
if line.startswith(':') and line.endswith(':') and len(line) > 2:
456
save_section(sections, order, label, section)
457
label,section = line[1:-1],''
458
elif (label is not None) and len(line) > 1 and not line[0].isspace():
459
save_section(sections, order, label, section)
460
label,section = None,line
463
section += '\n' + line
466
save_section(sections, order, label, section)
467
return summary, sections, order
469
def get_help_topic(self):
470
"""Return the commands help topic - its name."""
473
def get_see_also(self, additional_terms=None):
474
"""Return a list of help topics that are related to this command.
476
The list is derived from the content of the _see_also attribute. Any
477
duplicates are removed and the result is in lexical order.
478
:param additional_terms: Additional help topics to cross-reference.
479
:return: A list of help topics.
481
see_also = set(getattr(self, '_see_also', []))
483
see_also.update(additional_terms)
484
return sorted(see_also)
486
236
def options(self):
487
237
"""Return dict of valid options for this command.
489
239
Maps from long option name to option object."""
490
r = Option.STD_OPTIONS.copy()
241
r['help'] = option.Option.OPTIONS['help']
492
242
for o in self.takes_options:
493
243
if isinstance(o, basestring):
494
244
o = option.Option.OPTIONS[o]
496
if o.name in std_names:
497
self.supported_std_options.append(o.name)
500
248
def _setup_outf(self):
501
249
"""Return a file linked to stdout, which has proper encoding."""
250
assert self.encoding_type in ['strict', 'exact', 'replace']
502
252
# Originally I was using self.stdout, but that looks
503
253
# *way* too much like sys.stdout
504
254
if self.encoding_type == 'exact':
596
class CommandHooks(Hooks):
597
"""Hooks related to Command object creation/enumeration."""
600
"""Create the default hooks.
602
These are all empty initially, because by default nothing should get
606
self.create_hook(HookPoint('extend_command',
607
"Called after creating a command object to allow modifications "
608
"such as adding or removing options, docs etc. Called with the "
609
"new bzrlib.commands.Command object.", (1, 13), None))
611
Command.hooks = CommandHooks()
341
# Technically, this function hasn't been use in a *really* long time
342
# but we are only deprecating it now.
343
@deprecated_function(zero_eleven)
344
def parse_spec(spec):
350
>>> parse_spec("../@")
352
>>> parse_spec("../f/@35")
354
>>> parse_spec('./@revid:john@arbash-meinel.com-20050711044610-3ca0327c6a222f67')
355
['.', 'revid:john@arbash-meinel.com-20050711044610-3ca0327c6a222f67']
360
parsed = spec.split('/@')
361
assert len(parsed) == 2
366
parsed[1] = int(parsed[1])
368
pass # We can allow stuff like ./@revid:blahblahblah
372
parsed = [spec, None]
614
375
def parse_args(command, argv, alias_argv=None):
615
376
"""Parse command line.
617
378
Arguments and options are parsed at this level before being passed
618
379
down to specific command handlers. This routine knows, from a
619
380
lookup table, something about the available options, what optargs
716
461
os.remove(pfname)
719
def exception_to_return_code(the_callable, *args, **kwargs):
720
"""UI level helper for profiling and coverage.
722
This transforms exceptions into a return value of 3. As such its only
723
relevant to the UI layer, and should never be called where catching
724
exceptions may be desirable.
727
return the_callable(*args, **kwargs)
728
except (KeyboardInterrupt, Exception), e:
729
# used to handle AssertionError and KeyboardInterrupt
730
# specially here, but hopefully they're handled ok by the logger now
731
exc_info = sys.exc_info()
732
exitcode = trace.report_exception(exc_info, sys.stderr)
733
if os.environ.get('BZR_PDB'):
734
print '**** entering debugger'
737
if sys.version_info[:2] < (2, 6):
739
# pdb.post_mortem(tb)
740
# but because pdb.post_mortem gives bad results for tracebacks
741
# from inside generators, we do it manually.
742
# (http://bugs.python.org/issue4150, fixed in Python 2.6)
744
# Setup pdb on the traceback
747
p.setup(tb.tb_frame, tb)
748
# Point the debugger at the deepest frame of the stack
749
p.curindex = len(p.stack) - 1
750
p.curframe = p.stack[p.curindex][0]
751
# Start the pdb prompt.
752
p.print_stack_entry(p.stack[p.curindex])
760
464
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
761
465
from bzrlib.lsprof import profile
762
ret, stats = profile(exception_to_return_code, the_callable, *args, **kwargs)
467
ret, stats = profile(the_callable, *args, **kwargs)
764
469
if filename is None:
768
trace.note('Profile data written to "%s".', filename)
473
cPickle.dump(stats, open(filename, 'w'), 2)
474
print 'Profile data written to %r.' % filename
772
def shlex_split_unicode(unsplit):
774
return [u.decode('utf-8') for u in shlex.split(unsplit.encode('utf-8'))]
777
478
def get_alias(cmd, config=None):
778
479
"""Return an expanded alias, or None if no alias exists.
898
596
# 'command not found' error later.
900
598
cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
901
run = cmd_obj.run_argv_aliases
902
run_argv = [argv, alias_argv]
599
if not getattr(cmd_obj.run_argv, 'is_deprecated', False):
600
run = cmd_obj.run_argv
603
run = cmd_obj.run_argv_aliases
604
run_argv = [argv, alias_argv]
905
# We can be called recursively (tests for example), but we don't want
906
# the verbosity level to propagate.
907
saved_verbosity_level = option._verbosity_level
908
option._verbosity_level = 0
912
'--coverage ignored, because --lsprof is in use.')
913
608
ret = apply_lsprofiled(opt_lsprof_file, run, *run_argv)
914
609
elif opt_profile:
917
'--coverage ignored, because --profile is in use.')
918
610
ret = apply_profiled(run, *run_argv)
919
elif opt_coverage_dir:
920
ret = apply_coveraged(opt_coverage_dir, run, *run_argv)
922
612
ret = run(*run_argv)
923
if 'memory' in debug.debug_flags:
924
trace.debug_memory('Process status after command:', short=False)
927
# reset, in case we may do other commands later within the same
928
# process. Commands that want to execute sub-commands must propagate
929
# --verbose in their own way.
930
option._verbosity_level = saved_verbosity_level
615
# reset, in case we may do other commands later within the same process
616
trace.be_quiet(False)
933
618
def display_command(func):
934
619
"""Decorator that suppresses pipe/interrupt errors."""
955
bzrlib.ui.ui_factory = bzrlib.ui.make_ui_for_terminal(
956
sys.stdin, sys.stdout, sys.stderr)
958
# Is this a final release version? If so, we should suppress warnings
959
if bzrlib.version_info[3] == 'final':
960
from bzrlib import symbol_versioning
961
symbol_versioning.suppress_deprecation_warnings(override=False)
963
user_encoding = osutils.get_user_encoding()
964
argv = [a.decode(user_encoding) for a in argv[1:]]
965
except UnicodeDecodeError:
966
raise errors.BzrError(("Parameter '%r' is unsupported by the current "
640
from bzrlib.ui.text import TextUIFactory
641
bzrlib.ui.ui_factory = TextUIFactory()
642
argv = [a.decode(bzrlib.user_encoding) for a in argv[1:]]
968
643
ret = run_bzr_catch_errors(argv)
969
644
trace.mutter("return code %d", ret)
973
648
def run_bzr_catch_errors(argv):
974
"""Run a bzr command with parameters as described by argv.
976
This function assumed that that UI layer is setup, that symbol deprecations
977
are already applied, and that unicode decoding has already been performed on argv.
979
return exception_to_return_code(run_bzr, argv)
982
def run_bzr_catch_user_errors(argv):
983
"""Run bzr and report user errors, but let internal errors propagate.
985
This is used for the test suite, and might be useful for other programs
986
that want to wrap the commandline interface.
989
650
return run_bzr(argv)
991
if (isinstance(e, (OSError, IOError))
992
or not getattr(e, 'internal_error', True)):
993
trace.report_exception(sys.exc_info(), sys.stderr)
999
class HelpCommandIndex(object):
1000
"""A index for bzr help that returns commands."""
1003
self.prefix = 'commands/'
1005
def get_topics(self, topic):
1006
"""Search for topic amongst commands.
1008
:param topic: A topic to search for.
1009
:return: A list which is either empty or contains a single
1012
if topic and topic.startswith(self.prefix):
1013
topic = topic[len(self.prefix):]
1015
cmd = _get_cmd_object(topic)
1022
class Provider(object):
1023
'''Generic class to be overriden by plugins'''
1025
def plugin_for_command(self, cmd_name):
1026
'''Takes a command and returns the information for that plugin
1028
:return: A dictionary with all the available information
1029
for the requested plugin
1031
raise NotImplementedError
1034
class ProvidersRegistry(registry.Registry):
1035
'''This registry exists to allow other providers to exist'''
1038
for key, provider in self.iteritems():
1041
command_providers_registry = ProvidersRegistry()
651
# do this here inside the exception wrappers to catch EPIPE
653
except (KeyboardInterrupt, Exception), e:
654
# used to handle AssertionError and KeyboardInterrupt
655
# specially here, but hopefully they're handled ok by the logger now
656
trace.report_exception(sys.exc_info(), sys.stderr)
657
if os.environ.get('BZR_PDB'):
658
print '**** entering debugger'
660
pdb.post_mortem(sys.exc_traceback)
1044
663
if __name__ == '__main__':
1045
664
sys.exit(main(sys.argv))
added
removed
bzrlib/commands.py
