From 8c14542d5eb833e9f88fd9c9547c7782d150fb97 Mon Sep 17 00:00:00 2001 From: Rahul Ranjan Date: Wed, 28 Oct 2026 15:00:52 +0530 Subject: [PATCH 1/4] fix(parser): unescape backslash pairs before the character after them _unescape_char applied its replacements as a sequential str.replace chain with "\\\\" collapsed last, so in a serialized value like C:\\numbers the "\\n" rule consumed the second backslash of the escaped-backslash pair first and turned the value into C:\ + a newline + "umbers". The function is documented as reversing _escape_char, but the round trip corrupted any value in which a literal backslash is followed by "n" or "N". Unescape in one left-to-right pass with a compiled alternation, the same approach unescape_backslash already uses, so a "\\" pair is consumed as a unit before the character after it is considered. Fixes #2041 Co-authored-by: rahul05ranjan <11793455+rahul05ranjan@users.noreply.github.com> --- news/2041.bugfix | 1 + src/icalendar/parser/string.py | 61 ++++++++++++++++++++--------- src/icalendar/tests/test_parsing.py | 23 +++++++++++ 3 files changed, 66 insertions(+), 19 deletions(-) create mode 100644 news/2041.bugfix diff --git a/news/2041.bugfix b/news/2041.bugfix new file mode 100644 index 000000000..57ed49aae --- /dev/null +++ b/news/2041.bugfix @@ -0,0 +1 @@ +Fix ``_unescape_char`` corrupting a serialized escaped backslash followed by "n"/"N": the backslash pair is now consumed in a single left-to-right pass, so unescaping a serialized ``C:\\numbers`` yields ``C:\numbers`` again and round-trips with ``_escape_char``. @rahul05ranjan diff --git a/src/icalendar/parser/string.py b/src/icalendar/parser/string.py index 52e57bf42..f3dd41b84 100644 --- a/src/icalendar/parser/string.py +++ b/src/icalendar/parser/string.py @@ -61,6 +61,33 @@ def _escape_char(text: str | bytes) -> str: ) +# The order of the alternatives is irrelevant: the substitution scans the +# text once, left to right, so an escaped backslash ("\\\\") is consumed as +# a pair before the character after it can be mistaken for an escape. This is +# what makes a literal backslash followed by "n" or "N" survive -- the +# sequential str.replace chain did not, and a serialized "C:\\\\numbers" +# (the _escape_char form of "C:\\numbers") came back as "C:\\" + a newline +# + "umbers" instead of "C:\\numbers". +_UNESCAPE_CHAR_REGEX = re.compile(r"\r\n|\\N|\\n|\\\\|\\,|\\;") +_UNESCAPE_CHAR_BYTES_REGEX = re.compile(rb"\r\n|\\N|\\n|\\\\|\\,|\\;") +_UNESCAPE_CHAR_REPLACEMENTS = { + "\r\n": "\n", + "\\N": "\n", + "\\n": "\n", + "\\\\": "\\", + "\\,": ",", + "\\;": ";", +} +_UNESCAPE_CHAR_BYTES_REPLACEMENTS = { + b"\r\n": b"\n", + b"\\N": b"\n", + b"\\n": b"\n", + b"\\\\": b"\\", + b"\\,": b",", + b"\\;": b";", +} + + def _unescape_char(text: str | bytes) -> str | bytes: r"""Unescape iCalendar TEXT values. @@ -77,34 +104,30 @@ def _unescape_char(text: str | bytes) -> str | bytes: TypeError: If ``text`` is neither ``str`` nor ``bytes``. Note: - The replacement order is critical to avoid double-unescaping: + The text is scanned once, left to right, so every backslash pair + (``\\\\`` -> ``\\``) is consumed as a unit before the character + after it is considered. With sequential replacements instead, a + literal backslash followed by "n" or "N" was corrupted into a + newline: ``\\\\numbers`` (the escaped form of ``\\numbers``) + became ``\\`` + a newline + ``umbers``. + + Conversions performed, in scan order: - 1. ``\N`` -> ``\n`` (intermediate step) - 2. ``\r\n`` -> ``\n`` (normalize line endings) + 1. ``\N`` -> ``\n`` (normalize the uppercase newline escape) + 2. ``\r\n`` -> ``\n`` (normalize raw line endings) 3. ``\n`` -> newline (unescape newlines) 4. ``\,`` -> ``,`` (unescape commas) 5. ``\;`` -> ``;`` (unescape semicolons) - 6. ``\\`` -> ``\`` (unescape backslashes last) + 6. ``\\`` -> ``\`` (unescape backslashes) """ if not isinstance(text, (str, bytes)): raise TypeError(f"Expected str or bytes, got {type(text).__name__}") - # NOTE: ORDER MATTERS! if isinstance(text, str): - return ( - text.replace("\\N", "\\n") - .replace("\r\n", "\n") - .replace("\\n", "\n") - .replace("\\,", ",") - .replace("\\;", ";") - .replace("\\\\", "\\") + return _UNESCAPE_CHAR_REGEX.sub( + lambda match: _UNESCAPE_CHAR_REPLACEMENTS[match.group(0)], text ) - return ( - text.replace(b"\\N", b"\\n") - .replace(b"\r\n", b"\n") - .replace(b"\\n", b"\n") - .replace(b"\\,", b",") - .replace(b"\\;", b";") - .replace(b"\\\\", b"\\") + return _UNESCAPE_CHAR_BYTES_REGEX.sub( + lambda match: _UNESCAPE_CHAR_BYTES_REPLACEMENTS[match.group(0)], text ) diff --git a/src/icalendar/tests/test_parsing.py b/src/icalendar/tests/test_parsing.py index ca1cefcfc..847f9558f 100644 --- a/src/icalendar/tests/test_parsing.py +++ b/src/icalendar/tests/test_parsing.py @@ -309,6 +309,29 @@ def test_unescape_char(): assert _unescape_char(b"\\n") == b"\n" +@pytest.mark.parametrize( + ("value", "expected"), + [ + # a literal backslash before "n"/"N" must survive: the escaped-backslash + # pair is consumed as a unit before the next character is considered + (r"C:\\numbers", "C:" + chr(92) + "numbers"), + (r"C:\\Numbers", "C:" + chr(92) + "Numbers"), + # double-escaped backslash then an escaped newline + ("a" + chr(92) * 3 + "n b", "a" + chr(92) + "\n b"), + ], +) +def test_unescape_char_keeps_backslash_before_n(value, expected): + r""""unescaped backslashes are consumed as pairs, never combined with a later escape.""" + assert _unescape_char(value) == expected + assert _unescape_char(value.encode()) == expected.encode() + + +def test_unescape_char_round_trip(): + r"""_unescape_char must reverse _escape_char for text with backslashes.""" + original = "Read C:" + chr(92) + "numbers.csv first" + assert _unescape_char(_escape_char(original)) == original + + @pytest.mark.parametrize( ("value", "expected"), [ From f447218732cc34f1dbe29eea04b2cb4c59704ca8 Mon Sep 17 00:00:00 2001 From: Rahul Date: Fri, 30 Oct 2026 11:19:38 +0530 Subject: [PATCH 2/4] Fix docstring formatting flagged by ruff format Co-authored-by: rahul05ranjan <11793455+rahul05ranjan@users.noreply.github.com> --- src/icalendar/tests/test_parsing.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/icalendar/tests/test_parsing.py b/src/icalendar/tests/test_parsing.py index 847f9558f..e9d374e86 100644 --- a/src/icalendar/tests/test_parsing.py +++ b/src/icalendar/tests/test_parsing.py @@ -321,7 +321,7 @@ def test_unescape_char(): ], ) def test_unescape_char_keeps_backslash_before_n(value, expected): - r""""unescaped backslashes are consumed as pairs, never combined with a later escape.""" + r""" "unescaped backslashes are consumed as pairs, never combined with a later escape.""" assert _unescape_char(value) == expected assert _unescape_char(value.encode()) == expected.encode() From f838599cd7c40df74762db6f5f05062a9105f319 Mon Sep 17 00:00:00 2001 From: Rahul Ranjan Date: Fri, 13 Nov 2026 08:57:27 +0000 Subject: [PATCH 3/4] docs: disclose AI use for the 2041 fix per the Responsible AI use policy Model: GLM (Z.ai) model versions served via OpenRouter, as configured at the time of each commit; this session runs GLM-5.3. Use: an LLM agent (OpenClaw) operating the rahul05ranjan account analyzed the reported unescaping corruption, wrote the fix in src/icalendar/parser/string.py, added the regression tests in src/icalendar/tests/test_parsing.py, and drafted the change log entry and pull request description; each iteration ran the test suite locally before pushing. The account owner assigns the work and reviews the submissions. Output: this commit adds the AI disclosure to the change log entry; the pull request checklist item for the AI policy is checked with it. Co-authored-by: rahul05ranjan <11793455+rahul05ranjan@users.noreply.github.com> --- news/2041.bugfix | 1 + 1 file changed, 1 insertion(+) diff --git a/news/2041.bugfix b/news/2041.bugfix index 57ed49aae..bc0fcefd8 100644 --- a/news/2041.bugfix +++ b/news/2041.bugfix @@ -1 +1,2 @@ Fix ``_unescape_char`` corrupting a serialized escaped backslash followed by "n"/"N": the backslash pair is now consumed in a single left-to-right pass, so unescaping a serialized ``C:\\numbers`` yields ``C:\numbers`` again and round-trips with ``_escape_char``. @rahul05ranjan +This fix, its tests, and the pull request text were drafted with AI assistance, disclosed per icalendar's Responsible AI use policy. From 8728eadd86a57cc8620e7d6ae1ca1e297b6ff05c Mon Sep 17 00:00:00 2001 From: rahul05ranjan <11793455+rahul05ranjan@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:18:03 +0000 Subject: [PATCH 4/4] docs(news): make news/2041.bugfix a single line Co-authored-by: rahul05ranjan <11793455+rahul05ranjan@users.noreply.github.com> --- news/2041.bugfix | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/news/2041.bugfix b/news/2041.bugfix index bc0fcefd8..9d54d9c45 100644 --- a/news/2041.bugfix +++ b/news/2041.bugfix @@ -1,2 +1 @@ -Fix ``_unescape_char`` corrupting a serialized escaped backslash followed by "n"/"N": the backslash pair is now consumed in a single left-to-right pass, so unescaping a serialized ``C:\\numbers`` yields ``C:\numbers`` again and round-trips with ``_escape_char``. @rahul05ranjan -This fix, its tests, and the pull request text were drafted with AI assistance, disclosed per icalendar's Responsible AI use policy. +Fix ``_unescape_char`` corrupting a serialized escaped backslash followed by "n"/"N": the backslash pair is now consumed in a single left-to-right pass, so unescaping a serialized ``C:\\numbers`` yields ``C:\numbers`` again and round-trips with ``_escape_char``. This fix, its tests, and the pull request text were drafted with AI assistance, disclosed per icalendar's Responsible AI use policy. @rahul05ranjan