links-notation 0.21.2__tar.gz → 0.22.0__tar.gz

{links_notation-0.21.2/links_notation.egg-info → links_notation-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: links-notation
-Version: 0.21.2
+Version: 0.22.0
 Summary: Python implementation of the Links Notation parser
 Author-email: "Link.Foundation" <drakonard@gmail.com>
 License-Expression: Unlicense
@@ -140,9 +140,42 @@ stream also exposes `position`, `drain()`, `reset()`, and a buffer-size limit.
 
 The main parser class for Links Notation.
 
-- `__init__(..., comments: bool = True)`: Create a parser; with `comments=False`
-  a `#` is an ordinary character instead of the start of a comment
-- `parse(input_text: str) -> List[Link]`: Parse Links Notation text into Link objects
+- `__init__(max_input_size: int = 10 * 1024 * 1024, max_depth: int = DEFAULT_MAX_DEPTH, comments: bool = True)`:
+  Create a parser; with `comments=False` a `#` is an ordinary character instead
+  of the start of a comment
+- `parse(input_text: str) -> List[Link]`: Parse Links Notation text into Link
+  objects; raises `ParseError` when the text does not parse or nests links
+  deeper than `max_depth`
+- `DEFAULT_MAX_DEPTH`: The default `max_depth`, 64, the same in every
+  implementation
+
+`max_depth` is how deep links may nest (default: 64). Every parenthesized group
+and every indentation level is one level, and the lines of a document start at
+level 0, so with `max_depth=1` `(a)` is accepted while `((a))`, `(a (b))` and a
+group on an indented line are refused. A document nested deeper is refused with
+a `ParseError` rather than recursed into until Python's recursion limit is hit.
+
+### ParseError
+
+Raised when parsing fails. When a document nests links deeper than
+`max_depth`, it points at the group or the line that is one level too deep:
+
+```text
+Nesting too deep at line 1, column 4: nesting depth exceeds the maximum of 3
+1 | ((((a))))
+  |    ^
+```
+
+- `max_depth`: The deepest nesting the parser accepts, when the document nests
+  deeper; `None` for any other error
+- `line`, `column`: Where the offending group or line starts, counted from 1
+- `offset`: The same position as a character offset from the start of the
+  document
+- `line_text`: The offending line, as written
+
+`StreamParser` reports the same error as a `StreamParseError` whose `error` is
+the `ParseError` and whose `line`, `column` and `offset` are counted from the
+start of the stream.
 
 ### Link
 

{links_notation-0.21.2 → links_notation-0.22.0}/README.md

@@ -102,9 +102,42 @@ stream also exposes `position`, `drain()`, `reset()`, and a buffer-size limit.
 
 The main parser class for Links Notation.
 
-- `__init__(..., comments: bool = True)`: Create a parser; with `comments=False`
-  a `#` is an ordinary character instead of the start of a comment
-- `parse(input_text: str) -> List[Link]`: Parse Links Notation text into Link objects
+- `__init__(max_input_size: int = 10 * 1024 * 1024, max_depth: int = DEFAULT_MAX_DEPTH, comments: bool = True)`:
+  Create a parser; with `comments=False` a `#` is an ordinary character instead
+  of the start of a comment
+- `parse(input_text: str) -> List[Link]`: Parse Links Notation text into Link
+  objects; raises `ParseError` when the text does not parse or nests links
+  deeper than `max_depth`
+- `DEFAULT_MAX_DEPTH`: The default `max_depth`, 64, the same in every
+  implementation
+
+`max_depth` is how deep links may nest (default: 64). Every parenthesized group
+and every indentation level is one level, and the lines of a document start at
+level 0, so with `max_depth=1` `(a)` is accepted while `((a))`, `(a (b))` and a
+group on an indented line are refused. A document nested deeper is refused with
+a `ParseError` rather than recursed into until Python's recursion limit is hit.
+
+### ParseError
+
+Raised when parsing fails. When a document nests links deeper than
+`max_depth`, it points at the group or the line that is one level too deep:
+
+```text
+Nesting too deep at line 1, column 4: nesting depth exceeds the maximum of 3
+1 | ((((a))))
+  |    ^
+```
+
+- `max_depth`: The deepest nesting the parser accepts, when the document nests
+  deeper; `None` for any other error
+- `line`, `column`: Where the offending group or line starts, counted from 1
+- `offset`: The same position as a character offset from the start of the
+  document
+- `line_text`: The offending line, as written
+
+`StreamParser` reports the same error as a `StreamParseError` whose `error` is
+the `ParseError` and whose `line`, `column` and `offset` are counted from the
+start of the stream.
 
 ### Link
 

{links_notation-0.21.2 → links_notation-0.22.0}/README.ru.md

@@ -103,9 +103,43 @@ for link in parse_chunks(["одна свя", "зь\nвторая связь"]):
 
 Основной класс парсера для Links Notation.
 
-- `__init__(..., comments: bool = True)`: создать парсер; при `comments=False`
-  `#` — обычный символ, а не начало комментария
-- `parse(input_text: str) -> List[Link]`: Парсинг текста Links Notation в объекты Link
+- `__init__(max_input_size: int = 10 * 1024 * 1024, max_depth: int = DEFAULT_MAX_DEPTH, comments: bool = True)`:
+  создать парсер; при `comments=False` `#` — обычный символ, а не начало
+  комментария
+- `parse(input_text: str) -> List[Link]`: Парсинг текста Links Notation в
+  объекты Link; выбрасывает `ParseError`, если текст не удалось разобрать или
+  связи в нем вложены глубже `max_depth`
+- `DEFAULT_MAX_DEPTH`: значение `max_depth` по умолчанию, 64, одинаковое во всех
+  реализациях
+
+`max_depth` — насколько глубоко могут вкладываться связи (по умолчанию 64).
+Каждая группа в скобках и каждый уровень отступа — это один уровень, а строки
+документа находятся на уровне 0, поэтому при `max_depth=1` `(a)` принимается,
+а `((a))`, `(a (b))` и группа на строке с отступом отклоняются. Документ с более
+глубокой вложенностью отклоняется с `ParseError`, а не разбирается рекурсивно,
+пока не будет достигнут предел рекурсии Python.
+
+### ParseError
+
+Выбрасывается при ошибке разбора. Когда связи в документе вложены глубже
+`max_depth`, указывает на группу или строку, которая на уровень глубже
+допустимого:
+
+```text
+Nesting too deep at line 1, column 4: nesting depth exceeds the maximum of 3
+1 | ((((a))))
+  |    ^
+```
+
+- `max_depth`: наибольшая допустимая глубина вложенности, если документ вложен
+  глубже; `None` для любой другой ошибки
+- `line`, `column`: где начинается группа или строка, считая с 1
+- `offset`: та же позиция как смещение в символах от начала документа
+- `line_text`: строка с ошибкой в том виде, в каком она написана
+
+`StreamParser` сообщает о той же ошибке через `StreamParseError`, у которого
+`error` — это `ParseError`, а `line`, `column` и `offset` отсчитываются от
+начала потока.
 
 ### Link
 

{links_notation-0.21.2 → links_notation-0.22.0}/links_notation/__init__.py

@@ -14,7 +14,7 @@ from .comments import strip_comments
 from .format_config import FormatConfig
 from .formatter import format_links
 from .link import Link
-from .parser import Parser
+from .parser import DEFAULT_MAX_DEPTH, ParseError, Parser
 from .stream_parser import StreamParseError, StreamParser, StreamPosition, parse_async_chunks, parse_chunks
 
 
@@ -47,7 +47,9 @@ def _read_version() -> str:
 __version__ = _read_version()
 
 __all__ = [
+    "DEFAULT_MAX_DEPTH",
     "Link",
+    "ParseError",
     "Parser",
     "StreamParseError",
     "StreamParser",

{links_notation-0.21.2 → links_notation-0.22.0}/links_notation/parser.py

@@ -5,15 +5,135 @@ This module provides parsing functionality for Links Notation (Lino),
 converting text into structured Link objects.
 """
 
-from typing import Any, Dict, List, Optional
+import re
+from typing import Any, Dict, List, Optional, Tuple
 
 from .comments import strip_comments
 from .link import Link
 from .quotes import _parse_quoted_string_at
 
+#: How deep links may nest unless a parser is told otherwise: every
+#: parenthesized group and every indentation level is one level, and the lines
+#: of a document are at level 0. Every implementation shares this default.
+DEFAULT_MAX_DEPTH = 64
+
+#: The number of characters a quoted line is cut down to.
+_QUOTED_LINE_WIDTH = 80
+
+#: What a message writes in place of the part of a long line it left out.
+_ELLIPSIS = "..."
+
+
+#: The characters that can end a line or open a quoted string.
+_LINE_BREAK_OR_QUOTE = re.compile("[\n\"'`]")
+
+#: The characters that can separate an id from its values or open a quoted string.
+_COLON_OR_QUOTE = re.compile("[:\"'`]")
+
+#: A run of opening parentheses, a run of closing ones, or a character that can
+#: open a quoted string.
+_PAREN_RUN_OR_QUOTE = re.compile("\\(+|\\)+|[\"'`]")
+
 
 class ParseError(Exception):
-    """Exception raised when parsing fails."""
+    """
+    Exception raised when parsing fails.
+
+    An error that points at a place in the document carries that place:
+    ``offset`` (characters from the start of the document), ``line`` and
+    ``column`` (both counted from 1), and ``line_text`` (the offending line as
+    written, without its line ending); for any other error they are None.
+
+    A document nested deeper than the parser's ``max_depth`` is refused with
+    this error too; then ``max_depth`` says how deep the nesting may go. It is
+    None for any other error.
+    """
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        offset: Optional[int] = None,
+        line: Optional[int] = None,
+        column: Optional[int] = None,
+        line_text: Optional[str] = None,
+        max_depth: Optional[int] = None,
+    ):
+        super().__init__(message)
+        self.offset = offset
+        self.line = line
+        self.column = column
+        self.line_text = line_text
+        self.max_depth = max_depth
+
+    @classmethod
+    def nesting_too_deep(cls, document: str, offset: int, max_depth: int) -> "ParseError":
+        """The error for a document nested deeper than ``max_depth`` at ``offset``."""
+        line, column, line_text = _locate(document, offset)
+        summary = f"line {line}, column {column}: nesting depth exceeds the maximum of {max_depth}"
+        return cls(
+            f"Nesting too deep at {summary}\n{_quote(line, line_text, column)}",
+            offset=offset,
+            line=line,
+            column=column,
+            line_text=line_text,
+            max_depth=max_depth,
+        )
+
+
+def _locate(document: str, offset: int) -> Tuple[int, int, str]:
+    """
+    The line and column ``offset`` falls on, both counted from 1, and that line
+    without its line ending. CR, LF and CRLF all end a line.
+    """
+    offset = max(0, min(offset, len(document)))
+    line = 1
+    line_start = 0
+    cursor = 0
+    while cursor < offset:
+        character = document[cursor]
+        cursor += 1
+        if character == "\r":
+            line += 1
+            if cursor < offset and document[cursor] == "\n":
+                cursor += 1
+            line_start = cursor
+        elif character == "\n":
+            line += 1
+            line_start = cursor
+    line_end = len(document)
+    for ending in ("\r", "\n"):
+        found = document.find(ending, line_start)
+        if 0 <= found < line_end:
+            line_end = found
+    return line, offset - line_start + 1, document[line_start:line_end]
+
+
+def _quote(number: int, line_text: str, column: int) -> str:
+    """
+    The offending line with a caret under the offending column, quoted the way
+    a compiler quotes source. A long line is shown as a window around the caret.
+    """
+    quoted, column = _window_around(line_text, column)
+    gutter = " " * len(str(number))
+    return f"{number} | {quoted}\n{gutter} | {' ' * (column - 1)}^"
+
+
+def _window_around(line_text: str, column: int) -> Tuple[str, int]:
+    """
+    Cut a line down to a window around ``column``, and say which column the
+    offending character sits at in that window. Both columns count from 1.
+    """
+    if len(line_text) <= _QUOTED_LINE_WIDTH:
+        return line_text, column
+
+    target = column - 1
+    last_start = len(line_text) - _QUOTED_LINE_WIDTH
+    start = min(max(target - _QUOTED_LINE_WIDTH // 2, 0), last_start)
+    end = start + _QUOTED_LINE_WIDTH
+    quoted = (_ELLIPSIS if start > 0 else "") + line_text[start:end] + (_ELLIPSIS if end < len(line_text) else "")
+    shift = len(_ELLIPSIS) if start > 0 else 0
+    return quoted, target - start + shift + 1
 
 
 class Parser:
@@ -26,7 +146,7 @@ class Parser:
     def __init__(
         self,
         max_input_size: int = 10 * 1024 * 1024,
-        max_depth: int = 1000,
+        max_depth: int = DEFAULT_MAX_DEPTH,
         comments: bool = True,
     ):
         """
@@ -34,7 +154,10 @@ class Parser:
 
         Args:
             max_input_size: Maximum input size in bytes (default: 10MB)
-            max_depth: Maximum nesting depth (default: 1000)
+            max_depth: How deep links may nest (default: 64). Every
+                parenthesized group and every indentation level is one level,
+                and the lines of a document are at level 0; a document nested
+                deeper is refused with a ParseError whose ``max_depth`` is set
             comments: Whether ``#`` starts a comment that runs to the end of
                 its line; when False it is an ordinary character (default: True)
         """
@@ -42,7 +165,15 @@ class Parser:
         self.pos = 0
         self.text = ""
         self.lines = []
+        self.line_offsets: List[int] = []
         self.base_indentation = None
+        # The document as written, for quoting the offending line in an error
+        self.source = ""
+        # Depth of the lines at level 0 of the context being parsed: the number
+        # of parenthesized groups around it
+        self.context_depth = 0
+        # Depth of the line being parsed
+        self.depth = 0
         self.max_input_size = max_input_size
         self.max_depth = max_depth
         self.comments = comments
@@ -58,7 +189,8 @@ class Parser:
             List of parsed Link objects
 
         Raises:
-            ParseError: If parsing fails
+            ParseError: If parsing fails, including when the document nests
+                links deeper than ``max_depth``
             TypeError: If input is not a string
             ValueError: If input exceeds maximum size
         """
@@ -79,11 +211,14 @@ class Parser:
             prepared = strip_comments(input_text) if self.comments else input_text
 
             self.text = prepared
+            self.source = input_text
             # Use smart line splitting that respects quoted strings
-            self.lines = self._split_lines_respecting_quotes(prepared)
+            self.lines, self.line_offsets = self._split_lines_respecting_quotes(prepared, 0)
             self.pos = 0
             self.indentation_stack = [0]
             self.base_indentation = None
+            self.context_depth = 0
+            self.depth = 0
 
             raw_result = self._parse_document()
             return self._transform_result(raw_result)
@@ -96,6 +231,13 @@ class Parser:
         except (KeyError, IndexError, AttributeError) as e:
             # Catch specific parsing-related exceptions
             raise ParseError(f"Parse error: {str(e)}") from e
+        except RecursionError:
+            # Only reachable with a max_depth set higher than Python's recursion
+            # limit allows; the default is far below it.
+            raise ParseError(
+                "Parse error: the document is nested too deeply for Python's recursion limit; "
+                f"lower max_depth (currently {self.max_depth}) to refuse it with a located error"
+            ) from None
 
     def _skip_quoted_string(self, text: str, start: int) -> int:
         """
@@ -107,7 +249,7 @@ class Parser:
         parsed = _parse_quoted_string_at(text, start)
         return -1 if parsed is None else parsed[1]
 
-    def _split_lines_respecting_quotes(self, text: str) -> List[str]:
+    def _split_lines_respecting_quotes(self, text: str, base: int) -> Tuple[List[str], List[int]]:
         """
         Split text into lines, but preserve newlines inside quoted strings
         and handle multiline parenthesized expressions.
@@ -115,47 +257,47 @@ class Parser:
         Quoted strings can span multiple lines, and newlines within them
         should be preserved as part of the string value. Also, parenthesized
         expressions that span multiple lines are kept together.
+
+        Returns the lines and where each of them starts in the document, given
+        that text starts at ``base``.
         """
         lines = []
-        current_line = ""
+        offsets = []
+        line_start = 0
+        # Parentheses are counted in bulk between the characters that matter
+        # here, so a long run of them costs one pass in C rather than a Python
+        # step per character.
         paren_depth = 0
-        i = 0
-
-        while i < len(text):
-            char = text[i]
+        counted = 0
+        position = 0
 
-            if char in ('"', "'", "`"):
-                end = self._skip_quoted_string(text, i)
-                if end > i:
-                    # A quoted string is opaque: newlines inside it are content
-                    current_line += text[i:end]
-                    i = end
-                    continue
-                current_line += char
-            elif char == "(":
-                paren_depth += 1
-                current_line += char
-            elif char == ")":
-                paren_depth -= 1
-                current_line += char
-            elif char == "\n":
-                if paren_depth > 0:
-                    # Inside unclosed parens: preserve the newline
-                    current_line += char
-                else:
-                    # Parentheses balanced: this is a line break
-                    lines.append(current_line)
-                    current_line = ""
+        while True:
+            found = _LINE_BREAK_OR_QUOTE.search(text, position)
+            if found is None:
+                break
+            i = found.start()
+            paren_depth += text.count("(", counted, i) - text.count(")", counted, i)
+
+            if text[i] == "\n":
+                # Inside unclosed parens the newline is preserved; with the
+                # parentheses balanced it is a line break
+                if paren_depth <= 0:
+                    lines.append(text[line_start:i])
+                    offsets.append(base + line_start)
+                    line_start = i + 1
+                position = i + 1
             else:
-                current_line += char
-
-            i += 1
+                # A quoted string is opaque: newlines inside it are content
+                end = self._skip_quoted_string(text, i)
+                position = end if end > i else i + 1
+            counted = position
 
         # Add the last line if non-empty
-        if current_line:
-            lines.append(current_line)
+        if line_start < len(text):
+            lines.append(text[line_start:])
+            offsets.append(base + line_start)
 
-        return lines
+        return lines, offsets
 
     def _parse_document(self) -> List[Dict]:
         """Parse the entire document."""
@@ -165,7 +307,7 @@ class Parser:
         while self.pos < len(self.lines):
             line = self.lines[self.pos]
             if line.strip():  # Skip empty lines
-                element = self._parse_element(0)
+                element = self._parse_element(0, 0)
                 if element:
                     links.append(element)
             else:
@@ -173,8 +315,13 @@ class Parser:
 
         return links
 
-    def _parse_element(self, current_indent: int) -> Optional[Dict]:
-        """Parse a single element (link or reference) at given indentation."""
+    def _parse_element(self, current_indent: int, level: int) -> Optional[Dict]:
+        """
+        Parse a single element (link or reference) at given indentation.
+
+        ``level`` is the number of indentation levels the element sits at in
+        the context being parsed.
+        """
         if self.pos >= len(self.lines):
             return None
 
@@ -196,14 +343,18 @@ class Parser:
             self.pos += 1
             return None
 
+        content_offset = self.line_offsets[self.pos] + len(line) - len(line.lstrip())
         self.pos += 1
 
         # Try to parse the line
-        element = self._parse_line_content(content)
+        line_depth = self.context_depth + level
+        self.depth = line_depth
+        element = self._parse_line_content(content, content_offset)
+        # Only a line that parsed counts, as in the other implementations
+        self._check_depth(line_depth, content_offset)
 
         # Check for children (indented lines that follow)
         children = []
-        child_indent = indent + 2  # Expect at least 2 spaces for child
 
         while self.pos < len(self.lines):
             # A line holding nothing does not close a block: the block goes on
@@ -226,7 +377,9 @@ class Parser:
 
             # This is a child
             self.pos = following
-            child = self._parse_element(child_indent if not children else indent + 2)
+            # A child only has to be indented deeper than its parent; asking
+            # for more left a line indented by a single space unread forever.
+            child = self._parse_element(indent + 1, level + 1)
             if child:
                 children.append(child)
 
@@ -235,11 +388,19 @@ class Parser:
 
         return element
 
-    def _parse_line_content(self, content: str) -> Dict:
-        """Parse the content of a single line."""
+    def _check_depth(self, depth: int, offset: int) -> None:
+        """
+        Refuse, for good, links at ``depth`` when that is deeper than the
+        parser allows. ``offset`` is where the level that is too deep opens.
+        """
+        if depth > self.max_depth:
+            raise ParseError.nesting_too_deep(self.source, offset, self.max_depth)
+
+    def _parse_line_content(self, content: str, offset: int) -> Dict:
+        """Parse the content of a single line, which starts at ``offset``."""
         # A whole parenthesized group: (id: values), (values) or a nested document
         if content.startswith("(") and self._find_matching_paren(content, 0) == len(content) - 1:
-            return self._parse_parenthesized(content[1:-1])
+            return self._parse_parenthesized(content[1:-1], offset)
 
         # Try indented ID syntax: id:
         if content.endswith(":"):
@@ -251,69 +412,92 @@ class Parser:
         colon_pos = self._find_colon_outside_quotes(content)
         if colon_pos >= 0:
             id_part = content[:colon_pos].strip()
-            values_part = content[colon_pos + 1 :].strip()
+            after_colon = content[colon_pos + 1 :]
+            values_part = after_colon.strip()
+            values_offset = offset + colon_pos + 1 + len(after_colon) - len(after_colon.lstrip())
             ref = self._extract_reference(id_part)
-            values = self._parse_values(values_part)
+            values = self._parse_values(values_part, values_offset)
             return {"id": ref, "values": values}
 
         # Simple value list
-        values = self._parse_values(content)
+        values = self._parse_values(content, offset)
         return {"values": values}
 
-    def _parse_parenthesized(self, inner: str) -> Dict:
+    def _parse_parenthesized(self, inner: str, offset: int) -> Dict:
         """
-        Parse the content of a parenthesized group.
+        Parse the content of a parenthesized group opened at ``offset``.
 
         The group opens a nested context that starts fresh at indentation level
         zero and follows exactly the rules used at the root of the document, so
-        line breaks separate links and indentation nests them.
+        line breaks separate links and indentation nests them. The group is one
+        level deeper than the line it is written on.
         """
-        return {"nested": self._parse_nested_document(inner)}
+        self._check_depth(self.depth + 1, offset)
+        return {"nested": self._parse_nested_document(inner, offset + 1)}
 
-    def _parse_nested_document(self, inner: str) -> List[Dict]:
-        """Parse the text of a parenthesized group as a document of its own."""
+    def _parse_nested_document(self, inner: str, offset: int) -> List[Dict]:
+        """
+        Parse the text of a parenthesized group, which starts at ``offset``,
+        as a document of its own.
+        """
         saved_lines = self.lines
+        saved_line_offsets = self.line_offsets
         saved_pos = self.pos
         saved_base_indentation = self.base_indentation
         saved_indentation_stack = self.indentation_stack
+        saved_context_depth = self.context_depth
+        saved_depth = self.depth
         try:
-            self.lines = self._split_lines_respecting_quotes(inner)
+            self.lines, self.line_offsets = self._split_lines_respecting_quotes(inner, offset)
             self.pos = 0
             self.base_indentation = None
             self.indentation_stack = [0]
+            self.context_depth = self.depth + 1
             return self._parse_document()
         finally:
             self.lines = saved_lines
+            self.line_offsets = saved_line_offsets
             self.pos = saved_pos
             self.base_indentation = saved_base_indentation
             self.indentation_stack = saved_indentation_stack
+            self.context_depth = saved_context_depth
+            self.depth = saved_depth
 
     def _find_matching_paren(self, text: str, start: int) -> int:
         """
         Find the position of the parenthesis closing the one at start.
 
         Quoted strings are skipped, so parentheses inside them are ignored.
-        Returns -1 when the group is not closed.
-        """
-        depth = 0
-        i = start
+        Returns -1 when the group is not closed, or when start is not at an
+        opening parenthesis.
 
-        while i < len(text):
-            char = text[i]
-            if char in ('"', "'", "`"):
-                end = self._skip_quoted_string(text, i)
-                if end > i:
-                    i = end
-                    continue
-            elif char == "(":
-                depth += 1
-            elif char == ")":
-                depth -= 1
-                if depth == 0:
-                    return i
-            i += 1
+        A run of parentheses is taken in one step, so the parentheses deeply
+        nested groups begin and end with cost a step per run rather than one
+        per character: every group is scanned once for each group around it.
+        """
+        if not text.startswith("(", start):
+            return -1
 
-        return -1
+        depth = 0
+        position = start
+
+        while True:
+            for found in _PAREN_RUN_OR_QUOTE.finditer(text, position):
+                run_start, run_end = found.span()
+                char = text[run_start]
+                if char == "(":
+                    depth += run_end - run_start
+                elif char == ")":
+                    if run_end - run_start >= depth:
+                        return run_start + depth - 1
+                    depth -= run_end - run_start
+                else:
+                    end = self._skip_quoted_string(text, run_start)
+                    if end > run_start:
+                        position = end
+                        break
+            else:
+                return -1
 
     def _find_colon_outside_quotes(self, text: str) -> int:
         """
@@ -325,28 +509,28 @@ class Parser:
         because it's inside the second parenthesized expression.
         """
         paren_depth = 0
-        i = 0
-
-        while i < len(text):
-            char = text[i]
-            if char in ('"', "'", "`"):
+        counted = 0
+        position = 0
+
+        while True:
+            found = _COLON_OR_QUOTE.search(text, position)
+            if found is None:
+                return -1
+            i = found.start()
+            paren_depth += text.count("(", counted, i) - text.count(")", counted, i)
+
+            if text[i] == ":":
+                if paren_depth == 0:
+                    # Only return colon if it's outside quotes AND at parenthesis depth 0
+                    return i
+                position = i + 1
+            else:
                 end = self._skip_quoted_string(text, i)
-                if end > i:
-                    i = end
-                    continue
-            elif char == "(":
-                paren_depth += 1
-            elif char == ")":
-                paren_depth -= 1
-            elif char == ":" and paren_depth == 0:
-                # Only return colon if it's outside quotes AND at parenthesis depth 0
-                return i
-            i += 1
-
-        return -1
+                position = end if end > i else i + 1
+            counted = position
 
-    def _parse_values(self, text: str) -> List[Dict]:
-        """Parse a space-separated list of values."""
+    def _parse_values(self, text: str, offset: int) -> List[Dict]:
+        """Parse a space-separated list of values, which starts at ``offset``."""
         if not text:
             return []
 
@@ -363,7 +547,7 @@ class Parser:
             # Try to extract the next value
             value_end, value_text = self._extract_next_value(text, i)
             if value_text and value_text.strip():
-                values.append(self._parse_value(value_text))
+                values.append(self._parse_value(value_text, offset + i))
             if value_end == i:
                 # No progress made - skip this character to avoid infinite loop
                 i += 1
@@ -414,11 +598,11 @@ class Parser:
 
         return (i, text[start:i])
 
-    def _parse_value(self, value: str) -> Dict:
-        """Parse a single value (could be a reference or nested link)."""
+    def _parse_value(self, value: str, offset: int) -> Dict:
+        """Parse a single value (could be a reference or nested link) starting at ``offset``."""
         # Nested link in parentheses
         if value.startswith("(") and self._find_matching_paren(value, 0) == len(value) - 1:
-            return self._parse_parenthesized(value[1:-1])
+            return self._parse_parenthesized(value[1:-1], offset)
 
         # Simple reference
         ref = self._extract_reference(value)

{links_notation-0.21.2 → links_notation-0.22.0}/links_notation/stream_parser.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 from typing import AsyncIterable, AsyncIterator, Callable, Iterable, Iterator, List, Optional
 
 from .link import Link
-from .parser import ParseError, Parser
+from .parser import DEFAULT_MAX_DEPTH, ParseError, Parser
 from .quotes import QUOTE_CHARS, _parse_quoted_string_at
 
 
@@ -19,14 +19,22 @@ class StreamPosition:
 
 
 class StreamParseError(ParseError):
-    """A canonical parse error located within the complete stream."""
+    """A canonical parse error located within the complete stream.
+
+    ``error`` is the error the parser raised for the buffered record;
+    ``offset``, ``line`` and ``column`` locate it within the complete stream.
+    """
 
     def __init__(self, error: Exception, offset: int, line: int, column: int):
-        super().__init__(f"Stream parse error at line {line}, column {column}: {error}")
+        super().__init__(
+            f"Stream parse error at line {line}, column {column}: {error}",
+            offset=offset,
+            line=line,
+            column=column,
+            line_text=getattr(error, "line_text", None),
+            max_depth=getattr(error, "max_depth", None),
+        )
         self.error = error
-        self.offset = offset
-        self.line = line
-        self.column = column
 
 
 class StreamParser:
@@ -45,8 +53,9 @@ class StreamParser:
         collect: bool = True,
         max_buffer_size: Optional[int] = None,
         comments: bool = True,
+        max_depth: int = DEFAULT_MAX_DEPTH,
     ):
-        self.parser = parser or Parser(comments=comments)
+        self.parser = parser or Parser(comments=comments, max_depth=max_depth)
         self.on_link = on_link
         self.collect = collect
         self.max_buffer_size = self.parser.max_input_size if max_buffer_size is None else max_buffer_size
@@ -95,7 +104,7 @@ class StreamParser:
             try:
                 links = self.parser.parse(document)
             except Exception as error:
-                raise StreamParseError(error, self._segment_offset, self._segment_line, 1) from error
+                raise self._stream_error(error) from error
             self._publish(links, emitted)
             self._advance_segment(document)
 
@@ -164,6 +173,15 @@ class StreamParser:
             if self.on_link is not None:
                 self.on_link(link)
 
+    def _stream_error(self, error: Exception) -> StreamParseError:
+        """Locate an error the parser raised for the buffered record within the stream."""
+        line = getattr(error, "line", None)
+        column = getattr(error, "column", None)
+        offset = getattr(error, "offset", None)
+        if line is None or column is None or offset is None:
+            return StreamParseError(error, self._segment_offset, self._segment_line, 1)
+        return StreamParseError(error, self._segment_offset + offset, self._segment_line + line - 1, column)
+
     def _advance_segment(self, document: str) -> None:
         self._segment_offset += len(document)
         self._segment_line += document.count("\n")

{links_notation-0.21.2 → links_notation-0.22.0/links_notation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: links-notation
-Version: 0.21.2
+Version: 0.22.0
 Summary: Python implementation of the Links Notation parser
 Author-email: "Link.Foundation" <drakonard@gmail.com>
 License-Expression: Unlicense
@@ -140,9 +140,42 @@ stream also exposes `position`, `drain()`, `reset()`, and a buffer-size limit.
 
 The main parser class for Links Notation.
 
-- `__init__(..., comments: bool = True)`: Create a parser; with `comments=False`
-  a `#` is an ordinary character instead of the start of a comment
-- `parse(input_text: str) -> List[Link]`: Parse Links Notation text into Link objects
+- `__init__(max_input_size: int = 10 * 1024 * 1024, max_depth: int = DEFAULT_MAX_DEPTH, comments: bool = True)`:
+  Create a parser; with `comments=False` a `#` is an ordinary character instead
+  of the start of a comment
+- `parse(input_text: str) -> List[Link]`: Parse Links Notation text into Link
+  objects; raises `ParseError` when the text does not parse or nests links
+  deeper than `max_depth`
+- `DEFAULT_MAX_DEPTH`: The default `max_depth`, 64, the same in every
+  implementation
+
+`max_depth` is how deep links may nest (default: 64). Every parenthesized group
+and every indentation level is one level, and the lines of a document start at
+level 0, so with `max_depth=1` `(a)` is accepted while `((a))`, `(a (b))` and a
+group on an indented line are refused. A document nested deeper is refused with
+a `ParseError` rather than recursed into until Python's recursion limit is hit.
+
+### ParseError
+
+Raised when parsing fails. When a document nests links deeper than
+`max_depth`, it points at the group or the line that is one level too deep:
+
+```text
+Nesting too deep at line 1, column 4: nesting depth exceeds the maximum of 3
+1 | ((((a))))
+  |    ^
+```
+
+- `max_depth`: The deepest nesting the parser accepts, when the document nests
+  deeper; `None` for any other error
+- `line`, `column`: Where the offending group or line starts, counted from 1
+- `offset`: The same position as a character offset from the start of the
+  document
+- `line_text`: The offending line, as written
+
+`StreamParser` reports the same error as a `StreamParseError` whose `error` is
+the `ParseError` and whose `line`, `column` and `offset` are counted from the
+start of the stream.
 
 ### Link
 

{links_notation-0.21.2 → links_notation-0.22.0}/links_notation.egg-info/SOURCES.txt

@@ -34,5 +34,6 @@ tests/test_multiline_quoted_string.py
 tests/test_nested_indentation.py
 tests/test_nested_parser.py
 tests/test_nested_self_reference.py
+tests/test_nesting_limit.py
 tests/test_single_line_parser.py
 tests/test_stream_parser.py

{links_notation-0.21.2 → links_notation-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "links-notation"
-version = "0.21.2"
+version = "0.22.0"
 description = "Python implementation of the Links Notation parser"
 readme = "README.md"
 license = "Unlicense"

links_notation-0.22.0/tests/test_nesting_limit.py

@@ -0,0 +1,137 @@
+"""Links nested too deeply are refused with an error rather than recursed into
+until the stack overflows
+(https://github.com/link-foundation/links-notation/issues/315).
+
+Every parenthesized group and every indentation level is one level, and the
+lines of a document start at level 0. The positions asserted here are the ones
+the Rust port reports for the same input.
+"""
+
+import sys
+
+import pytest
+
+from links_notation import DEFAULT_MAX_DEPTH, ParseError, Parser, StreamParser
+from links_notation.stream_parser import StreamParseError
+
+
+def parens(depth):
+    return "(" * depth + "a" + ")" * depth
+
+
+def values(depth):
+    return "(a " * depth + "b" + ")" * depth
+
+
+def indentation(depth):
+    return "".join(" " * level + "a\n" for level in range(depth + 1))
+
+
+def too_deep(document, max_depth):
+    with pytest.raises(ParseError) as caught:
+        Parser(max_depth=max_depth).parse(document)
+    assert caught.value.max_depth == max_depth
+    return caught.value
+
+
+def accepted(document, max_depth=DEFAULT_MAX_DEPTH):
+    return len(Parser(max_depth=max_depth).parse(document)) > 0
+
+
+def test_default_limit_is_shared_by_every_implementation():
+    assert DEFAULT_MAX_DEPTH == 64
+    assert Parser().max_depth == DEFAULT_MAX_DEPTH
+    assert StreamParser().parser.max_depth == DEFAULT_MAX_DEPTH
+
+
+def test_parentheses_up_to_the_limit_are_accepted():
+    assert accepted(parens(3), 3)
+    assert accepted(values(3), 3)
+    assert accepted(parens(DEFAULT_MAX_DEPTH))
+
+
+def test_parentheses_past_the_limit_are_refused_at_the_group_that_is_too_deep():
+    error = too_deep(parens(4), 3)
+
+    assert (error.line, error.column, error.offset) == (1, 4, 3)
+    assert str(error) == (
+        "Nesting too deep at line 1, column 4: nesting depth exceeds the maximum of 3\n" "1 | ((((a))))\n" "  |    ^"
+    )
+
+
+def test_groups_in_value_position_count_like_any_other_group():
+    error = too_deep(values(4), 3)
+
+    assert (error.line, error.column) == (1, 10)
+
+
+def test_indentation_up_to_the_limit_is_accepted():
+    assert accepted(indentation(3), 3)
+    assert accepted(indentation(DEFAULT_MAX_DEPTH))
+
+
+def test_indentation_past_the_limit_is_refused_at_the_line_that_is_too_deep():
+    error = too_deep(indentation(4), 3)
+
+    assert (error.line, error.column) == (5, 5)
+    assert error.line_text == "    a"
+
+
+def test_groups_and_indentation_add_up():
+    # `(b)` on the line indented once is at level 2.
+    assert accepted("a\n  (b)\n", 2)
+    error = too_deep("a\n  (b)\n", 1)
+
+    assert (error.line, error.column) == (2, 3)
+
+
+def test_limit_of_one_allows_one_group():
+    assert accepted("(a b)", 1)
+    assert accepted("a\n  b\n", 1)
+    too_deep("((a))", 1)
+    too_deep("a\n  b\n    c\n", 1)
+
+
+def test_trailing_spaces_on_a_deep_line_are_not_a_deeper_line():
+    assert accepted("a\n  b\n    c   \n", 2)
+
+
+def test_limit_past_the_recursion_limit_is_an_error_rather_than_a_crash():
+    # Nothing here is too deep for the limit, so the error has no max_depth.
+    with pytest.raises(ParseError) as caught:
+        Parser(max_depth=sys.maxsize).parse(parens(100_000))
+
+    assert caught.value.max_depth is None
+    assert not str(caught.value).startswith("Nesting too deep")
+
+
+def test_parser_is_reusable_after_refusing_a_document():
+    parser = Parser(max_depth=2)
+    with pytest.raises(ParseError):
+        parser.parse(parens(3))
+
+    assert parser.parse(parens(2))
+    assert parser.parse(indentation(2))
+
+
+@pytest.mark.timeout(30)
+def test_refuses_a_document_far_past_the_limit_without_overflowing_the_stack():
+    # Before the limit existed each of these exhausted Python's recursion limit.
+    # Each group around the one too deep is scanned to its end before it is
+    # entered, so refusing values(n) reads the document once per level; it is
+    # kept short enough to be refused quickly.
+    for document in (parens(100_000), values(5_000), indentation(2_000)):
+        error = too_deep(document, DEFAULT_MAX_DEPTH)
+        assert str(error).startswith("Nesting too deep at ")
+
+
+def test_stream_parser_reports_where_the_nesting_is_too_deep():
+    stream = StreamParser(max_depth=1)
+    stream.write("a\nb ((c))\n")
+
+    with pytest.raises(StreamParseError) as caught:
+        stream.finish()
+
+    assert caught.value.error.max_depth == 1
+    assert caught.value.max_depth == 1
+    assert (caught.value.line, caught.value.column, caught.value.offset) == (2, 4, 5)