help: load module doc of disabled extension in extensions.disabledcmd()

This helps rewriting _finddisablecmd() to not load the module.

mercurial/extensions.py

@@ -1,734 +1,735 b''
 # extensions.py - extension handling for mercurial
 #
 # Copyright 2005-2007 Matt Mackall <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 from __future__ import absolute_import
 
 import functools
 import imp
 import inspect
 import os
 
 from .i18n import (
     _,
     gettext,
 )
 
 from . import (
     cmdutil,
     configitems,
     error,
     pycompat,
     util,
 )
 
 from .utils import (
     stringutil,
 )
 
 _extensions = {}
 _disabledextensions = {}
 _aftercallbacks = {}
 _order = []
 _builtin = {
     'hbisect',
     'bookmarks',
     'color',
     'parentrevspec',
     'progress',
     'interhg',
     'inotify',
     'hgcia'
 }
 
 def extensions(ui=None):
     if ui:
         def enabled(name):
             for format in ['%s', 'hgext.%s']:
                 conf = ui.config('extensions', format % name)
                 if conf is not None and not conf.startswith('!'):
                     return True
     else:
         enabled = lambda name: True
     for name in _order:
         module = _extensions[name]
         if module and enabled(name):
             yield name, module
 
 def find(name):
     '''return module with given extension name'''
     mod = None
     try:
         mod = _extensions[name]
     except KeyError:
         for k, v in _extensions.iteritems():
             if k.endswith('.' + name) or k.endswith('/' + name):
                 mod = v
                 break
     if not mod:
         raise KeyError(name)
     return mod
 
 def loadpath(path, module_name):
     module_name = module_name.replace('.', '_')
     path = util.normpath(util.expandpath(path))
     module_name = pycompat.fsdecode(module_name)
     path = pycompat.fsdecode(path)
     if os.path.isdir(path):
         # module/__init__.py style
         d, f = os.path.split(path)
         fd, fpath, desc = imp.find_module(f, [d])
         return imp.load_module(module_name, fd, fpath, desc)
     else:
         try:
             return imp.load_source(module_name, path)
         except IOError as exc:
             if not exc.filename:
                 exc.filename = path # python does not fill this
             raise
 
 def _importh(name):
     """import and return the <name> module"""
     mod = __import__(pycompat.sysstr(name))
     components = name.split('.')
     for comp in components[1:]:
         mod = getattr(mod, comp)
     return mod
 
 def _importext(name, path=None, reportfunc=None):
     if path:
         # the module will be loaded in sys.modules
         # choose an unique name so that it doesn't
         # conflicts with other modules
         mod = loadpath(path, 'hgext.%s' % name)
     else:
         try:
             mod = _importh("hgext.%s" % name)
         except ImportError as err:
             if reportfunc:
                 reportfunc(err, "hgext.%s" % name, "hgext3rd.%s" % name)
             try:
                 mod = _importh("hgext3rd.%s" % name)
             except ImportError as err:
                 if reportfunc:
                     reportfunc(err, "hgext3rd.%s" % name, name)
                 mod = _importh(name)
     return mod
 
 def _reportimporterror(ui, err, failed, next):
     # note: this ui.debug happens before --debug is processed,
     #       Use --config ui.debug=1 to see them.
     ui.debug('could not import %s (%s): trying %s\n'
              % (failed, stringutil.forcebytestr(err), next))
     if ui.debugflag:
         ui.traceback()
 
 def _rejectunicode(name, xs):
     if isinstance(xs, (list, set, tuple)):
         for x in xs:
             _rejectunicode(name, x)
     elif isinstance(xs, dict):
         for k, v in xs.items():
             _rejectunicode(name, k)
             _rejectunicode(b'%s.%s' % (name, stringutil.forcebytestr(k)), v)
     elif isinstance(xs, type(u'')):
         raise error.ProgrammingError(b"unicode %r found in %s" % (xs, name),
                                      hint="use b'' to make it byte string")
 
 # attributes set by registrar.command
 _cmdfuncattrs = ('norepo', 'optionalrepo', 'inferrepo')
 
 def _validatecmdtable(ui, cmdtable):
     """Check if extension commands have required attributes"""
     for c, e in cmdtable.iteritems():
         f = e[0]
         missing = [a for a in _cmdfuncattrs if not util.safehasattr(f, a)]
         if not missing:
             continue
         raise error.ProgrammingError(
             'missing attributes: %s' % ', '.join(missing),
             hint="use @command decorator to register '%s'" % c)
 
 def _validatetables(ui, mod):
     """Sanity check for loadable tables provided by extension module"""
     for t in ['cmdtable', 'colortable', 'configtable']:
         _rejectunicode(t, getattr(mod, t, {}))
     for t in ['filesetpredicate', 'internalmerge', 'revsetpredicate',
               'templatefilter', 'templatefunc', 'templatekeyword']:
         o = getattr(mod, t, None)
         if o:
             _rejectunicode(t, o._table)
     _validatecmdtable(ui, getattr(mod, 'cmdtable', {}))
 
 def load(ui, name, path):
     if name.startswith('hgext.') or name.startswith('hgext/'):
         shortname = name[6:]
     else:
         shortname = name
     if shortname in _builtin:
         return None
     if shortname in _extensions:
         return _extensions[shortname]
     _extensions[shortname] = None
     mod = _importext(name, path, bind(_reportimporterror, ui))
 
     # Before we do anything with the extension, check against minimum stated
     # compatibility. This gives extension authors a mechanism to have their
     # extensions short circuit when loaded with a known incompatible version
     # of Mercurial.
     minver = getattr(mod, 'minimumhgversion', None)
     if minver and util.versiontuple(minver, 2) > util.versiontuple(n=2):
         ui.warn(_('(third party extension %s requires version %s or newer '
                   'of Mercurial; disabling)\n') % (shortname, minver))
         return
     _validatetables(ui, mod)
 
     _extensions[shortname] = mod
     _order.append(shortname)
     for fn in _aftercallbacks.get(shortname, []):
         fn(loaded=True)
     return mod
 
 def _runuisetup(name, ui):
     uisetup = getattr(_extensions[name], 'uisetup', None)
     if uisetup:
         try:
             uisetup(ui)
         except Exception as inst:
             ui.traceback(force=True)
             msg = stringutil.forcebytestr(inst)
             ui.warn(_("*** failed to set up extension %s: %s\n") % (name, msg))
             return False
     return True
 
 def _runextsetup(name, ui):
     extsetup = getattr(_extensions[name], 'extsetup', None)
     if extsetup:
         try:
             try:
                 extsetup(ui)
             except TypeError:
                 if pycompat.getargspec(extsetup).args:
                     raise
                 extsetup() # old extsetup with no ui argument
         except Exception as inst:
             ui.traceback(force=True)
             msg = stringutil.forcebytestr(inst)
             ui.warn(_("*** failed to set up extension %s: %s\n") % (name, msg))
             return False
     return True
 
 def loadall(ui, whitelist=None):
     result = ui.configitems("extensions")
     if whitelist is not None:
         result = [(k, v) for (k, v) in result if k in whitelist]
     newindex = len(_order)
     for (name, path) in result:
         if path:
             if path[0:1] == '!':
                 _disabledextensions[name] = path[1:]
                 continue
         try:
             load(ui, name, path)
         except Exception as inst:
             msg = stringutil.forcebytestr(inst)
             if path:
                 ui.warn(_("*** failed to import extension %s from %s: %s\n")
                         % (name, path, msg))
             else:
                 ui.warn(_("*** failed to import extension %s: %s\n")
                         % (name, msg))
             if isinstance(inst, error.Hint) and inst.hint:
                 ui.warn(_("*** (%s)\n") % inst.hint)
             ui.traceback()
     # list of (objname, loadermod, loadername) tuple:
     # - objname is the name of an object in extension module,
     #   from which extra information is loaded
     # - loadermod is the module where loader is placed
     # - loadername is the name of the function,
     #   which takes (ui, extensionname, extraobj) arguments
     #
     # This one is for the list of item that must be run before running any setup
     earlyextraloaders = [
         ('configtable', configitems, 'loadconfigtable'),
     ]
     _loadextra(ui, newindex, earlyextraloaders)
 
     broken = set()
     for name in _order[newindex:]:
         if not _runuisetup(name, ui):
             broken.add(name)
 
     for name in _order[newindex:]:
         if name in broken:
             continue
         if not _runextsetup(name, ui):
             broken.add(name)
 
     for name in broken:
         _extensions[name] = None
 
     # Call aftercallbacks that were never met.
     for shortname in _aftercallbacks:
         if shortname in _extensions:
             continue
 
         for fn in _aftercallbacks[shortname]:
             fn(loaded=False)
 
     # loadall() is called multiple times and lingering _aftercallbacks
     # entries could result in double execution. See issue4646.
     _aftercallbacks.clear()
 
     # delay importing avoids cyclic dependency (especially commands)
     from . import (
         color,
         commands,
         filemerge,
         fileset,
         revset,
         templatefilters,
         templatefuncs,
         templatekw,
     )
 
     # list of (objname, loadermod, loadername) tuple:
     # - objname is the name of an object in extension module,
     #   from which extra information is loaded
     # - loadermod is the module where loader is placed
     # - loadername is the name of the function,
     #   which takes (ui, extensionname, extraobj) arguments
     extraloaders = [
         ('cmdtable', commands, 'loadcmdtable'),
         ('colortable', color, 'loadcolortable'),
         ('filesetpredicate', fileset, 'loadpredicate'),
         ('internalmerge', filemerge, 'loadinternalmerge'),
         ('revsetpredicate', revset, 'loadpredicate'),
         ('templatefilter', templatefilters, 'loadfilter'),
         ('templatefunc', templatefuncs, 'loadfunction'),
         ('templatekeyword', templatekw, 'loadkeyword'),
     ]
     _loadextra(ui, newindex, extraloaders)
 
 def _loadextra(ui, newindex, extraloaders):
     for name in _order[newindex:]:
         module = _extensions[name]
         if not module:
             continue # loading this module failed
 
         for objname, loadermod, loadername in extraloaders:
             extraobj = getattr(module, objname, None)
             if extraobj is not None:
                 getattr(loadermod, loadername)(ui, name, extraobj)
 
 def afterloaded(extension, callback):
     '''Run the specified function after a named extension is loaded.
 
     If the named extension is already loaded, the callback will be called
     immediately.
 
     If the named extension never loads, the callback will be called after
     all extensions have been loaded.
 
     The callback receives the named argument ``loaded``, which is a boolean
     indicating whether the dependent extension actually loaded.
     '''
 
     if extension in _extensions:
         # Report loaded as False if the extension is disabled
         loaded = (_extensions[extension] is not None)
         callback(loaded=loaded)
     else:
         _aftercallbacks.setdefault(extension, []).append(callback)
 
 def bind(func, *args):
     '''Partial function application
 
       Returns a new function that is the partial application of args and kwargs
       to func.  For example,
 
           f(1, 2, bar=3) === bind(f, 1)(2, bar=3)'''
     assert callable(func)
     def closure(*a, **kw):
         return func(*(args + a), **kw)
     return closure
 
 def _updatewrapper(wrap, origfn, unboundwrapper):
     '''Copy and add some useful attributes to wrapper'''
     try:
         wrap.__name__ = origfn.__name__
     except AttributeError:
         pass
     wrap.__module__ = getattr(origfn, '__module__')
     wrap.__doc__ = getattr(origfn, '__doc__')
     wrap.__dict__.update(getattr(origfn, '__dict__', {}))
     wrap._origfunc = origfn
     wrap._unboundwrapper = unboundwrapper
 
 def wrapcommand(table, command, wrapper, synopsis=None, docstring=None):
     '''Wrap the command named `command' in table
 
     Replace command in the command table with wrapper. The wrapped command will
     be inserted into the command table specified by the table argument.
 
     The wrapper will be called like
 
       wrapper(orig, *args, **kwargs)
 
     where orig is the original (wrapped) function, and *args, **kwargs
     are the arguments passed to it.
 
     Optionally append to the command synopsis and docstring, used for help.
     For example, if your extension wraps the ``bookmarks`` command to add the
     flags ``--remote`` and ``--all`` you might call this function like so:
 
       synopsis = ' [-a] [--remote]'
       docstring = """
 
       The ``remotenames`` extension adds the ``--remote`` and ``--all`` (``-a``)
       flags to the bookmarks command. Either flag will show the remote bookmarks
       known to the repository; ``--remote`` will also suppress the output of the
       local bookmarks.
       """
 
       extensions.wrapcommand(commands.table, 'bookmarks', exbookmarks,
                              synopsis, docstring)
     '''
     assert callable(wrapper)
     aliases, entry = cmdutil.findcmd(command, table)
     for alias, e in table.iteritems():
         if e is entry:
             key = alias
             break
 
     origfn = entry[0]
     wrap = functools.partial(util.checksignature(wrapper),
                              util.checksignature(origfn))
     _updatewrapper(wrap, origfn, wrapper)
     if docstring is not None:
         wrap.__doc__ += docstring
 
     newentry = list(entry)
     newentry[0] = wrap
     if synopsis is not None:
         newentry[2] += synopsis
     table[key] = tuple(newentry)
     return entry
 
 def wrapfilecache(cls, propname, wrapper):
     """Wraps a filecache property.
 
     These can't be wrapped using the normal wrapfunction.
     """
     propname = pycompat.sysstr(propname)
     assert callable(wrapper)
     for currcls in cls.__mro__:
         if propname in currcls.__dict__:
             origfn = currcls.__dict__[propname].func
             assert callable(origfn)
             def wrap(*args, **kwargs):
                 return wrapper(origfn, *args, **kwargs)
             currcls.__dict__[propname].func = wrap
             break
 
     if currcls is object:
         raise AttributeError(r"type '%s' has no property '%s'" % (
             cls, propname))
 
 class wrappedfunction(object):
     '''context manager for temporarily wrapping a function'''
 
     def __init__(self, container, funcname, wrapper):
         assert callable(wrapper)
         self._container = container
         self._funcname = funcname
         self._wrapper = wrapper
 
     def __enter__(self):
         wrapfunction(self._container, self._funcname, self._wrapper)
 
     def __exit__(self, exctype, excvalue, traceback):
         unwrapfunction(self._container, self._funcname, self._wrapper)
 
 def wrapfunction(container, funcname, wrapper):
     '''Wrap the function named funcname in container
 
     Replace the funcname member in the given container with the specified
     wrapper. The container is typically a module, class, or instance.
 
     The wrapper will be called like
 
       wrapper(orig, *args, **kwargs)
 
     where orig is the original (wrapped) function, and *args, **kwargs
     are the arguments passed to it.
 
     Wrapping methods of the repository object is not recommended since
     it conflicts with extensions that extend the repository by
     subclassing. All extensions that need to extend methods of
     localrepository should use this subclassing trick: namely,
     reposetup() should look like
 
       def reposetup(ui, repo):
           class myrepo(repo.__class__):
               def whatever(self, *args, **kwargs):
                   [...extension stuff...]
                   super(myrepo, self).whatever(*args, **kwargs)
                   [...extension stuff...]
 
           repo.__class__ = myrepo
 
     In general, combining wrapfunction() with subclassing does not
     work. Since you cannot control what other extensions are loaded by
     your end users, you should play nicely with others by using the
     subclass trick.
     '''
     assert callable(wrapper)
 
     origfn = getattr(container, funcname)
     assert callable(origfn)
     if inspect.ismodule(container):
         # origfn is not an instance or class method. "partial" can be used.
         # "partial" won't insert a frame in traceback.
         wrap = functools.partial(wrapper, origfn)
     else:
         # "partial" cannot be safely used. Emulate its effect by using "bind".
         # The downside is one more frame in traceback.
         wrap = bind(wrapper, origfn)
     _updatewrapper(wrap, origfn, wrapper)
     setattr(container, funcname, wrap)
     return origfn
 
 def unwrapfunction(container, funcname, wrapper=None):
     '''undo wrapfunction
 
     If wrappers is None, undo the last wrap. Otherwise removes the wrapper
     from the chain of wrappers.
 
     Return the removed wrapper.
     Raise IndexError if wrapper is None and nothing to unwrap; ValueError if
     wrapper is not None but is not found in the wrapper chain.
     '''
     chain = getwrapperchain(container, funcname)
     origfn = chain.pop()
     if wrapper is None:
         wrapper = chain[0]
     chain.remove(wrapper)
     setattr(container, funcname, origfn)
     for w in reversed(chain):
         wrapfunction(container, funcname, w)
     return wrapper
 
 def getwrapperchain(container, funcname):
     '''get a chain of wrappers of a function
 
     Return a list of functions: [newest wrapper, ..., oldest wrapper, origfunc]
 
     The wrapper functions are the ones passed to wrapfunction, whose first
     argument is origfunc.
     '''
     result = []
     fn = getattr(container, funcname)
     while fn:
         assert callable(fn)
         result.append(getattr(fn, '_unboundwrapper', fn))
         fn = getattr(fn, '_origfunc', None)
     return result
 
 def _disabledpaths(strip_init=False):
     '''find paths of disabled extensions. returns a dict of {name: path}
     removes /__init__.py from packages if strip_init is True'''
     import hgext
     extpath = os.path.dirname(
         os.path.abspath(pycompat.fsencode(hgext.__file__)))
     try: # might not be a filesystem path
         files = os.listdir(extpath)
     except OSError:
         return {}
 
     exts = {}
     for e in files:
         if e.endswith('.py'):
             name = e.rsplit('.', 1)[0]
             path = os.path.join(extpath, e)
         else:
             name = e
             path = os.path.join(extpath, e, '__init__.py')
             if not os.path.exists(path):
                 continue
             if strip_init:
                 path = os.path.dirname(path)
         if name in exts or name in _order or name == '__init__':
             continue
         exts[name] = path
     for name, path in _disabledextensions.iteritems():
         # If no path was provided for a disabled extension (e.g. "color=!"),
         # don't replace the path we already found by the scan above.
         if path:
             exts[name] = path
     return exts
 
 def _moduledoc(file):
     '''return the top-level python documentation for the given file
 
     Loosely inspired by pydoc.source_synopsis(), but rewritten to
     handle triple quotes and to return the whole text instead of just
     the synopsis'''
     result = []
 
     line = file.readline()
     while line[:1] == '#' or not line.strip():
         line = file.readline()
         if not line:
             break
 
     start = line[:3]
     if start == '"""' or start == "'''":
         line = line[3:]
         while line:
             if line.rstrip().endswith(start):
                 line = line.split(start)[0]
                 if line:
                     result.append(line)
                 break
             elif not line:
                 return None # unmatched delimiter
             result.append(line)
             line = file.readline()
     else:
         return None
 
     return ''.join(result)
 
 def _disabledhelp(path):
     '''retrieve help synopsis of a disabled extension (without importing)'''
     try:
         file = open(path)
     except IOError:
         return
     else:
         doc = _moduledoc(file)
         file.close()
 
     if doc: # extracting localized synopsis
         return gettext(doc)
     else:
         return _('(no help text available)')
 
 def disabled():
     '''find disabled extensions from hgext. returns a dict of {name: desc}'''
     try:
         from hgext import __index__
         return dict((name, gettext(desc))
                     for name, desc in __index__.docs.iteritems()
                     if name not in _order)
     except (ImportError, AttributeError):
         pass
 
     paths = _disabledpaths()
     if not paths:
         return {}
 
     exts = {}
     for name, path in paths.iteritems():
         doc = _disabledhelp(path)
         if doc:
             exts[name] = doc.splitlines()[0]
 
     return exts
 
 def disabledext(name):
     '''find a specific disabled extension from hgext. returns desc'''
     try:
         from hgext import __index__
         if name in _order:  # enabled
             return
         else:
             return gettext(__index__.docs.get(name))
     except (ImportError, AttributeError):
         pass
 
     paths = _disabledpaths()
     if name in paths:
         return _disabledhelp(paths[name])
 
 def _finddisabledcmd(ui, cmd, name, path, strict):
     try:
         mod = loadpath(path, 'hgext.%s' % name)
     except Exception:
         return
     try:
         aliases, entry = cmdutil.findcmd(cmd,
             getattr(mod, 'cmdtable', {}), strict)
     except (error.AmbiguousCommand, error.UnknownCommand):
         return
     except Exception:
         ui.warn(_('warning: error finding commands in %s\n') % path)
         ui.traceback()
         return
     for c in aliases:
         if c.startswith(cmd):
             cmd = c
             break
     else:
         cmd = aliases[0]
-    return (cmd, name, mod)
+    doc = gettext(pycompat.getdoc(mod))
+    return (cmd, name, doc)
 
 def disabledcmd(ui, cmd, strict=False):
     '''import disabled extensions until cmd is found.
-    returns (cmdname, extname, module)'''
+    returns (cmdname, extname, doc)'''
 
     paths = _disabledpaths(strip_init=True)
     if not paths:
         raise error.UnknownCommand(cmd)
 
     ext = None
     # first, search for an extension with the same name as the command
     path = paths.pop(cmd, None)
     if path:
         ext = _finddisabledcmd(ui, cmd, cmd, path, strict=strict)
     if not ext:
         # otherwise, interrogate each extension until there's a match
         for name, path in paths.iteritems():
             ext = _finddisabledcmd(ui, cmd, name, path, strict=strict)
             if ext:
                 break
     if ext:
         return ext
 
     raise error.UnknownCommand(cmd)
 
 def enabled(shortname=True):
     '''return a dict of {name: desc} of extensions'''
     exts = {}
     for ename, ext in extensions():
         doc = (gettext(ext.__doc__) or _('(no help text available)'))
         if shortname:
             ename = ename.split('.')[-1]
         exts[ename] = doc.splitlines()[0].strip()
 
     return exts
 
 def notloaded():
     '''return short names of extensions that failed to load'''
     return [name for name, mod in _extensions.iteritems() if mod is None]
 
 def moduleversion(module):
     '''return version information from given module as a string'''
     if (util.safehasattr(module, 'getversion')
           and callable(module.getversion)):
         version = module.getversion()
     elif util.safehasattr(module, '__version__'):
         version = module.__version__
     else:
         version = ''
     if isinstance(version, (list, tuple)):
         version = '.'.join(str(o) for o in version)
     return version
 
 def ismoduleinternal(module):
     exttestedwith = getattr(module, 'testedwith', None)
     return exttestedwith == "ships-with-hg-core"

mercurial/help.py

@@ -1,689 +1,689 b''
 # help.py - help data for mercurial
 #
 # Copyright 2006 Matt Mackall <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 from __future__ import absolute_import
 
 import itertools
 import os
 import textwrap
 
 from .i18n import (
     _,
     gettext,
 )
 from . import (
     cmdutil,
     encoding,
     error,
     extensions,
     fancyopts,
     filemerge,
     fileset,
     minirst,
     pycompat,
     revset,
     templatefilters,
     templatefuncs,
     templatekw,
     util,
 )
 from .hgweb import (
     webcommands,
 )
 
 _exclkeywords = {
     "(ADVANCED)",
     "(DEPRECATED)",
     "(EXPERIMENTAL)",
     # i18n: "(ADVANCED)" is a keyword, must be translated consistently
     _("(ADVANCED)"),
     # i18n: "(DEPRECATED)" is a keyword, must be translated consistently
     _("(DEPRECATED)"),
     # i18n: "(EXPERIMENTAL)" is a keyword, must be translated consistently
     _("(EXPERIMENTAL)"),
 }
 
 def listexts(header, exts, indent=1, showdeprecated=False):
     '''return a text listing of the given extensions'''
     rst = []
     if exts:
         for name, desc in sorted(exts.iteritems()):
             if not showdeprecated and any(w in desc for w in _exclkeywords):
                 continue
             rst.append('%s:%s: %s\n' % (' ' * indent, name, desc))
     if rst:
         rst.insert(0, '\n%s\n\n' % header)
     return rst
 
 def extshelp(ui):
     rst = loaddoc('extensions')(ui).splitlines(True)
     rst.extend(listexts(
         _('enabled extensions:'), extensions.enabled(), showdeprecated=True))
     rst.extend(listexts(_('disabled extensions:'), extensions.disabled(),
                         showdeprecated=ui.verbose))
     doc = ''.join(rst)
     return doc
 
 def optrst(header, options, verbose):
     data = []
     multioccur = False
     for option in options:
         if len(option) == 5:
             shortopt, longopt, default, desc, optlabel = option
         else:
             shortopt, longopt, default, desc = option
             optlabel = _("VALUE") # default label
 
         if not verbose and any(w in desc for w in _exclkeywords):
             continue
 
         so = ''
         if shortopt:
             so = '-' + shortopt
         lo = '--' + longopt
 
         if isinstance(default, fancyopts.customopt):
             default = default.getdefaultvalue()
         if default and not callable(default):
             # default is of unknown type, and in Python 2 we abused
             # the %s-shows-repr property to handle integers etc. To
             # match that behavior on Python 3, we do str(default) and
             # then convert it to bytes.
             desc += _(" (default: %s)") % pycompat.bytestr(default)
 
         if isinstance(default, list):
             lo += " %s [+]" % optlabel
             multioccur = True
         elif (default is not None) and not isinstance(default, bool):
             lo += " %s" % optlabel
 
         data.append((so, lo, desc))
 
     if multioccur:
         header += (_(" ([+] can be repeated)"))
 
     rst = ['\n%s:\n\n' % header]
     rst.extend(minirst.maketable(data, 1))
 
     return ''.join(rst)
 
 def indicateomitted(rst, omitted, notomitted=None):
     rst.append('\n\n.. container:: omitted\n\n    %s\n\n' % omitted)
     if notomitted:
         rst.append('\n\n.. container:: notomitted\n\n    %s\n\n' % notomitted)
 
 def filtercmd(ui, cmd, kw, doc):
     if not ui.debugflag and cmd.startswith("debug") and kw != "debug":
         return True
     if not ui.verbose and doc and any(w in doc for w in _exclkeywords):
         return True
     return False
 
 def topicmatch(ui, commands, kw):
     """Return help topics matching kw.
 
     Returns {'section': [(name, summary), ...], ...} where section is
     one of topics, commands, extensions, or extensioncommands.
     """
     kw = encoding.lower(kw)
     def lowercontains(container):
         return kw in encoding.lower(container)  # translated in helptable
     results = {'topics': [],
                'commands': [],
                'extensions': [],
                'extensioncommands': [],
                }
     for names, header, doc in helptable:
         # Old extensions may use a str as doc.
         if (sum(map(lowercontains, names))
             or lowercontains(header)
             or (callable(doc) and lowercontains(doc(ui)))):
             results['topics'].append((names[0], header))
     for cmd, entry in commands.table.iteritems():
         if len(entry) == 3:
             summary = entry[2]
         else:
             summary = ''
         # translate docs *before* searching there
         docs = _(pycompat.getdoc(entry[0])) or ''
         if kw in cmd or lowercontains(summary) or lowercontains(docs):
             doclines = docs.splitlines()
             if doclines:
                 summary = doclines[0]
             cmdname = cmdutil.parsealiases(cmd)[0]
             if filtercmd(ui, cmdname, kw, docs):
                 continue
             results['commands'].append((cmdname, summary))
     for name, docs in itertools.chain(
         extensions.enabled(False).iteritems(),
         extensions.disabled().iteritems()):
         if not docs:
             continue
         name = name.rpartition('.')[-1]
         if lowercontains(name) or lowercontains(docs):
             # extension docs are already translated
             results['extensions'].append((name, docs.splitlines()[0]))
         try:
             mod = extensions.load(ui, name, '')
         except ImportError:
             # debug message would be printed in extensions.load()
             continue
         for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems():
             if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])):
                 cmdname = cmdutil.parsealiases(cmd)[0]
                 cmddoc = pycompat.getdoc(entry[0])
                 if cmddoc:
                     cmddoc = gettext(cmddoc).splitlines()[0]
                 else:
                     cmddoc = _('(no help text available)')
                 if filtercmd(ui, cmdname, kw, cmddoc):
                     continue
                 results['extensioncommands'].append((cmdname, cmddoc))
     return results
 
 def loaddoc(topic, subdir=None):
     """Return a delayed loader for help/topic.txt."""
 
     def loader(ui):
         docdir = os.path.join(util.datapath, 'help')
         if subdir:
             docdir = os.path.join(docdir, subdir)
         path = os.path.join(docdir, topic + ".txt")
         doc = gettext(util.readfile(path))
         for rewriter in helphooks.get(topic, []):
             doc = rewriter(ui, topic, doc)
         return doc
 
     return loader
 
 internalstable = sorted([
     (['bundle2'], _('Bundle2'),
      loaddoc('bundle2', subdir='internals')),
     (['bundles'], _('Bundles'),
      loaddoc('bundles', subdir='internals')),
     (['censor'], _('Censor'),
      loaddoc('censor', subdir='internals')),
     (['changegroups'], _('Changegroups'),
      loaddoc('changegroups', subdir='internals')),
     (['config'], _('Config Registrar'),
      loaddoc('config', subdir='internals')),
     (['requirements'], _('Repository Requirements'),
      loaddoc('requirements', subdir='internals')),
     (['revlogs'], _('Revision Logs'),
      loaddoc('revlogs', subdir='internals')),
     (['wireprotocol'], _('Wire Protocol'),
      loaddoc('wireprotocol', subdir='internals')),
 ])
 
 def internalshelp(ui):
     """Generate the index for the "internals" topic."""
     lines = ['To access a subtopic, use "hg help internals.{subtopic-name}"\n',
              '\n']
     for names, header, doc in internalstable:
         lines.append(' :%s: %s\n' % (names[0], header))
 
     return ''.join(lines)
 
 helptable = sorted([
     (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')),
     (['color'], _("Colorizing Outputs"), loaddoc('color')),
     (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
     (["dates"], _("Date Formats"), loaddoc('dates')),
     (["flags"], _("Command-line flags"), loaddoc('flags')),
     (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
     (['environment', 'env'], _('Environment Variables'),
      loaddoc('environment')),
     (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
       _('Specifying Revisions'), loaddoc('revisions')),
     (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')),
     (['diffs'], _('Diff Formats'), loaddoc('diffs')),
     (['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),
      loaddoc('merge-tools')),
     (['templating', 'templates', 'template', 'style'], _('Template Usage'),
      loaddoc('templates')),
     (['urls'], _('URL Paths'), loaddoc('urls')),
     (["extensions"], _("Using Additional Features"), extshelp),
     (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')),
     (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
     (["glossary"], _("Glossary"), loaddoc('glossary')),
     (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
      loaddoc('hgignore')),
     (["phases"], _("Working with Phases"), loaddoc('phases')),
     (['scripting'], _('Using Mercurial from scripts and automation'),
      loaddoc('scripting')),
     (['internals'], _("Technical implementation topics"),
      internalshelp),
     (['pager'], _("Pager Support"), loaddoc('pager')),
 ])
 
 # Maps topics with sub-topics to a list of their sub-topics.
 subtopics = {
     'internals': internalstable,
 }
 
 # Map topics to lists of callable taking the current topic help and
 # returning the updated version
 helphooks = {}
 
 def addtopichook(topic, rewriter):
     helphooks.setdefault(topic, []).append(rewriter)
 
 def makeitemsdoc(ui, topic, doc, marker, items, dedent=False):
     """Extract docstring from the items key to function mapping, build a
     single documentation block and use it to overwrite the marker in doc.
     """
     entries = []
     for name in sorted(items):
         text = (pycompat.getdoc(items[name]) or '').rstrip()
         if (not text
             or not ui.verbose and any(w in text for w in _exclkeywords)):
             continue
         text = gettext(text)
         if dedent:
             # Abuse latin1 to use textwrap.dedent() on bytes.
             text = textwrap.dedent(text.decode('latin1')).encode('latin1')
         lines = text.splitlines()
         doclines = [(lines[0])]
         for l in lines[1:]:
             # Stop once we find some Python doctest
             if l.strip().startswith('>>>'):
                 break
             if dedent:
                 doclines.append(l.rstrip())
             else:
                 doclines.append('  ' + l.strip())
         entries.append('\n'.join(doclines))
     entries = '\n\n'.join(entries)
     return doc.replace(marker, entries)
 
 def addtopicsymbols(topic, marker, symbols, dedent=False):
     def add(ui, topic, doc):
         return makeitemsdoc(ui, topic, doc, marker, symbols, dedent=dedent)
     addtopichook(topic, add)
 
 addtopicsymbols('bundlespec', '.. bundlecompressionmarker',
                 util.bundlecompressiontopics())
 addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
 addtopicsymbols('merge-tools', '.. internaltoolsmarker',
                 filemerge.internalsdoc)
 addtopicsymbols('revisions', '.. predicatesmarker', revset.symbols)
 addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
 addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
 addtopicsymbols('templates', '.. functionsmarker', templatefuncs.funcs)
 addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands,
                 dedent=True)
 
 def help_(ui, commands, name, unknowncmd=False, full=True, subtopic=None,
           **opts):
     '''
     Generate the help for 'name' as unformatted restructured text. If
     'name' is None, describe the commands available.
     '''
 
     opts = pycompat.byteskwargs(opts)
 
     def helpcmd(name, subtopic=None):
         try:
             aliases, entry = cmdutil.findcmd(name, commands.table,
                                              strict=unknowncmd)
         except error.AmbiguousCommand as inst:
             # py3k fix: except vars can't be used outside the scope of the
             # except block, nor can be used inside a lambda. python issue4617
             prefix = inst.args[0]
             select = lambda c: cmdutil.parsealiases(c)[0].startswith(prefix)
             rst = helplist(select)
             return rst
 
         rst = []
 
         # check if it's an invalid alias and display its error if it is
         if getattr(entry[0], 'badalias', None):
             rst.append(entry[0].badalias + '\n')
             if entry[0].unknowncmd:
                 try:
                     rst.extend(helpextcmd(entry[0].cmdname))
                 except error.UnknownCommand:
                     pass
             return rst
 
         # synopsis
         if len(entry) > 2:
             if entry[2].startswith('hg'):
                 rst.append("%s\n" % entry[2])
             else:
                 rst.append('hg %s %s\n' % (aliases[0], entry[2]))
         else:
             rst.append('hg %s\n' % aliases[0])
         # aliases
         if full and not ui.quiet and len(aliases) > 1:
             rst.append(_("\naliases: %s\n") % ', '.join(aliases[1:]))
         rst.append('\n')
 
         # description
         doc = gettext(pycompat.getdoc(entry[0]))
         if not doc:
             doc = _("(no help text available)")
         if util.safehasattr(entry[0], 'definition'):  # aliased command
             source = entry[0].source
             if entry[0].definition.startswith('!'):  # shell alias
                 doc = (_('shell alias for: %s\n\n%s\n\ndefined by: %s\n') %
                        (entry[0].definition[1:], doc, source))
             else:
                 doc = (_('alias for: hg %s\n\n%s\n\ndefined by: %s\n') %
                        (entry[0].definition, doc, source))
         doc = doc.splitlines(True)
         if ui.quiet or not full:
             rst.append(doc[0])
         else:
             rst.extend(doc)
         rst.append('\n')
 
         # check if this command shadows a non-trivial (multi-line)
         # extension help text
         try:
             mod = extensions.find(name)
             doc = gettext(pycompat.getdoc(mod)) or ''
             if '\n' in doc.strip():
                 msg = _("(use 'hg help -e %s' to show help for "
                         "the %s extension)") % (name, name)
                 rst.append('\n%s\n' % msg)
         except KeyError:
             pass
 
         # options
         if not ui.quiet and entry[1]:
             rst.append(optrst(_("options"), entry[1], ui.verbose))
 
         if ui.verbose:
             rst.append(optrst(_("global options"),
                               commands.globalopts, ui.verbose))
 
         if not ui.verbose:
             if not full:
                 rst.append(_("\n(use 'hg %s -h' to show more help)\n")
                            % name)
             elif not ui.quiet:
                 rst.append(_('\n(some details hidden, use --verbose '
                                'to show complete help)'))
 
         return rst
 
 
     def helplist(select=None, **opts):
         # list of commands
         if name == "shortlist":
             header = _('basic commands:\n\n')
         elif name == "debug":
             header = _('debug commands (internal and unsupported):\n\n')
         else:
             header = _('list of commands:\n\n')
 
         h = {}
         cmds = {}
         for c, e in commands.table.iteritems():
             fs = cmdutil.parsealiases(c)
             f = fs[0]
             p = ''
             if c.startswith("^"):
                 p = '^'
             if select and not select(p + f):
                 continue
             if (not select and name != 'shortlist' and
                 e[0].__module__ != commands.__name__):
                 continue
             if name == "shortlist" and not p:
                 continue
             doc = pycompat.getdoc(e[0])
             if filtercmd(ui, f, name, doc):
                 continue
             doc = gettext(doc)
             if not doc:
                 doc = _("(no help text available)")
             h[f] = doc.splitlines()[0].rstrip()
             cmds[f] = '|'.join(fs)
 
         rst = []
         if not h:
             if not ui.quiet:
                 rst.append(_('no commands defined\n'))
             return rst
 
         if not ui.quiet:
             rst.append(header)
         fns = sorted(h)
         for f in fns:
             if ui.verbose:
                 commacmds = cmds[f].replace("|",", ")
                 rst.append(" :%s: %s\n" % (commacmds, h[f]))
             else:
                 rst.append(' :%s: %s\n' % (f, h[f]))
 
         ex = opts.get
         anyopts = (ex(r'keyword') or not (ex(r'command') or ex(r'extension')))
         if not name and anyopts:
             exts = listexts(_('enabled extensions:'), extensions.enabled())
             if exts:
                 rst.append('\n')
                 rst.extend(exts)
 
             rst.append(_("\nadditional help topics:\n\n"))
             topics = []
             for names, header, doc in helptable:
                 topics.append((names[0], header))
             for t, desc in topics:
                 rst.append(" :%s: %s\n" % (t, desc))
 
         if ui.quiet:
             pass
         elif ui.verbose:
             rst.append('\n%s\n' % optrst(_("global options"),
                                          commands.globalopts, ui.verbose))
             if name == 'shortlist':
                 rst.append(_("\n(use 'hg help' for the full list "
                              "of commands)\n"))
         else:
             if name == 'shortlist':
                 rst.append(_("\n(use 'hg help' for the full list of commands "
                              "or 'hg -v' for details)\n"))
             elif name and not full:
                 rst.append(_("\n(use 'hg help %s' to show the full help "
                              "text)\n") % name)
             elif name and cmds and name in cmds.keys():
                 rst.append(_("\n(use 'hg help -v -e %s' to show built-in "
                              "aliases and global options)\n") % name)
             else:
                 rst.append(_("\n(use 'hg help -v%s' to show built-in aliases "
                              "and global options)\n")
                            % (name and " " + name or ""))
         return rst
 
     def helptopic(name, subtopic=None):
         # Look for sub-topic entry first.
         header, doc = None, None
         if subtopic and name in subtopics:
             for names, header, doc in subtopics[name]:
                 if subtopic in names:
                     break
 
         if not header:
             for names, header, doc in helptable:
                 if name in names:
                     break
             else:
                 raise error.UnknownCommand(name)
 
         rst = [minirst.section(header)]
 
         # description
         if not doc:
             rst.append("    %s\n" % _("(no help text available)"))
         if callable(doc):
             rst += ["    %s\n" % l for l in doc(ui).splitlines()]
 
         if not ui.verbose:
             omitted = _('(some details hidden, use --verbose'
                          ' to show complete help)')
             indicateomitted(rst, omitted)
 
         try:
             cmdutil.findcmd(name, commands.table)
             rst.append(_("\nuse 'hg help -c %s' to see help for "
                        "the %s command\n") % (name, name))
         except error.UnknownCommand:
             pass
         return rst
 
     def helpext(name, subtopic=None):
         try:
             mod = extensions.find(name)
             doc = gettext(pycompat.getdoc(mod)) or _('no help text available')
         except KeyError:
             mod = None
             doc = extensions.disabledext(name)
             if not doc:
                 raise error.UnknownCommand(name)
 
         if '\n' not in doc:
             head, tail = doc, ""
         else:
             head, tail = doc.split('\n', 1)
         rst = [_('%s extension - %s\n\n') % (name.rpartition('.')[-1], head)]
         if tail:
             rst.extend(tail.splitlines(True))
             rst.append('\n')
 
         if not ui.verbose:
             omitted = _('(some details hidden, use --verbose'
                          ' to show complete help)')
             indicateomitted(rst, omitted)
 
         if mod:
             try:
                 ct = mod.cmdtable
             except AttributeError:
                 ct = {}
             modcmds = set([c.partition('|')[0] for c in ct])
             rst.extend(helplist(modcmds.__contains__))
         else:
             rst.append(_("(use 'hg help extensions' for information on enabling"
                        " extensions)\n"))
         return rst
 
     def helpextcmd(name, subtopic=None):
-        cmd, ext, mod = extensions.disabledcmd(ui, name,
+        cmd, ext, doc = extensions.disabledcmd(ui, name,
                                                ui.configbool('ui', 'strict'))
-        doc = gettext(pycompat.getdoc(mod)).splitlines()[0]
+        doc = doc.splitlines()[0]
 
         rst = listexts(_("'%s' is provided by the following "
                               "extension:") % cmd, {ext: doc}, indent=4,
                        showdeprecated=True)
         rst.append('\n')
         rst.append(_("(use 'hg help extensions' for information on enabling "
                    "extensions)\n"))
         return rst
 
 
     rst = []
     kw = opts.get('keyword')
     if kw or name is None and any(opts[o] for o in opts):
         matches = topicmatch(ui, commands, name or '')
         helpareas = []
         if opts.get('extension'):
             helpareas += [('extensions', _('Extensions'))]
         if opts.get('command'):
             helpareas += [('commands', _('Commands'))]
         if not helpareas:
             helpareas = [('topics', _('Topics')),
                          ('commands', _('Commands')),
                          ('extensions', _('Extensions')),
                          ('extensioncommands', _('Extension Commands'))]
         for t, title in helpareas:
             if matches[t]:
                 rst.append('%s:\n\n' % title)
                 rst.extend(minirst.maketable(sorted(matches[t]), 1))
                 rst.append('\n')
         if not rst:
             msg = _('no matches')
             hint = _("try 'hg help' for a list of topics")
             raise error.Abort(msg, hint=hint)
     elif name and name != 'shortlist':
         queries = []
         if unknowncmd:
             queries += [helpextcmd]
         if opts.get('extension'):
             queries += [helpext]
         if opts.get('command'):
             queries += [helpcmd]
         if not queries:
             queries = (helptopic, helpcmd, helpext, helpextcmd)
         for f in queries:
             try:
                 rst = f(name, subtopic)
                 break
             except error.UnknownCommand:
                 pass
         else:
             if unknowncmd:
                 raise error.UnknownCommand(name)
             else:
                 msg = _('no such help topic: %s') % name
                 hint = _("try 'hg help --keyword %s'") % name
                 raise error.Abort(msg, hint=hint)
     else:
         # program name
         if not ui.quiet:
             rst = [_("Mercurial Distributed SCM\n"), '\n']
         rst.extend(helplist(None, **pycompat.strkwargs(opts)))
 
     return ''.join(rst)
 
 def formattedhelp(ui, commands, name, keep=None, unknowncmd=False, full=True,
                   **opts):
     """get help for a given topic (as a dotted name) as rendered rst
 
     Either returns the rendered help text or raises an exception.
     """
     if keep is None:
         keep = []
     else:
         keep = list(keep) # make a copy so we can mutate this later
     fullname = name
     section = None
     subtopic = None
     if name and '.' in name:
         name, remaining = name.split('.', 1)
         remaining = encoding.lower(remaining)
         if '.' in remaining:
             subtopic, section = remaining.split('.', 1)
         else:
             if name in subtopics:
                 subtopic = remaining
             else:
                 section = remaining
     textwidth = ui.configint('ui', 'textwidth')
     termwidth = ui.termwidth() - 2
     if textwidth <= 0 or termwidth < textwidth:
         textwidth = termwidth
     text = help_(ui, commands, name,
                  subtopic=subtopic, unknowncmd=unknowncmd, full=full, **opts)
 
     formatted, pruned = minirst.format(text, textwidth, keep=keep,
                                        section=section)
 
     # We could have been given a weird ".foo" section without a name
     # to look for, or we could have simply failed to found "foo.bar"
     # because bar isn't a section of foo
     if section and not (formatted and name):
         raise error.Abort(_("help section not found: %s") % fullname)
 
     if 'verbose' in pruned:
         keep.append('omitted')
     else:
         keep.append('notomitted')
     formatted, pruned = minirst.format(text, textwidth, keep=keep,
                                        section=section)
     return formatted