mercurial-scm/hg: comparison mercurial/help.py

equal deleted inserted replaced

-:5744ceeb9067
+:2a70d1fc70c4
 import itertools
 import re
 import textwrap
+from typing import (
+Callable,
+Dict,
+Iterable,
+List,
+Optional,
+Set,
+Tuple,
+Union,
+cast,
+)
 from .i18n import (
 _,
 gettext,
 )
 compression,
 resourceutil,
 stringutil,
 )
-_exclkeywords = {
+_DocLoader = Callable[[uimod.ui], bytes]
+# Old extensions may not register with a category
+_HelpEntry = Union["_HelpEntryNoCategory", "_HelpEntryWithCategory"]
+_HelpEntryNoCategory = Tuple[List[bytes], bytes, _DocLoader]
+_HelpEntryWithCategory = Tuple[List[bytes], bytes, _DocLoader, bytes]
+_SelectFn = Callable[[object], bool]
+_SynonymTable = Dict[bytes, List[bytes]]
+_TopicHook = Callable[[uimod.ui, bytes, bytes], bytes]
+_exclkeywords: Set[bytes] = {
 b"(ADVANCED)",
 b"(DEPRECATED)",
 b"(EXPERIMENTAL)",
 # i18n: "(ADVANCED)" is a keyword, must be translated consistently
 _(b"(ADVANCED)"),
 # The order in which command categories will be displayed.
 # Extensions with custom categories should insert them into this list
 # after/before the appropriate item, rather than replacing the list or
 # assuming absolute positions.
-CATEGORY_ORDER = [
+CATEGORY_ORDER: List[bytes] = [
 registrar.command.CATEGORY_REPO_CREATION,
 registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT,
 registrar.command.CATEGORY_COMMITTING,
 registrar.command.CATEGORY_CHANGE_MANAGEMENT,
 registrar.command.CATEGORY_CHANGE_ORGANIZATION,
 registrar.command.CATEGORY_NONE,
 ]
 # Human-readable category names. These are translated.
 # Extensions with custom categories should add their names here.
-CATEGORY_NAMES = {
+CATEGORY_NAMES: Dict[bytes, bytes] = {
 registrar.command.CATEGORY_REPO_CREATION: b'Repository creation',
 registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT: b'Remote repository management',
 registrar.command.CATEGORY_COMMITTING: b'Change creation',
 registrar.command.CATEGORY_CHANGE_NAVIGATION: b'Change navigation',
 registrar.command.CATEGORY_CHANGE_MANAGEMENT: b'Change manipulation',
 # The order in which topic categories will be displayed.
 # Extensions with custom categories should insert them into this list
 # after/before the appropriate item, rather than replacing the list or
 # assuming absolute positions.
-TOPIC_CATEGORY_ORDER = [
+TOPIC_CATEGORY_ORDER: List[bytes] = [
 TOPIC_CATEGORY_IDS,
 TOPIC_CATEGORY_OUTPUT,
 TOPIC_CATEGORY_CONFIG,
 TOPIC_CATEGORY_CONCEPTS,
 TOPIC_CATEGORY_MISC,
 TOPIC_CATEGORY_NONE,
 ]
 # Human-readable topic category names. These are translated.
-TOPIC_CATEGORY_NAMES = {
+TOPIC_CATEGORY_NAMES: Dict[bytes, bytes] = {
 TOPIC_CATEGORY_IDS: b'Mercurial identifiers',
 TOPIC_CATEGORY_OUTPUT: b'Mercurial output',
 TOPIC_CATEGORY_CONFIG: b'Mercurial configuration',
 TOPIC_CATEGORY_CONCEPTS: b'Concepts',
 TOPIC_CATEGORY_MISC: b'Miscellaneous',
 TOPIC_CATEGORY_NONE: b'Uncategorized topics',
 }
-def listexts(header, exts, indent=1, showdeprecated=False):
+def listexts(
+header: bytes,
+exts: Dict[bytes, bytes],
+indent: int = 1,
+showdeprecated: bool = False,
+) -> List[bytes]:
 '''return a text listing of the given extensions'''
 rst = []
 if exts:
 for name, desc in sorted(exts.items()):
 if not showdeprecated and any(w in desc for w in _exclkeywords):
 if rst:
 rst.insert(0, b'\n%s\n\n' % header)
 return rst
-def extshelp(ui):
+def extshelp(ui: uimod.ui) -> bytes:
 rst = loaddoc(b'extensions')(ui).splitlines(True)
 rst.extend(
 listexts(
 _(b'enabled extensions:'), extensions.enabled(), showdeprecated=True
 )
 )
 doc = b''.join(rst)
 return doc
-def parsedefaultmarker(text):
+def parsedefaultmarker(text: bytes) -> Optional[Tuple[bytes, List[bytes]]]:
 """given a text 'abc (DEFAULT: def.ghi)',
 returns (b'abc', (b'def', b'ghi')). Otherwise return None"""
 if text[-1:] == b')':
 marker = b' (DEFAULT: '
 pos = text.find(marker)
 if pos >= 0:
 item = text[pos + len(marker) : -1]
 return text[:pos], item.split(b'.', 2)
-def optrst(header, options, verbose, ui):
+def optrst(header: bytes, options, verbose: bool, ui: uimod.ui) -> bytes:
 data = []
 multioccur = False
 for option in options:
 if len(option) == 5:
 shortopt, longopt, default, desc, optlabel = option
 rst.extend(minirst.maketable(data, 1))
 return b''.join(rst)
-def indicateomitted(rst, omitted, notomitted=None):
+def indicateomitted(
+rst: List[bytes], omitted: bytes, notomitted: Optional[bytes] = None
+) -> None:
 rst.append(b'\n\n.. container:: omitted\n\n    %s\n\n' % omitted)
 if notomitted:
 rst.append(b'\n\n.. container:: notomitted\n\n    %s\n\n' % notomitted)
-def filtercmd(ui, cmd, func, kw, doc):
+def filtercmd(ui: uimod.ui, cmd: bytes, func, kw: bytes, doc: bytes) -> bool:
 if not ui.debugflag and cmd.startswith(b"debug") and kw != b"debug":
 # Debug command, and user is not looking for those.
 return True
 if not ui.verbose:
 if not kw and not doc:
 # Configuration explicitly hides the command.
 return True
 return False
-def filtertopic(ui, topic):
+def filtertopic(ui: uimod.ui, topic: bytes) -> bool:
 return ui.configbool(b'help', b'hidden-topic.%s' % topic, False)
-def topicmatch(ui, commands, kw):
+def topicmatch(
+ui: uimod.ui, commands, kw: bytes
+) -> Dict[bytes, List[Tuple[bytes, bytes]]]:
 """Return help topics matching kw.
 Returns {'section': [(name, summary), ...], ...} where section is
 one of topics, commands, extensions, or extensioncommands.
 """
 continue
 results[b'extensioncommands'].append((cmdname, cmddoc))
 return results
-def loaddoc(topic, subdir=None):
+def loaddoc(topic: bytes, subdir: Optional[bytes] = None) -> _DocLoader:
 """Return a delayed loader for help/topic.txt."""
-def loader(ui):
+def loader(ui: uimod.ui) -> bytes:
 package = b'mercurial.helptext'
 if subdir:
 package += b'.' + subdir
 with resourceutil.open_resource(package, topic + b'.txt') as fp:
 doc = gettext(fp.read())
 return doc
 return loader
-internalstable = sorted(
+internalstable: List[_HelpEntryNoCategory] = sorted(
 [
 (
 [b'bid-merge'],
 _(b'Bid Merge Algorithm'),
 loaddoc(b'bid-merge', subdir=b'internals'),
 ),
 ]
 )
-def internalshelp(ui):
+def internalshelp(ui: uimod.ui) -> bytes:
 """Generate the index for the "internals" topic."""
 lines = [
 b'To access a subtopic, use "hg help internals.{subtopic-name}"\n',
 b'\n',
 ]
 lines.append(b' :%s: %s\n' % (names[0], header))
 return b''.join(lines)
-helptable = sorted(
+helptable: List[_HelpEntryWithCategory] = sorted(
 [
 (
 [b'bundlespec'],
 _(b"Bundle File Formats"),
 loaddoc(b'bundlespec'),
 ),
 ]
 )
 # Maps topics with sub-topics to a list of their sub-topics.
-subtopics = {
+subtopics: Dict[bytes, List[_HelpEntryNoCategory]] = {
 b'internals': internalstable,
 }
 # Map topics to lists of callable taking the current topic help and
 # returning the updated version
-helphooks = {}
+helphooks: Dict[bytes, List[_TopicHook]] = {}
-def addtopichook(topic, rewriter):
+def addtopichook(topic: bytes, rewriter: _TopicHook) -> None:
 helphooks.setdefault(topic, []).append(rewriter)
-def makeitemsdoc(ui, topic, doc, marker, items, dedent=False):
+def makeitemsdoc(
+ui: uimod.ui,
+topic: bytes,
+doc: bytes,
+marker: bytes,
+items: Dict[bytes, bytes],
+dedent: bool = False,
+) -> bytes:
 """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):
 entries.append(b'\n'.join(doclines))
 entries = b'\n\n'.join(entries)
 return doc.replace(marker, entries)
-def addtopicsymbols(topic, marker, symbols, dedent=False):
+def addtopicsymbols(
-def add(ui, topic, doc):
+topic: bytes, marker: bytes, symbols, dedent: bool = False
+) -> None:
+def add(ui: uimod.ui, topic: bytes, doc: bytes):
 return makeitemsdoc(ui, topic, doc, marker, symbols, dedent=dedent)
 addtopichook(topic, add)
 addtopicsymbols(
 b'hgweb', b'.. webcommandsmarker', webcommands.commands, dedent=True
 )
-def inserttweakrc(ui, topic, doc):
+def inserttweakrc(ui: uimod.ui, topic: bytes, doc: bytes) -> bytes:
 marker = b'.. tweakdefaultsmarker'
 repl = uimod.tweakrc
 def sub(m):
 lines = [m.group(1) + s for s in repl.splitlines()]
 return b'\n'.join(lines)
 return re.sub(br'( *)%s' % re.escape(marker), sub, doc)
-def _getcategorizedhelpcmds(ui, cmdtable, name, select=None):
+def _getcategorizedhelpcmds(
+ui: uimod.ui, cmdtable, name: bytes, select: Optional[_SelectFn] = None
+) -> Tuple[Dict[bytes, List[bytes]], Dict[bytes, bytes], _SynonymTable]:
 # Category -> list of commands
 cats = {}
 # Command -> short description
 h = {}
 # Command -> string showing synonyms
 )
 cats.setdefault(cat, []).append(f)
 return cats, h, syns
-def _getcategorizedhelptopics(ui, topictable):
+def _getcategorizedhelptopics(
+ui: uimod.ui, topictable: List[_HelpEntry]
+) -> Tuple[Dict[bytes, List[Tuple[bytes, bytes]]], Dict[bytes, List[bytes]]]:
 # Group commands by category.
 topiccats = {}
 syns = {}
 for topic in topictable:
 names, header, doc = topic[0:3]
 if len(topic) > 3 and topic[3]:
-category = topic[3]
+category: bytes = cast(bytes, topic[3])  # help pytype
 else:
-category = TOPIC_CATEGORY_NONE
+category: bytes = TOPIC_CATEGORY_NONE
 topicname = names[0]
 syns[topicname] = list(names)
 if not filtertopic(ui, topicname):
 topiccats.setdefault(category, []).append((topicname, header))
 addtopichook(b'config', inserttweakrc)
 def help_(
-ui,
+ui: uimod.ui,
 commands,
-name,
+name: bytes,
-unknowncmd=False,
+unknowncmd: bool = False,
-full=True,
+full: bool = True,
-subtopic=None,
+subtopic: Optional[bytes] = None,
-fullname=None,
+fullname: Optional[bytes] = None,
 **opts
-):
+) -> bytes:
 """
 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):
+def helpcmd(name: bytes, subtopic: Optional[bytes]) -> List[bytes]:
 try:
 aliases, entry = cmdutil.findcmd(
 name, commands.table, strict=unknowncmd
 )
 except error.AmbiguousCommand as inst:
 )
 )
 return rst
-def helplist(select=None, **opts):
+def helplist(select: Optional[_SelectFn] = None, **opts) -> List[bytes]:
 cats, h, syns = _getcategorizedhelpcmds(
 ui, commands.table, name, select
 )
 rst = []
 elif name == b"debug":
 rst.append(_(b'debug commands (internal and unsupported):\n\n'))
 else:
 rst.append(_(b'list of commands:\n'))
-def appendcmds(cmds):
+def appendcmds(cmds: Iterable[bytes]) -> None:
 cmds = sorted(cmds)
 for c in cmds:
 display_cmd = c
 if ui.verbose:
 display_cmd = b', '.join(syns[c])
 )
 % (name and b" " + name or b"")
 )
 return rst
-def helptopic(name, subtopic=None):
+def helptopic(name: bytes, subtopic: Optional[bytes] = None) -> List[bytes]:
 # 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:
 )
 except error.UnknownCommand:
 pass
 return rst
-def helpext(name, subtopic=None):
+def helpext(name: bytes, subtopic: Optional[bytes] = None) -> List[bytes]:
 try:
 mod = extensions.find(name)
 doc = gettext(pycompat.getdoc(mod)) or _(b'no help text available')
 except KeyError:
 mod = None
 b" extensions)\n"
 )
 )
 return rst
-def helpextcmd(name, subtopic=None):
+def helpextcmd(
+name: bytes, subtopic: Optional[bytes] = None
+) -> List[bytes]:
 cmd, ext, doc = extensions.disabledcmd(
 ui, name, ui.configbool(b'ui', b'strict')
 )
 doc = stringutil.firstline(doc)
 return b''.join(rst)
 def formattedhelp(
-ui, commands, fullname, keep=None, unknowncmd=False, full=True, **opts
+ui: uimod.ui,
-):
+commands,
+fullname: Optional[bytes],
+keep: Optional[Iterable[bytes]] = None,
+unknowncmd: bool = False,
+full: bool = True,
+**opts
+) -> bytes:
 """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:

changeset 49646	2a70d1fc70c4
parent 49565	04e6add9e4dc
child 49664	f56873a7284c