b.c.Command(object) : class documentation

Part of bzrlib.commands View In Hierarchy

Known subclasses: bzrlib.builtins.cmd_add, bzrlib.builtins.cmd_added, bzrlib.builtins.cmd_alias, bzrlib.builtins.cmd_ancestry, bzrlib.builtins.cmd_annotate, bzrlib.builtins.cmd_assert_fail, bzrlib.builtins.cmd_bind, bzrlib.builtins.cmd_branch, bzrlib.builtins.cmd_branches, bzrlib.builtins.cmd_break_lock, bzrlib.builtins.cmd_cat, bzrlib.builtins.cmd_cat_revision, bzrlib.builtins.cmd_check, bzrlib.builtins.cmd_checkout, bzrlib.builtins.cmd_clean_tree, bzrlib.builtins.cmd_commit, bzrlib.builtins.cmd_deleted, bzrlib.builtins.cmd_diff, bzrlib.builtins.cmd_dump_btree, bzrlib.builtins.cmd_export, bzrlib.builtins.cmd_export_pot, bzrlib.builtins.cmd_file_id, bzrlib.builtins.cmd_file_path, bzrlib.builtins.cmd_find_merge_base, bzrlib.builtins.cmd_help, bzrlib.builtins.cmd_hooks, bzrlib.builtins.cmd_ignore, bzrlib.builtins.cmd_ignored, bzrlib.builtins.cmd_info, bzrlib.builtins.cmd_init, bzrlib.builtins.cmd_init_repository, bzrlib.builtins.cmd_inventory, bzrlib.builtins.cmd_join, bzrlib.builtins.cmd_local_time_offset, bzrlib.builtins.cmd_log, bzrlib.builtins.cmd_lookup_revision, bzrlib.builtins.cmd_ls, bzrlib.builtins.cmd_merge, bzrlib.builtins.cmd_merge_directive, bzrlib.builtins.cmd_missing, bzrlib.builtins.cmd_mkdir, bzrlib.builtins.cmd_modified, bzrlib.builtins.cmd_mv, bzrlib.builtins.cmd_nick, bzrlib.builtins.cmd_pack, bzrlib.builtins.cmd_plugins, bzrlib.builtins.cmd_pull, bzrlib.builtins.cmd_push, bzrlib.builtins.cmd_re_sign, bzrlib.builtins.cmd_reconcile, bzrlib.builtins.cmd_reconfigure, bzrlib.builtins.cmd_reference, bzrlib.builtins.cmd_relpath, bzrlib.builtins.cmd_remerge, bzrlib.builtins.cmd_remove, bzrlib.builtins.cmd_remove_branch, bzrlib.builtins.cmd_remove_tree, bzrlib.builtins.cmd_renames, bzrlib.builtins.cmd_repair_workingtree, bzrlib.builtins.cmd_revert, bzrlib.builtins.cmd_revision_history, bzrlib.builtins.cmd_revision_info, bzrlib.builtins.cmd_revno, bzrlib.builtins.cmd_rocks, bzrlib.builtins.cmd_root, bzrlib.builtins.cmd_selftest, bzrlib.builtins.cmd_send, bzrlib.builtins.cmd_serve, bzrlib.builtins.cmd_shell_complete, bzrlib.builtins.cmd_shelve, bzrlib.builtins.cmd_split, bzrlib.builtins.cmd_status, bzrlib.builtins.cmd_switch, bzrlib.builtins.cmd_tag, bzrlib.builtins.cmd_tags, bzrlib.builtins.cmd_testament, bzrlib.builtins.cmd_touching_revisions, bzrlib.builtins.cmd_unbind, bzrlib.builtins.cmd_uncommit, bzrlib.builtins.cmd_unknowns, bzrlib.builtins.cmd_unshelve, bzrlib.builtins.cmd_update, bzrlib.builtins.cmd_upgrade, bzrlib.builtins.cmd_version, bzrlib.builtins.cmd_view, bzrlib.builtins.cmd_wait_until_signalled, bzrlib.builtins.cmd_whoami, bzrlib.bundle.commands.cmd_bundle_info, bzrlib.cmd_test_script.cmd_test_script, bzrlib.cmd_version_info.cmd_version_info, bzrlib.commit_signature_commands.cmd_sign_my_commits, bzrlib.commit_signature_commands.cmd_verify_signatures, bzrlib.config.cmd_config, bzrlib.conflicts.cmd_conflicts, bzrlib.conflicts.cmd_resolve, bzrlib.externalcommand.ExternalCommand, bzrlib.foreign.cmd_dpush, bzrlib.plugins.bash_completion.bashcomp.cmd_bash_completion, bzrlib.plugins.launchpad.cmd_launchpad_login, bzrlib.plugins.launchpad.cmd_launchpad_mirror, bzrlib.plugins.launchpad.cmd_launchpad_open, bzrlib.plugins.launchpad.cmd_lp_find_proposal, bzrlib.plugins.launchpad.cmd_lp_propose_merge, bzrlib.plugins.launchpad.cmd_register_branch, bzrlib.tests.blackbox.test_command_encoding.cmd_echo_exact, bzrlib.tests.test_script.cmd_test_confirm

Base class for commands.

Commands are the heart of the command-line bzr interface.

The command object mostly handles the mapping of command-line parameters into one or more bzrlib operations, and of the results into textual output.

Commands normally don't have any state. All their arguments are passed in to the run method. (Subclasses may take a different policy if the behaviour of the instance needs to depend on e.g. a shell plugin and not just its Python class.)

The docstring for an actual command should give a single-line summary, then a complete description of the command. A grammar description will be inserted.

Class VariablesaliasesOther accepted names for this command.
takes_args

List of argument forms, marked with whether they are optional, repeated, etc. Examples:

['to_location', 'from_branch?', 'file*']
  • 'to_location' is required
  • 'from_branch' is optional
  • 'file' can be specified 0 or more times
takes_optionsList of options that may be given for this command. These can be either strings, referring to globally-defined options, or option objects. Retrieve through options().
hiddenIf true, this command isn't advertised. This is typically for commands intended for expert users.
encoding_typeCommand objects will get a 'outf' attribute, which has been setup to properly handle encoding of unicode strings. encoding_type determines what will happen when characters cannot be encoded:

  • strict - abort if we cannot decode
  • replace - put in a bogus character (typically '?')
  • exact - do not encode sys.stdout

NOTE: by default on Windows, sys.stdout is opened as a text stream, therefore LF line-endings are converted to CRLF. When a command uses encoding_type = 'exact', then sys.stdout is forced to be a binary stream, and line-endings will not mangled.

invoked_asA string indicating the real name under which this command was invoked, before expansion of aliases. (This may be None if the command was constructed and run in-process.)
hooksAn instance of CommandHooks.
__doc__

The help shown by 'bzr help command' for this command. This is set by assigning explicitly to __doc__ so that -OO can be used:

class Foo(Command):
    __doc__ = "My help goes here"
Method __init__ Construct an instance of this command.
Method add_cleanup Register a function to call after self.run returns or raises.
Method cleanup_now Execute and empty pending cleanup functions immediately.
Method get_help_text Return a text string with help for this command.
Method get_help_topic Return the commands help topic - its name.
Method get_see_also Return a list of help topics that are related to this command.
Method options Return dict of valid options for this command.
Method run_argv_aliases Parse the command line and run with extra aliases in alias_argv.
Method run Actually run the command.
Method help Return help message for this class.
Method gettext Returns the gettext function used to translate this command's help.
Method name Return the canonical name for this command.
Method plugin_name Get the name of the plugin that provides this command.
Method _usage Return single-line grammar for this command.
Static Method _get_help_parts Split help text into a summary and named sections.
Method _setup_outf Return a file linked to stdout, which has proper encoding.
Method _setup_run Wrap the defined run method on self with a cleanup.
def __init__(self):
Construct an instance of this command.
def add_cleanup(self, cleanup_func, *args, **kwargs):
Register a function to call after self.run returns or raises.

Functions will be called in LIFO order.

def cleanup_now(self):
Execute and empty pending cleanup functions immediately.

After cleanup_now all registered cleanups are forgotten. add_cleanup may be called again after cleanup_now; these cleanups will be called after self.run returns or raises (or when cleanup_now is next called).

This is useful for releasing expensive or contentious resources (such as write locks) before doing further work that does not require those resources (such as writing results to self.outf). Note though, that as it releases all resources, this may release locks that the command wants to hold, so use should be done with care.

def _usage(self):
Return single-line grammar for this command.

Only describes arguments, not options.

def get_help_text(self, additional_see_also=None, plain=True, see_also_as_links=False, verbose=True):
Return a text string with help for this command.
Parametersadditional_see_alsoAdditional help topics to be cross-referenced.
plainif False, raw help (reStructuredText) is returned instead of plain text.
see_also_as_linksif True, convert items in 'See also' list to internal links (used by bzr_man rstx generator)
verboseif True, display the full help, otherwise leave out the descriptive sections and just display usage help (e.g. Purpose, Usage, Options) with a message explaining how to obtain full help.
@staticmethod
def _get_help_parts(text):
Split help text into a summary and named sections.
Returns(summary,sections,order) where summary is the top line and sections is a dictionary of the rest indexed by section name. order is the order the section appear in the text. A section starts with a heading line of the form ":xxx:". Indented text on following lines is the section value. All text found outside a named section is assigned to the default section which is given the key of None.
def get_help_topic(self):
Return the commands help topic - its name.
def get_see_also(self, additional_terms=None):
Return a list of help topics that are related to this command.

The list is derived from the content of the _see_also attribute. Any duplicates are removed and the result is in lexical order. :param additional_terms: Additional help topics to cross-reference. :return: A list of help topics.

def options(self):
Return dict of valid options for this command.

Maps from long option name to option object.

def _setup_outf(self):
Return a file linked to stdout, which has proper encoding.
def run_argv_aliases(self, argv, alias_argv=None):
Parse the command line and run with extra aliases in alias_argv.
def _setup_run(self):
Wrap the defined run method on self with a cleanup.

This is called by __init__ to make the Command be able to be run by just calling run(), as it could be before cleanups were added.

If a different form of cleanups are in use by your Command subclass, you can override this method.

def run(self):
overridden in bzrlib.builtins.cmd_add, bzrlib.builtins.cmd_added, bzrlib.builtins.cmd_alias, bzrlib.builtins.cmd_ancestry, bzrlib.builtins.cmd_annotate, bzrlib.builtins.cmd_assert_fail, bzrlib.builtins.cmd_bind, bzrlib.builtins.cmd_branch, bzrlib.builtins.cmd_branches, bzrlib.builtins.cmd_break_lock, bzrlib.builtins.cmd_cat, bzrlib.builtins.cmd_cat_revision, bzrlib.builtins.cmd_check, bzrlib.builtins.cmd_checkout, bzrlib.builtins.cmd_clean_tree, bzrlib.builtins.cmd_commit, bzrlib.builtins.cmd_deleted, bzrlib.builtins.cmd_diff, bzrlib.builtins.cmd_dump_btree, bzrlib.builtins.cmd_export, bzrlib.builtins.cmd_export_pot, bzrlib.builtins.cmd_file_id, bzrlib.builtins.cmd_file_path, bzrlib.builtins.cmd_find_merge_base, bzrlib.builtins.cmd_help, bzrlib.builtins.cmd_hooks, bzrlib.builtins.cmd_ignore, bzrlib.builtins.cmd_ignored, bzrlib.builtins.cmd_info, bzrlib.builtins.cmd_init, bzrlib.builtins.cmd_init_repository, bzrlib.builtins.cmd_inventory, bzrlib.builtins.cmd_join, bzrlib.builtins.cmd_local_time_offset, bzrlib.builtins.cmd_log, bzrlib.builtins.cmd_lookup_revision, bzrlib.builtins.cmd_ls, bzrlib.builtins.cmd_merge, bzrlib.builtins.cmd_merge_directive, bzrlib.builtins.cmd_missing, bzrlib.builtins.cmd_mkdir, bzrlib.builtins.cmd_modified, bzrlib.builtins.cmd_mv, bzrlib.builtins.cmd_nick, bzrlib.builtins.cmd_pack, bzrlib.builtins.cmd_plugins, bzrlib.builtins.cmd_pull, bzrlib.builtins.cmd_push, bzrlib.builtins.cmd_re_sign, bzrlib.builtins.cmd_reconcile, bzrlib.builtins.cmd_reconfigure, bzrlib.builtins.cmd_reference, bzrlib.builtins.cmd_relpath, bzrlib.builtins.cmd_remerge, bzrlib.builtins.cmd_remove, bzrlib.builtins.cmd_remove_branch, bzrlib.builtins.cmd_remove_tree, bzrlib.builtins.cmd_renames, bzrlib.builtins.cmd_repair_workingtree, bzrlib.builtins.cmd_revert, bzrlib.builtins.cmd_revision_history, bzrlib.builtins.cmd_revision_info, bzrlib.builtins.cmd_revno, bzrlib.builtins.cmd_rocks, bzrlib.builtins.cmd_root, bzrlib.builtins.cmd_selftest, bzrlib.builtins.cmd_send, bzrlib.builtins.cmd_serve, bzrlib.builtins.cmd_shell_complete, bzrlib.builtins.cmd_shelve, bzrlib.builtins.cmd_split, bzrlib.builtins.cmd_status, bzrlib.builtins.cmd_switch, bzrlib.builtins.cmd_tag, bzrlib.builtins.cmd_tags, bzrlib.builtins.cmd_testament, bzrlib.builtins.cmd_touching_revisions, bzrlib.builtins.cmd_unbind, bzrlib.builtins.cmd_uncommit, bzrlib.builtins.cmd_unknowns, bzrlib.builtins.cmd_unshelve, bzrlib.builtins.cmd_update, bzrlib.builtins.cmd_upgrade, bzrlib.builtins.cmd_version, bzrlib.builtins.cmd_view, bzrlib.builtins.cmd_wait_until_signalled, bzrlib.builtins.cmd_whoami, bzrlib.bundle.commands.cmd_bundle_info, bzrlib.cmd_test_script.cmd_test_script, bzrlib.cmd_version_info.cmd_version_info, bzrlib.commit_signature_commands.cmd_sign_my_commits, bzrlib.commit_signature_commands.cmd_verify_signatures, bzrlib.config.cmd_config, bzrlib.conflicts.cmd_conflicts, bzrlib.conflicts.cmd_resolve, bzrlib.externalcommand.ExternalCommand, bzrlib.foreign.cmd_dpush, bzrlib.plugins.bash_completion.bashcomp.cmd_bash_completion, bzrlib.plugins.launchpad.cmd_launchpad_login, bzrlib.plugins.launchpad.cmd_launchpad_mirror, bzrlib.plugins.launchpad.cmd_launchpad_open, bzrlib.plugins.launchpad.cmd_lp_find_proposal, bzrlib.plugins.launchpad.cmd_lp_propose_merge, bzrlib.plugins.launchpad.cmd_register_branch, bzrlib.tests.blackbox.test_command_encoding.cmd_echo_exact, bzrlib.tests.test_script.cmd_test_confirm

Actually run the command.

This is invoked with the options and arguments bound to keyword parameters.

Return 0 or None if the command was successful, or a non-zero shell error code if not. It's OK for this method to allow an exception to raise up.

This method is automatically wrapped by Command.__init__ with a cleanup operation, stored as self._operation. This can be used via self.add_cleanup to perform automatic cleanups at the end of run().

The argument for run are assembled by introspection. So for instance, if your command takes an argument files, you would declare:

def run(self, files=None):
    pass
def help(self):
Return help message for this class.
def gettext(self, message):
Returns the gettext function used to translate this command's help.

Commands provided by plugins should override this to use their own i18n system.

def name(self):
Return the canonical name for this command.

The name under which it was actually invoked is available in invoked_as.

def plugin_name(self):
Get the name of the plugin that provides this command.
ReturnsThe name of the plugin or None if the command is builtin.
API Documentation for Bazaar, generated by pydoctor at 2019-11-22 00:59:21.