Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/history.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ History and release notes
Unreleased
----------
* Fixed various type hints
* Fixed :meth:`Parser.desc` resetting the failure position of combined parsers.

2.2 - 2025-09-12
----------------
Expand Down
10 changes: 10 additions & 0 deletions docs/ref/methods_and_combinators.rst
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,16 @@ can be used and manipulated as below.
>>> year.parse('123')
ParseError: expected 4 digit year at 0:0

For a combined parser, the description replaces the expected text while
retaining the furthest failure position of its component parsers.

>>> pair = (string('a') >> string('b')).desc('a pair')
>>> pair.parse('ax')
ParseError: expected 'a pair' at 0:1

Successful results, including failure information retained from
backtracking, are unchanged.

.. method:: then(other_parser)

Returns a parser which, if the initial parser succeeds, will continue parsing
Expand Down
4 changes: 2 additions & 2 deletions src/parsy/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ def sep_by(self, sep: Parser, *, min: int = 0, max: float = float("inf")) -> Par
def desc(self, description: str) -> Parser:
"""
Returns a new parser with a description added, which is used in the error message
if parsing fails.
if parsing fails. The furthest failure position is preserved.
"""

@Parser
Expand All @@ -332,7 +332,7 @@ def desc_parser(stream: str | bytes | list, index: int) -> Result:
if result.status:
return result
else:
return Result.failure(index, description)
return Result.failure(result.furthest, description)

return desc_parser

Expand Down
74 changes: 74 additions & 0 deletions tests/test_parsy.py
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,80 @@ def thing():
self.assertEqual(ex.stream, "x")
self.assertEqual(ex.index, 0)

def test_desc_preserves_failure_location(self):
parser = (string("a") >> string("b")).desc("a pair")
with self.assertRaises(ParseError) as err:
parser.parse("ax")

self.assertEqual(err.exception.index, 1)
self.assertEqual(err.exception.expected, frozenset(["a pair"]))
self.assertEqual(str(err.exception), "expected 'a pair' at 0:1")

def test_desc_preserves_furthest_alternative(self):
parser = ((string("ab") >> string("c")) | string("z")).desc("a choice")
with self.assertRaises(ParseError) as err:
parser.parse("abx")

self.assertEqual(err.exception.index, 2)
self.assertEqual(err.exception.expected, frozenset(["a choice"]))

def test_desc_combines_alternatives_at_same_location(self):
parser = (string("a") >> string("b")).desc("a pair") | (string("a") >> string("c"))
with self.assertRaises(ParseError) as err:
parser.parse("ax")

self.assertEqual(err.exception.index, 1)
self.assertEqual(err.exception.expected, frozenset(["a pair", "c"]))

def test_desc_in_generate_preserves_line_and_column(self):
@generate
def document():
yield string("heading\n")
yield (string("a") >> string("b")).desc("a pair")

with self.assertRaises(ParseError) as err:
document.parse("heading\nax")

self.assertEqual(err.exception.index, 9)
self.assertEqual(str(err.exception), "expected 'a pair' at 1:1")

def test_generate_desc_preserves_failure_location(self):
@generate("a pair")
def pair():
yield string("a")
yield string("b")

with self.assertRaises(ParseError) as err:
pair.parse("ax")

self.assertEqual(err.exception.index, 1)
self.assertEqual(err.exception.expected, frozenset(["a pair"]))

def test_desc_preserves_bytes_and_token_locations(self):
cases = [
(string(b"a") >> string(b"b"), b"ax"),
(match_item("a") >> match_item("b"), ["a", "x"]),
]
for parser, stream in cases:
with self.subTest(stream=stream):
with self.assertRaises(ParseError) as err:
parser.desc("a pair").parse(stream)
self.assertEqual(err.exception.index, 1)
self.assertEqual(err.exception.expected, frozenset(["a pair"]))

def test_desc_preserves_success_and_backtracking(self):
parser = (string("a") >> string("b")) | string("a")
described = parser.desc("a pair or a")
for stream in ["ab", "ax", "a"]:
with self.subTest(stream=stream):
self.assertEqual(described(stream, 0), parser(stream, 0))
self.assertEqual(described.parse_partial(stream), parser.parse_partial(stream))

with self.assertRaises(ParseError) as err:
described.parse("ax")
self.assertEqual(err.exception.index, 1)
self.assertEqual(err.exception.expected, frozenset(["b", "EOF"]))

def test_generate_default_desc(self):
# We shouldn't give a default desc, the messages from the internal
# parsers should bubble up.
Expand Down