360
357
summary, then a complete description of the command. A grammar
361
358
description will be inserted.
364
Other accepted names for this command.
367
List of argument forms, marked with whether they are optional,
372
['to_location', 'from_branch?', 'file*']
374
'to_location' is required
375
'from_branch' is optional
376
'file' can be specified 0 or more times
379
List of options that may be given for this command. These can
380
be either strings, referring to globally-defined options,
381
or option objects. Retrieve through options().
384
If true, this command isn't advertised. This is typically
360
:cvar aliases: Other accepted names for this command.
362
:cvar takes_args: List of argument forms, marked with whether they are
363
optional, repeated, etc. Examples::
365
['to_location', 'from_branch?', 'file*']
367
* 'to_location' is required
368
* 'from_branch' is optional
369
* 'file' can be specified 0 or more times
371
:cvar takes_options: List of options that may be given for this command.
372
These can be either strings, referring to globally-defined options, or
373
option objects. Retrieve through options().
375
:cvar hidden: If true, this command isn't advertised. This is typically
385
376
for commands intended for expert users.
388
Command objects will get a 'outf' attribute, which has been
389
setup to properly handle encoding of unicode strings.
390
encoding_type determines what will happen when characters cannot
392
strict - abort if we cannot decode
393
replace - put in a bogus character (typically '?')
394
exact - do not encode sys.stdout
396
NOTE: by default on Windows, sys.stdout is opened as a text
397
stream, therefore LF line-endings are converted to CRLF.
398
When a command uses encoding_type = 'exact', then
399
sys.stdout is forced to be a binary stream, and line-endings
378
:cvar encoding_type: Command objects will get a 'outf' attribute, which has
379
been setup to properly handle encoding of unicode strings.
380
encoding_type determines what will happen when characters cannot be
383
* strict - abort if we cannot decode
384
* replace - put in a bogus character (typically '?')
385
* exact - do not encode sys.stdout
387
NOTE: by default on Windows, sys.stdout is opened as a text stream,
388
therefore LF line-endings are converted to CRLF. When a command uses
389
encoding_type = 'exact', then sys.stdout is forced to be a binary
390
stream, and line-endings will not mangled.
393
A string indicating the real name under which this command was
394
invoked, before expansion of aliases.
395
(This may be None if the command was constructed and run in-process.)
402
397
:cvar hooks: An instance of CommandHooks.
399
:cvar __doc__: The help shown by 'bzr help command' for this command.
400
This is set by assigning explicitly to __doc__ so that -OO can
404
__doc__ = "My help goes here"
406
408
takes_options = []
407
409
encoding_type = 'strict'
411
414
def __init__(self):
412
415
"""Construct an instance of this command."""
413
if self.__doc__ == Command.__doc__:
414
warn("No help message set for %r" % self)
415
416
# List of standard options directly supported
416
417
self.supported_std_options = []
417
self._operation = cleanup.OperationWithCleanups(self.run)
419
420
def add_cleanup(self, cleanup_func, *args, **kwargs):
420
421
"""Register a function to call after self.run returns or raises.
510
513
# so we get <https://bugs.launchpad.net/bzr/+bug/249908>. -- mbp
512
515
options = option.get_optparser(self.options()).format_option_help()
513
# XXX: According to the spec, ReST option lists actually don't support
514
# options like --1.9 so that causes syntax errors (in Sphinx at least).
515
# As that pattern always appears in the commands that break, we trap
516
# on that and then format that block of 'format' options as a literal
518
if not plain and options.find(' --1.9 ') != -1:
516
# FIXME: According to the spec, ReST option lists actually don't
517
# support options like --1.14 so that causes syntax errors (in Sphinx
518
# at least). As that pattern always appears in the commands that
519
# break, we trap on that and then format that block of 'format' options
520
# as a literal block. We use the most recent format still listed so we
521
# don't have to do that too often -- vila 20110514
522
if not plain and options.find(' --1.14 ') != -1:
519
523
options = options.replace(' format:\n', ' format::\n\n', 1)
520
524
if options.startswith('Options:'):
521
525
result += ':' + options
684
688
self._setup_outf()
686
return self.run_direct(**all_cmd_args)
691
return self.run(**all_cmd_args)
693
# reset it, so that other commands run in the same process won't
694
# inherit state. Before we reset it, log any activity, so that it
695
# gets properly tracked.
696
ui.ui_factory.log_transport_activity(
697
display=('bytes' in debug.debug_flags))
698
trace.set_verbosity_level(0)
700
def _setup_run(self):
701
"""Wrap the defined run method on self with a cleanup.
703
This is called by __init__ to make the Command be able to be run
704
by just calling run(), as it could be before cleanups were added.
706
If a different form of cleanups are in use by your Command subclass,
707
you can override this method.
710
def run(*args, **kwargs):
711
self._operation = cleanup.OperationWithCleanups(class_run)
713
return self._operation.run_simple(*args, **kwargs)
718
@deprecated_method(deprecated_in((2, 2, 0)))
688
719
def run_direct(self, *args, **kwargs):
689
"""Call run directly with objects (without parsing an argv list)."""
690
return self._operation.run_simple(*args, **kwargs)
720
"""Deprecated thunk from bzrlib 2.1."""
721
return self.run(*args, **kwargs)
693
724
"""Actually run the command.
698
729
Return 0 or None if the command was successful, or a non-zero
699
730
shell error code if not. It's OK for this method to allow
700
731
an exception to raise up.
733
This method is automatically wrapped by Command.__init__ with a
734
cleanup operation, stored as self._operation. This can be used
735
via self.add_cleanup to perform automatic cleanups at the end of
738
The argument for run are assembled by introspection. So for instance,
739
if your command takes an argument files, you would declare::
741
def run(self, files=None):
702
744
raise NotImplementedError('no implementation of command %r'
733
779
These are all empty initially, because by default nothing should get
737
self.create_hook(HookPoint('extend_command',
782
Hooks.__init__(self, "bzrlib.commands", "Command.hooks")
783
self.add_hook('extend_command',
738
784
"Called after creating a command object to allow modifications "
739
785
"such as adding or removing options, docs etc. Called with the "
740
"new bzrlib.commands.Command object.", (1, 13), None))
741
self.create_hook(HookPoint('get_command',
786
"new bzrlib.commands.Command object.", (1, 13))
787
self.add_hook('get_command',
742
788
"Called when creating a single command. Called with "
743
789
"(cmd_or_None, command_name). get_command should either return "
744
790
"the cmd_or_None parameter, or a replacement Command object that "
745
791
"should be used for the command. Note that the Command.hooks "
746
792
"hooks are core infrastructure. Many users will prefer to use "
747
793
"bzrlib.commands.register_command or plugin_cmds.register_lazy.",
749
self.create_hook(HookPoint('get_missing_command',
795
self.add_hook('get_missing_command',
750
796
"Called when creating a single command if no command could be "
751
797
"found. Called with (command_name). get_missing_command should "
752
798
"either return None, or a Command object to be used for the "
753
"command.", (1, 17), None))
754
self.create_hook(HookPoint('list_commands',
800
self.add_hook('list_commands',
755
801
"Called when enumerating commands. Called with a set of "
756
802
"cmd_name strings for all the commands found so far. This set "
757
803
" is safe to mutate - e.g. to remove a command. "
758
804
"list_commands should return the updated set of command names.",
761
807
Command.hooks = CommandHooks()
1048
1102
if not opt_no_aliases:
1049
1103
alias_argv = get_alias(argv[0])
1051
user_encoding = osutils.get_user_encoding()
1052
alias_argv = [a.decode(user_encoding) for a in alias_argv]
1053
1105
argv[0] = alias_argv.pop(0)
1055
1107
cmd = argv.pop(0)
1056
# We want only 'ascii' command names, but the user may have typed
1057
# in a Unicode name. In that case, they should just get a
1058
# 'command not found' error later.
1060
1108
cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
1061
1109
run = cmd_obj.run_argv_aliases
1062
1110
run_argv = [argv, alias_argv]
1223
1270
class Provider(object):
1224
'''Generic class to be overriden by plugins'''
1271
"""Generic class to be overriden by plugins"""
1226
1273
def plugin_for_command(self, cmd_name):
1227
'''Takes a command and returns the information for that plugin
1274
"""Takes a command and returns the information for that plugin
1229
1276
:return: A dictionary with all the available information
1230
for the requested plugin
1277
for the requested plugin
1232
1279
raise NotImplementedError
1235
1282
class ProvidersRegistry(registry.Registry):
1236
'''This registry exists to allow other providers to exist'''
1283
"""This registry exists to allow other providers to exist"""
1238
1285
def __iter__(self):
1239
1286
for key, provider in self.iteritems():
added
removed
bzrlib/commands.py
