robotcode-robot 2.9.0.dev87__tar.gz → 2.9.0.dev124__tar.gz

{robotcode_robot-2.9.0.dev87 → robotcode_robot-2.9.0.dev124}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: robotcode-robot
-Version: 2.9.0-dev.87
+Version: 2.9.0-dev.124
 Summary: Support classes for RobotCode for handling Robot Framework projects.
 Project-URL: Homepage, https://robotcode.io
 Project-URL: Donate, https://opencollective.com/robotcode
@@ -27,7 +27,7 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: platformdirs>=4.3
-Requires-Dist: robotcode-core==2.9.0-dev.87
+Requires-Dist: robotcode-core==2.9.0-dev.124
 Requires-Dist: robotframework>=5.0.0
 Requires-Dist: tomli>=1.1.0; python_version < '3.11'
 Description-Content-Type: text/markdown

{robotcode_robot-2.9.0.dev87 → robotcode_robot-2.9.0.dev124}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
   "robotframework>=5.0.0",
   "tomli>=1.1.0; python_version < '3.11'",
   "platformdirs>=4.3",
-  "robotcode-core==2.9.0-dev.87",
+  "robotcode-core==2.9.0-dev.124",
 ]
 dynamic = ["version"]
 

robotcode_robot-2.9.0.dev124/src/robotcode/robot/__version__.py

@@ -0,0 +1 @@
+__version__ = "2.9.0-dev.124"

{robotcode_robot-2.9.0.dev87 → robotcode_robot-2.9.0.dev124}/src/robotcode/robot/diagnostics/library_doc.py

@@ -90,6 +90,7 @@ from ..utils.markdown_docs import (
     code_span,
     code_span_variables,
     escape_link_text,
+    escape_text,
     extract_reference_definitions,
     heading_anchors,
     iter_headings,
@@ -99,6 +100,7 @@ from ..utils.markdown_docs import (
     section_anchors,
     shift_headings,
     slugify,
+    unescape_text,
     unique_reference_labels,
 )
 from ..utils.markdownformatter import MarkDownFormatter, NameLinker
@@ -241,18 +243,17 @@ def _page_heading_shift(doc_format: str, levels: int) -> Optional[Callable[[str]
 
 
 # A run of `#` after a space at the end of a keyword name would close its ATX heading: `### Use C #` shows "Use C".
-_RE_CLOSING_HASHES = re.compile(r"(\s)(#+)$")
-_RE_ESCAPED_CLOSING_HASHES = re.compile(r"(\s)\\(#+)$")
 
 
 def _heading_name(name: str) -> str:
-    """A keyword name as the title of its heading: a closing run of `#` escaped."""
-    return _RE_CLOSING_HASHES.sub(r"\1\\\2", name)
+    """A keyword name as the title of its heading: what Markdown would read as markup escaped,
+    also a closing run of `#`."""
+    return escape_text(name)
 
 
 def _heading_title_name(title: str) -> str:
     """The keyword name of a heading title that `_heading_name` wrote."""
-    return _RE_ESCAPED_CLOSING_HASHES.sub(r"\1\2", title)
+    return unescape_text(title)
 
 
 def _match_heading_anchors(headings: List[Tuple[str, str]], titles: List[Set[str]]) -> List[str]:
@@ -1284,7 +1285,7 @@ class KeywordDoc(SourceEntity):
         in_code = False
         for raw_line in self._format_doc_fragment(text, link_resolver, targets).splitlines():
             line = raw_line.strip()
-            if re.match(r"(`{3,}|~{3,})", line):
+            if re.match(r"(`{3,}(?!.*`)|~{3,})", line):
                 in_code = not in_code
                 new_line = True
             elif not line:
@@ -1348,7 +1349,8 @@ class KeywordDoc(SourceEntity):
         if add_type:
             result = (
                 f"#{'#' * header_level} "
-                f"{(self.libtype or 'Library').capitalize() if self.is_initializer else 'Keyword'} *{self.name}*\n"
+                f"{(self.libtype or 'Library').capitalize() if self.is_initializer else 'Keyword'} "
+                f"*{_heading_name(self.name)}*\n"
             )
         else:
             if not self.is_initializer:
@@ -1993,9 +1995,9 @@ class LibraryDoc:
         for level, title, anchor in heading_anchors(page):
             if level == header_level + 2:
                 in_introduction = title == "Introduction"
-                section_anchors_by_title.setdefault(normalize_reference(title), anchor)
+                section_anchors_by_title.setdefault(normalize_reference(_heading_title_name(title)), anchor)
             elif level > header_level + 2 and in_introduction:
-                introduction.setdefault(normalize_reference(title), anchor)
+                introduction.setdefault(normalize_reference(_heading_title_name(title)), anchor)
         section_anchors_by_title.update(introduction)
         _, type_anchors = self.get_page_anchors(page, header_level)
 

{robotcode_robot-2.9.0.dev87 → robotcode_robot-2.9.0.dev124}/src/robotcode/robot/utils/markdown_docs.py

@@ -18,9 +18,11 @@ __all__ = [
     "LinkResolver",
     "ReferenceTarget",
     "anchor_link_resolver",
+    "code_lines_before_headings",
     "code_span",
     "code_span_variables",
     "escape_link_text",
+    "escape_text",
     "extract_reference_definitions",
     "heading_anchors",
     "iter_headings",
@@ -34,6 +36,7 @@ __all__ = [
     "section_anchors",
     "shift_headings",
     "slugify",
+    "unescape_text",
     "unique_reference_labels",
 ]
 
@@ -60,7 +63,7 @@ class ReferenceTarget(NamedTuple):
 LinkResolver = Callable[[str, str], Optional[str]]
 
 # indented more than three spaces a fence belongs to a list item
-_RE_FENCE = re.compile(r"^\s*(`{3,}|~{3,})")
+_RE_FENCE = re.compile(r"^\s*(`{3,}(?!.*`)|~{3,})")
 _RE_ATX_HEADING = re.compile(r"^( {0,3})(#{1,6})(?=\s|$)(.*)$")
 _RE_HEADING_TITLE = re.compile(r"^ {0,3}(#{1,6})\s+(.+?)(?:\s+#+)?\s*$")
 _RE_ADMONITION = re.compile(r"^(\s*(?:>\s*)+)\[!([A-Za-z]+)\][ \t]*(.*?)\s*$")
@@ -147,6 +150,36 @@ def escape_link_text(text: str) -> str:
     return _RE_LINK_TEXT_SPECIAL.sub(r"\\\1", text)
 
 
+_RE_TEXT_SPECIAL = re.compile(
+    r"""
+  \\(?=[!-/:-@\[-`{-~]|\Z)     # a backslash before ASCII punctuation or at the end
+| [<\#`]                       # always
+| (?<!\s)\* | \*(?!\s)         # a star, unless it has space on both sides
+| (?<![^\W_])_ | _(?![^\W_])   # an underscore, unless it is inside a word
+| &(?=\#?\w+;)                 # what reads as an entity
+| \](?=\()                     # what reads as an inline link
+| ~(?=~) | (?<=~)~             # what reads as strikethrough
+""",
+    re.VERBOSE,
+)
+_RE_ESCAPED_VARIABLE = re.compile(r"(?<!\\)((?:\\\\)+)\$")
+_RE_MARKDOWN_ESCAPE = re.compile(r"\\([!-/:-@\[-`{-~])")
+
+
+def escape_text(text: str) -> str:
+    """Escape what Markdown would read as markup in text that is meant as text, only where
+    it would change the text: `snake_case`, `${list}[0]` and `2 * 3` stay as they are.
+
+    An odd number of backslashes before `$` is an escaped variable and stays one."""
+    text = _RE_TEXT_SPECIAL.sub(r"\\\g<0>", text)
+    return _RE_ESCAPED_VARIABLE.sub(lambda m: m.group(1) + ("\\$" if len(m.group(1)) % 4 else "$"), text)
+
+
+def unescape_text(text: str) -> str:
+    """The text that Markdown shows for `text`, without its escapes."""
+    return _RE_MARKDOWN_ESCAPE.sub(r"\1", text)
+
+
 def anchor_link_resolver(kind: str, name: str) -> Optional[str]:
     """A `LinkResolver` for pages that show a whole library: keywords and
     sections have a heading there. The heading of a type can carry a number,
@@ -200,6 +233,19 @@ def iter_headings(text: str) -> Iterator[Tuple[int, str]]:
             yield len(match.group(1)), match.group(2)
 
 
+def code_lines_before_headings(text: str) -> List[List[str]]:
+    """For every ATX heading, the lines of code blocks since the heading before it, stripped."""
+    result: List[List[str]] = []
+    lines: List[str] = []
+    for line, in_code in _iter_lines(text):
+        if in_code:
+            lines.append(line.strip())
+        elif _RE_HEADING_TITLE.match(line):
+            result.append(lines)
+            lines = []
+    return result
+
+
 def heading_anchors(text: str) -> List[Tuple[int, str, str]]:
     """Level, title and anchor of every ATX heading, in document order.
 
@@ -522,8 +568,11 @@ def _iter_text_lines(text: str) -> Iterator[Tuple[str, bool]]:
 
 
 def code_span(text: str) -> str:
-    """`text` as inline code, with a fence longer than any run of backticks in it."""
-    fence = "`" * (max((len(run) for run in _RE_BACKTICKS.findall(text)), default=0) + 1)
+    """`text` as inline code, with the shortest fence that no run of backticks in it has."""
+    runs = {len(run) for run in _RE_BACKTICKS.findall(text)}
+    fence = "`"
+    while len(fence) in runs:
+        fence += "`"
     padding = " " if text.startswith("`") or text.endswith("`") else ""
     return f"{fence}{padding}{text}{padding}{fence}"
 
@@ -538,7 +587,8 @@ def _code_span_variables_in(text: str) -> str:
         # variables that follow each other directly share one code span: `${TEMPDIR}${/}`
         while (following := search_variable(text[end:], "$", ignore_errors=True)).start == 0:
             end += following.end
-        result.append(text[: match.start] + code_span(text[match.start : end]))
+        # inside code an escape would show
+        result.append(text[: match.start] + code_span(unescape_text(text[match.start : end])))
         text = text[end:]
     result.append(text)
     return "".join(result)

{robotcode_robot-2.9.0.dev87 → robotcode_robot-2.9.0.dev124}/src/robotcode/robot/utils/markdownformatter.py

@@ -5,7 +5,7 @@ import re
 from abc import ABC, abstractmethod
 from typing import Any, Callable, Final, Iterator, List, Optional, Tuple
 
-from .markdown_docs import escape_link_text
+from .markdown_docs import code_span, escape_link_text, escape_text
 
 # Gets a name in single backticks of documentation in Robot Framework's format and
 # returns the target of a link to it, or `None` if it stays inline code.
@@ -13,7 +13,23 @@ NameLinker = Callable[[str], Optional[str]]
 
 # a name in single backticks, not code in double backticks
 _RE_NAME: Final["re.Pattern[str]"] = re.compile(r"(?<!`)`([^`]+)`(?!`)")
-_RE_NAME_PLACEHOLDER: Final["re.Pattern[str]"] = re.compile("\ue000(\\d+)\ue001")
+_RE_CODE_SPAN: Final["re.Pattern[str]"] = re.compile(
+    r"""
+\\.                     # what Markdown reads as an escaped character
+| (?<!`) (`+) (?!`)      # a run of backticks (group 1)
+  ([^\ue000]+?)          # anything but code that is already held (group 2)
+  (?<!`) \1 (?!`)        # up to the next run of the same length
+""",
+    re.VERBOSE,
+)
+# the documentation's own characters that the conversion uses
+_RE_OWN_MARKERS: Final["re.Pattern[str]"] = re.compile("[\ue000\ue002\ue003]")
+# what is no text: held code (group 1) and the syntax the formatter writes itself (group 2)
+_RE_NOT_TEXT: Final["re.Pattern[str]"] = re.compile("(\ue000\\d+\ue001)|\ue002(.*?)\ue003")
+# what starts a Markdown block: a quote, a list or a reference definition (group 1), a numbered list (groups 2 and 3)
+_RE_BLOCK_START: Final["re.Pattern[str]"] = re.compile(r"^(?:(>|[+-](?=\s|$)|\[(?=[^\]]*\]:))|(\d{1,9})([.)])(?=\s|$))")
+_RE_THREE_BACKTICKS: Final["re.Pattern[str]"] = re.compile("(?<!`)```(?!`)")
+_RE_LONG_BACKTICKS: Final["re.Pattern[str]"] = re.compile("`{3,}")
 
 
 class Formatter(ABC):
@@ -44,7 +60,7 @@ class MarkDownFormatter:
     def __init__(self, name_linker: Optional[NameLinker] = None) -> None:
         """`name_linker` turns names in single backticks into links, as Libdoc links them.
 
-        Headings and preformatted text keep their names.
+        Headings keep their names, in preformatted text they lose their backticks.
         """
         self._results: List[str] = []
         line_formatter = _line_formatter if name_linker is None else LineFormatter(name_linker)
@@ -112,7 +128,7 @@ class HeaderFormatter(SingleLineFormatter):
         if m is not None:
             level, text = m.groups()
 
-            return "%s %s\n" % ("#" * (len(level) + 1), text)
+            return "%s %s\n" % ("#" * (len(level) + 1), _format_heading(text))
         return ""
 
 
@@ -144,15 +160,14 @@ class LinkFormatter:
         return pre + self._get_link(url)
 
     def _get_image(self, src: str, title: Optional[str] = None) -> str:
-        return f"![{title or src}]({self._target(src)})"
+        return _syntax(f"![{escape_text(title or src)}]({self._target(src)})")
 
     def _get_link(self, href: str, content: Optional[str] = None) -> str:
-        return f"[{content or href}]({self._target(href)})"
+        return _syntax("[") + (content or href) + _syntax(f"]({self._target(href)})")
 
     def _target(self, target: str) -> str:
-        # `#` is escaped in the whole line before links are formatted, a link target needs it as it is
-        target = target.replace("\\#", "#")
-        # Markdown takes a target with spaces only in angle brackets; `<` is already escaped in the whole line
+        target = target.replace("<", "\\<")
+        # Markdown takes a target with spaces only in angle brackets
         if " " in target:
             return "<" + target.replace(">", "\\>") + ">"
         return target
@@ -173,32 +188,76 @@ class LinkFormatter:
             content = self._get_image(content, link)
         elif self._is_image(link):
             return self._get_image(link, content)
-        if link.startswith("\\#"):
+        if link.startswith("#"):
             link = link.lower()
         return self._get_link(link, content)
 
     def remove_link(self, text: str) -> str:
         # 2nd, 4th, etc. token contains link, others surrounding content
         tokens = self._link.split(text)
-        if len(tokens) > 1:
-            formatters: Iterator[Callable[[str], Any]] = itertools.cycle([self._remove_link])
-            return "".join(f(t) for f, t in zip(formatters, tokens))
-        return text
+        formatters: Iterator[Callable[[str], str]] = itertools.cycle((str, self._remove_link))
+        return "".join(f(t) for f, t in zip(formatters, tokens))
 
     def _remove_link(self, text: str) -> str:
-        if "|" not in text:
-            return text
-
         link, content = (t.strip() for t in text.split("|", 1))
-        if self._is_image(content):
-            return self._get_image(content, link)
-
-        return content
+        return content or link
 
     def _is_image(self, text: str) -> bool:
         return text.startswith("data:image/") or text.lower().endswith(self._image_exts)
 
 
+def _code_text(text: str) -> str:
+    """The text of code as a reader copies it: as written, only links and names lose their markup,
+    which Libdoc does not show either."""
+    return _RE_NAME.sub(r"\1", LinkFormatter().remove_link(text))
+
+
+def _hold(held: List[str], text: str) -> str:
+    """Puts text behind a placeholder, so that the other formatting cannot change it."""
+    held.append(text)
+    return f"\ue000{len(held) - 1}\ue001"
+
+
+def _hold_own_markers(line: str, held: List[str]) -> str:
+    return _RE_OWN_MARKERS.sub(lambda m: _hold(held, m.group(0)), line)
+
+
+def _restore(line: str, held: List[str]) -> str:
+    # backwards, the documentation's own characters can be part of held code
+    for index, text in reversed(list(enumerate(held))):
+        line = line.replace(f"\ue000{index}\ue001", text)
+    return line
+
+
+def _syntax(text: str) -> str:
+    """Marks what the formatter writes itself, the escape of the text leaves it alone."""
+    return f"\ue002{text}\ue003"
+
+
+def _escape_line(line: str) -> str:
+    result: List[str] = []
+    position = 0
+    for match in _RE_NOT_TEXT.finditer(line):
+        result.append(escape_text(line[position : match.start()]))
+        result.append(match.group(1) or match.group(2))
+        position = match.end()
+    result.append(escape_text(line[position:]))
+    return "".join(result)
+
+
+def _escape_block_start(match: re.Match[str]) -> str:
+    return f"\\{match.group(1)}" if match.group(1) else f"{match.group(2)}\\{match.group(3)}"
+
+
+def _format_heading(text: str) -> str:
+    """Robot Framework formats nothing in a heading, what Markdown would read as markup is text there."""
+    held: List[str] = []
+    text = _hold_own_markers(text, held)
+    if "`" in text:
+        text = _RE_CODE_SPAN.sub(lambda m: m.group(0) if m.group(1) is None else _hold(held, m.group(0)), text)
+    return _restore(_escape_line(text), held)
+
+
 class LineFormatter:
     _bold: Final["re.Pattern[str]"] = re.compile(
         r"""
@@ -242,49 +301,42 @@ _                          # end of italic
 
         self._name_linker = name_linker
         self._formatters: List[Tuple[str, Callable[[str], str]]] = [
-            ("<", self._quote_lower_then),
-            ("#", self._quote_hash),
             ("*", self._format_bold),
             ("_", self._format_italic),
-            ("``", self._format_code),
             ("", LinkFormatter().format_link),
         ]
 
     def format(self, line: str) -> str:
-        links: List[str] = []
-        if self._name_linker is not None and "`" in line:
-            # before the other formatting, which makes ``code`` the same code span as a `name`
-            line = _RE_NAME.sub(lambda m: self._link_name(m, links), line)
+        held: List[str] = []
+        line = _hold_own_markers(line, held)
+        if "`" in line:
+            # what Robot Framework reads as code decides first, then what else Markdown reads as code
+            line = self._code.sub(lambda m: m.group(1) + _hold(held, code_span(_code_text(m.group(3)))), line)
+            line = _RE_CODE_SPAN.sub(lambda m: self._hold_span(m, held), line)
         for marker, formatter in self._formatters:
             if marker in line:
                 line = formatter(line)
-        if links:
-            line = _RE_NAME_PLACEHOLDER.sub(lambda m: links[int(m.group(1))], line)
-        return line
-
-    def _link_name(self, match: re.Match[str], links: List[str]) -> str:
-        assert self._name_linker is not None
-        target = self._name_linker(match.group(1))
-        if target is None:
-            return match.group(0)
-        # the link waits behind a placeholder, so the other formatting cannot change it
-        links.append(f"[{escape_link_text(match.group(1))}]({target})")
-        return f"\ue000{len(links) - 1}\ue001"
+        # last, so that all that is left of the line is text
+        line = _RE_BLOCK_START.sub(_escape_block_start, _escape_line(line))
+        return _restore(line, held)
 
-    def _quote_lower_then(self, line: str) -> str:
-        return line.replace("<", "\\<")
-
-    def _quote_hash(self, line: str) -> str:
-        return line.replace("#", "\\#")
+    def _hold_span(self, match: re.Match[str], held: List[str]) -> str:
+        text, fence, span = match.group(0, 1, 2)
+        if fence is None:
+            return text
+        # for Robot Framework this is no code, but Markdown shows it as code
+        if len(fence) > 1:
+            return _hold(held, text)
+        target = None if self._name_linker is None else self._name_linker(span)
+        if target is not None:
+            return _hold(held, f"[{escape_link_text(span)}]({target})")
+        return _hold(held, code_span(_code_text(span)))
 
     def _format_bold(self, line: str) -> str:
-        return self._bold.sub("\\1**\\3**", line)
+        return self._bold.sub(f"\\1{_syntax('**')}\\3{_syntax('**')}", line)
 
     def _format_italic(self, line: str) -> str:
-        return self._italic.sub("\\1*\\3*", line)
-
-    def _format_code(self, line: str) -> str:
-        return self._code.sub("\\1`\\3`", line)
+        return self._italic.sub(f"\\1{_syntax('*')}\\3{_syntax('*')}", line)
 
 
 _line_formatter = LineFormatter()
@@ -295,8 +347,16 @@ class PreformattedFormatter(Formatter):
         return line.startswith("| ") or line == "|"
 
     def format(self, lines: List[str]) -> str:
-        lines = [LinkFormatter().remove_link(line[2:]) for line in lines]
-        return "```text\n" + "\n".join(lines) + "\n```\n"
+        text = "\n".join(self._format_line(line[2:]) for line in lines)
+        # a line of backticks must not end the block
+        fence = "`" * max((len(run) + 1 for run in _RE_LONG_BACKTICKS.findall(text)), default=3)
+        return f"{fence}text\n{text}\n{fence}\n"
+
+    def _format_line(self, line: str) -> str:
+        # the whole block is code, so double backticks have nothing left to say
+        line = _code_text(LineFormatter._code.sub(r"\1\3", line))
+        # a backtick can't be escaped, Libdoc shows three in a row as one
+        return _RE_THREE_BACKTICKS.sub("`", line)
 
 
 class ParagraphFormatter(Formatter):

robotcode_robot-2.9.0.dev87/src/robotcode/robot/__version__.py

@@ -1 +0,0 @@
-__version__ = "2.9.0-dev.87"