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

comparison mercurial/help.py @ 49763:2a70d1fc70c4

typing: add type hints to mercurial/help.py Was hoping to find more issues like f09bc2ed9100, but it may be that nothing checks the args to that operation. In any event, the work is done and pytype doesn't do a very good job inferring the types. A few of th emore complicated things like the command table are left untyped, because they come from modules that aren't typed yet.

author	Matt Harbison <matt_harbison@yahoo.com>
date	Sun, 20 Nov 2022 22:54:43 -0500
parents	04e6add9e4dc
children	f56873a7284c

comparison

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:

Mercurial > public > mercurial-scm > hg-stable

comparison mercurial/help.py @ 49763:2a70d1fc70c4