29
28
from bzrlib.lazy_import import lazy_import
30
29
lazy_import(globals(), """
33
from warnings import warn
35
36
from bzrlib import (
49
from bzrlib.hooks import Hooks
50
from bzrlib.i18n import gettext
49
from bzrlib.hooks import HookPoint, Hooks
51
50
# Compatibility - Option used to be in commands.
52
51
from bzrlib.option import Option
53
52
from bzrlib.plugin import disable_plugins, load_plugins
54
53
from bzrlib import registry
54
from bzrlib.symbol_versioning import (
57
61
class CommandInfo(object):
346
358
summary, then a complete description of the command. A grammar
347
359
description will be inserted.
349
:cvar aliases: Other accepted names for this command.
351
:cvar takes_args: List of argument forms, marked with whether they are
352
optional, repeated, etc. Examples::
354
['to_location', 'from_branch?', 'file*']
356
* 'to_location' is required
357
* 'from_branch' is optional
358
* 'file' can be specified 0 or more times
360
:cvar takes_options: List of options that may be given for this command.
361
These can be either strings, referring to globally-defined options, or
362
option objects. Retrieve through options().
364
:cvar hidden: If true, this command isn't advertised. This is typically
362
Other accepted names for this command.
365
List of argument forms, marked with whether they are optional,
370
['to_location', 'from_branch?', 'file*']
372
'to_location' is required
373
'from_branch' is optional
374
'file' can be specified 0 or more times
377
List of options that may be given for this command. These can
378
be either strings, referring to globally-defined options,
379
or option objects. Retrieve through options().
382
If true, this command isn't advertised. This is typically
365
383
for commands intended for expert users.
367
:cvar encoding_type: Command objects will get a 'outf' attribute, which has
368
been setup to properly handle encoding of unicode strings.
369
encoding_type determines what will happen when characters cannot be
372
* strict - abort if we cannot decode
373
* replace - put in a bogus character (typically '?')
374
* exact - do not encode sys.stdout
376
NOTE: by default on Windows, sys.stdout is opened as a text stream,
377
therefore LF line-endings are converted to CRLF. When a command uses
378
encoding_type = 'exact', then sys.stdout is forced to be a binary
379
stream, and line-endings will not mangled.
382
A string indicating the real name under which this command was
383
invoked, before expansion of aliases.
384
(This may be None if the command was constructed and run in-process.)
386
Command objects will get a 'outf' attribute, which has been
387
setup to properly handle encoding of unicode strings.
388
encoding_type determines what will happen when characters cannot
390
strict - abort if we cannot decode
391
replace - put in a bogus character (typically '?')
392
exact - do not encode sys.stdout
394
NOTE: by default on Windows, sys.stdout is opened as a text
395
stream, therefore LF line-endings are converted to CRLF.
396
When a command uses encoding_type = 'exact', then
397
sys.stdout is forced to be a binary stream, and line-endings
386
400
:cvar hooks: An instance of CommandHooks.
388
:cvar __doc__: The help shown by 'bzr help command' for this command.
401
:ivar __doc__: The help shown by 'bzr help command' for this command.
389
402
This is set by assigning explicitly to __doc__ so that -OO can
393
__doc__ = "My help goes here"
406
__doc__ = "My help goes here"
397
410
takes_options = []
398
411
encoding_type = 'strict'
462
486
usage help (e.g. Purpose, Usage, Options) with a
463
487
message explaining how to obtain full help.
466
i18n.install() # Install i18n only for get_help_text for now.
467
489
doc = self.help()
469
# Note: If self.gettext() translates ':Usage:\n', the section will
470
# be shown after "Description" section and we don't want to
471
# translate the usage string.
472
# Though, bzr export-pot don't exports :Usage: section and it must
474
doc = self.gettext(doc)
476
doc = gettext("No help for this command.")
491
doc = "No help for this command."
478
493
# Extract the summary (purpose) and sections out from the text
479
494
purpose,sections,order = self._get_help_parts(doc)
498
513
# XXX: optparse implicitly rewraps the help, and not always perfectly,
499
514
# so we get <https://bugs.launchpad.net/bzr/+bug/249908>. -- mbp
501
parser = option.get_optparser(self.options())
502
options = parser.format_option_help()
503
# FIXME: According to the spec, ReST option lists actually don't
504
# support options like --1.14 so that causes syntax errors (in Sphinx
505
# at least). As that pattern always appears in the commands that
506
# break, we trap on that and then format that block of 'format' options
507
# as a literal block. We use the most recent format still listed so we
508
# don't have to do that too often -- vila 20110514
509
if not plain and options.find(' --1.14 ') != -1:
516
options = option.get_optparser(self.options()).format_option_help()
517
# XXX: According to the spec, ReST option lists actually don't support
518
# options like --1.9 so that causes syntax errors (in Sphinx at least).
519
# As that pattern always appears in the commands that break, we trap
520
# on that and then format that block of 'format' options as a literal
522
if not plain and options.find(' --1.9 ') != -1:
510
523
options = options.replace(' format:\n', ' format::\n\n', 1)
511
524
if options.startswith('Options:'):
512
result += gettext(':Options:%s') % (options[len('options:'):],)
525
result += ':' + options
526
elif options.startswith('options:'):
527
# Python 2.4 version of optparse
528
result += ':Options:' + options[len('options:'):]
514
530
result += options
520
536
if sections.has_key(None):
521
537
text = sections.pop(None)
522
538
text = '\n '.join(text.splitlines())
523
result += gettext(':Description:\n %s\n\n') % (text,)
539
result += ':%s:\n %s\n\n' % ('Description',text)
525
541
# Add the custom sections (e.g. Examples). Note that there's no need
526
542
# to indent these as they must be indented already in the source.
528
544
for label in order:
529
if label in sections:
530
result += ':%s:\n%s\n' % (label, sections[label])
545
if sections.has_key(label):
546
result += ':%s:\n%s\n' % (label,sections[label])
533
result += (gettext("See bzr help %s for more details and examples.\n\n")
549
result += ("See bzr help %s for more details and examples.\n\n"
536
552
# Add the aliases, source (plug-in) and see also links, if any
538
result += gettext(':Aliases: ')
554
result += ':Aliases: '
539
555
result += ', '.join(self.aliases) + '\n'
540
556
plugin_name = self.plugin_name()
541
557
if plugin_name is not None:
542
result += gettext(':From: plugin "%s"\n') % plugin_name
558
result += ':From: plugin "%s"\n' % plugin_name
543
559
see_also = self.get_see_also(additional_see_also)
545
561
if not plain and see_also_as_links:
551
567
see_also_links.append(item)
553
569
# Use a Sphinx link for this entry
554
link_text = gettext(":doc:`{0} <{1}-help>`").format(
570
link_text = ":doc:`%s <%s-help>`" % (item, item)
556
571
see_also_links.append(link_text)
557
572
see_also = see_also_links
558
result += gettext(':See also: %s') % ', '.join(see_also) + '\n'
573
result += ':See also: '
574
result += ', '.join(see_also) + '\n'
560
576
# If this will be rendered as plain text, convert it
642
658
def run_argv_aliases(self, argv, alias_argv=None):
643
659
"""Parse the command line and run with extra aliases in alias_argv."""
644
660
args, opts = parse_args(self, argv, alias_argv)
647
662
# Process the standard options
648
663
if 'help' in opts: # e.g. bzr add --help
649
self.outf.write(self.get_help_text())
664
sys.stdout.write(self.get_help_text())
651
666
if 'usage' in opts: # e.g. bzr add --usage
652
self.outf.write(self.get_help_text(verbose=False))
667
sys.stdout.write(self.get_help_text(verbose=False))
654
669
trace.set_verbosity_level(option._verbosity_level)
655
670
if 'verbose' in self.supported_std_options:
669
685
all_cmd_args = cmdargs.copy()
670
686
all_cmd_args.update(cmdopts)
673
return self.run(**all_cmd_args)
675
# reset it, so that other commands run in the same process won't
676
# inherit state. Before we reset it, log any activity, so that it
677
# gets properly tracked.
678
ui.ui_factory.log_transport_activity(
679
display=('bytes' in debug.debug_flags))
680
trace.set_verbosity_level(0)
690
return self.run(**all_cmd_args)
682
692
def _setup_run(self):
683
693
"""Wrap the defined run method on self with a cleanup.
691
701
class_run = self.run
692
702
def run(*args, **kwargs):
693
for hook in Command.hooks['pre_command']:
695
703
self._operation = cleanup.OperationWithCleanups(class_run)
697
705
return self._operation.run_simple(*args, **kwargs)
699
707
del self._operation
700
for hook in Command.hooks['post_command']:
710
@deprecated_method(deprecated_in((2, 2, 0)))
711
def run_direct(self, *args, **kwargs):
712
"""Deprecated thunk from bzrlib 2.1."""
713
return self.run(*args, **kwargs)
705
716
"""Actually run the command.
768
767
These are all empty initially, because by default nothing should get
771
Hooks.__init__(self, "bzrlib.commands", "Command.hooks")
772
self.add_hook('extend_command',
771
self.create_hook(HookPoint('extend_command',
773
772
"Called after creating a command object to allow modifications "
774
773
"such as adding or removing options, docs etc. Called with the "
775
"new bzrlib.commands.Command object.", (1, 13))
776
self.add_hook('get_command',
774
"new bzrlib.commands.Command object.", (1, 13), None))
775
self.create_hook(HookPoint('get_command',
777
776
"Called when creating a single command. Called with "
778
777
"(cmd_or_None, command_name). get_command should either return "
779
778
"the cmd_or_None parameter, or a replacement Command object that "
780
779
"should be used for the command. Note that the Command.hooks "
781
780
"hooks are core infrastructure. Many users will prefer to use "
782
781
"bzrlib.commands.register_command or plugin_cmds.register_lazy.",
784
self.add_hook('get_missing_command',
783
self.create_hook(HookPoint('get_missing_command',
785
784
"Called when creating a single command if no command could be "
786
785
"found. Called with (command_name). get_missing_command should "
787
786
"either return None, or a Command object to be used for the "
789
self.add_hook('list_commands',
787
"command.", (1, 17), None))
788
self.create_hook(HookPoint('list_commands',
790
789
"Called when enumerating commands. Called with a set of "
791
790
"cmd_name strings for all the commands found so far. This set "
792
791
" is safe to mutate - e.g. to remove a command. "
793
792
"list_commands should return the updated set of command names.",
795
self.add_hook('pre_command',
796
"Called prior to executing a command. Called with the command "
798
self.add_hook('post_command',
799
"Called after executing a command. Called with the command "
802
795
Command.hooks = CommandHooks()
820
# for python 2.5 and later, optparse raises this exception if a non-ascii
821
# option name is given. See http://bugs.python.org/issue2931
823
options, args = parser.parse_args(args)
824
except UnicodeEncodeError,e:
825
raise errors.BzrCommandError(
826
gettext('Only ASCII permitted in option names'))
813
options, args = parser.parse_args(args)
828
814
opts = dict([(k, v) for k, v in options.__dict__.iteritems() if
829
815
v is not option.OptionParser.DEFAULT_VALUE])
830
816
return args, opts
847
833
argdict[argname + '_list'] = None
848
834
elif ap[-1] == '+':
850
raise errors.BzrCommandError(gettext(
851
"command {0!r} needs one or more {1}").format(
852
cmd, argname.upper()))
836
raise errors.BzrCommandError("command %r needs one or more %s"
837
% (cmd, argname.upper()))
854
839
argdict[argname + '_list'] = args[:]
856
841
elif ap[-1] == '$': # all but one
857
842
if len(args) < 2:
858
raise errors.BzrCommandError(
859
gettext("command {0!r} needs one or more {1}").format(
860
cmd, argname.upper()))
843
raise errors.BzrCommandError("command %r needs one or more %s"
844
% (cmd, argname.upper()))
861
845
argdict[argname + '_list'] = args[:-1]
864
848
# just a plain arg
867
raise errors.BzrCommandError(
868
gettext("command {0!r} requires argument {1}").format(
869
cmd, argname.upper()))
851
raise errors.BzrCommandError("command %r requires argument %s"
852
% (cmd, argname.upper()))
871
854
argdict[argname] = args.pop(0)
874
raise errors.BzrCommandError( gettext(
875
"extra argument to command {0}: {1}").format(
857
raise errors.BzrCommandError("extra argument to command %s: %s"
935
917
exitcode = trace.report_exception(exc_info, sys.stderr)
936
918
if os.environ.get('BZR_PDB'):
937
919
print '**** entering debugger'
939
pdb.post_mortem(exc_info[2])
922
if sys.version_info[:2] < (2, 6):
924
# pdb.post_mortem(tb)
925
# but because pdb.post_mortem gives bad results for tracebacks
926
# from inside generators, we do it manually.
927
# (http://bugs.python.org/issue4150, fixed in Python 2.6)
929
# Setup pdb on the traceback
932
p.setup(tb.tb_frame, tb)
933
# Point the debugger at the deepest frame of the stack
934
p.curindex = len(p.stack) - 1
935
p.curframe = p.stack[p.curindex][0]
936
# Start the pdb prompt.
937
p.print_stack_entry(p.stack[p.curindex])
943
945
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
944
946
from bzrlib.lsprof import profile
945
ret, stats = profile(exception_to_return_code, the_callable,
947
ret, stats = profile(exception_to_return_code, the_callable, *args, **kwargs)
948
949
if filename is None:
951
952
stats.save(filename)
952
trace.note(gettext('Profile data written to "%s".'), filename)
953
trace.note('Profile data written to "%s".', filename)
957
@deprecated_function(deprecated_in((2, 2, 0)))
958
def shlex_split_unicode(unsplit):
959
return cmdline.split(unsplit)
956
962
def get_alias(cmd, config=None):
957
963
"""Return an expanded alias, or None if no alias exists.
1056
1059
pass # already handled in startup script Bug #588277
1057
1060
elif a.startswith('-D'):
1058
1061
debug.debug_flags.add(a[2:])
1059
elif a.startswith('-O'):
1060
override_config.append(a[2:])
1062
1063
argv_copy.append(a)
1065
if bzrlib.global_state is None:
1066
# FIXME: Workaround for users that imported bzrlib but didn't call
1067
# bzrlib.initialize -- vila 2012-01-19
1068
cmdline_overrides = config.CommandLineStore()
1070
cmdline_overrides = bzrlib.global_state.cmdline_overrides
1071
cmdline_overrides._from_cmdline(override_config)
1073
1066
debug.set_debug_flags_from_config()
1075
1068
if not opt_no_plugins:
1264
1253
class Provider(object):
1265
"""Generic class to be overriden by plugins"""
1254
'''Generic class to be overriden by plugins'''
1267
1256
def plugin_for_command(self, cmd_name):
1268
"""Takes a command and returns the information for that plugin
1257
'''Takes a command and returns the information for that plugin
1270
1259
:return: A dictionary with all the available information
1271
for the requested plugin
1260
for the requested plugin
1273
1262
raise NotImplementedError
1276
1265
class ProvidersRegistry(registry.Registry):
1277
"""This registry exists to allow other providers to exist"""
1266
'''This registry exists to allow other providers to exist'''
1279
1268
def __iter__(self):
1280
1269
for key, provider in self.iteritems():