diff --git a/news/2041.bugfix b/news/2041.bugfix new file mode 100644 index 000000000..9d54d9c45 --- /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``. This fix, its tests, and the pull request text were drafted with AI assistance, disclosed per icalendar's Responsible AI use policy. @rahul05ranjan diff --git a/src/icalendar/parser/string.py b/src/icalendar/parser/string.py index 8c879dcb5..cafa2ea1b 100644 --- a/src/icalendar/parser/string.py +++ b/src/icalendar/parser/string.py @@ -55,6 +55,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. @@ -71,34 +98,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 472e467bd..31b27bbce 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"), [