Preserve RFC 7265 unknown property values verbatim

[lcampanella98]

Linked issue

• Closes [Bug] unknown value type is escaped/unescaped instead of kept verbatim, breaking round-trips #1445

Description

Values of unrecognized properties — and X- properties without a VALUE
parameter — were run through RFC 5545 TEXT escaping, so they did not round-trip
unchanged. RFC 7265 reserves the unknown value type precisely for these cases
and requires the value to be carried "without processing" (§5.1/§5.2). Treating
it as TEXT re-escapes it and, as the RFC warns, "breaks round-tripping values".

Example (before this change) — in iCal the ; gains a backslash that wasn't there; in jCal the \, loses its backslash, where RFC 7265 §5.3 gives the value as "Stenophylla;Guinea\\,Africa", preserved exactly:

>>> from icalendar.cal import Component
>>> orig = r"""BEGIN:VEVENT
UID:1
X-COFFEE-DATA:Stenophylla;Guinea\,Africa
END:VEVENT
"""
>>> ev = Component.from_ical(orig)
>>> print(ev.to_ical().decode())
BEGIN:VEVENT
UID:1
X-COFFEE-DATA:Stenophylla\;Guinea\,Africa
END:VEVENT
>>> ev.to_jcal()
['vevent', [['uid', {}, 'text', '1'], ['x-coffee-data', {}, 'unknown', 'Stenophylla;Guinea,Africa']], []]

After this change the value is preserved exactly, matching the RFC 7265 §5.3 example:

>>> print(ev.to_ical().decode())
BEGIN:VEVENT
UID:1
X-COFFEE-DATA:Stenophylla;Guinea\,Africa
END:VEVENT
>>> ev.to_jcal()
['vevent', [['uid', {}, 'text', '1'], ['x-coffee-data', {}, 'unknown', 'Stenophylla;Guinea\\,Africa']], []]

What this changes

• unknown values are now preserved verbatim when parsing, serializing, and
  converting to/from jCal. The fix skips backslash unescaping on parse and
  emits the stored value unchanged on output.
• Known types are untouched: an explicit VALUE (e.g. VALUE=TEXT) still gets
  normal TEXT escaping, and property parameters are still decoded as before.
  An unrecognized VALUE type keeps its type name so it round-trips losslessly.
• vUnknown no longer inherits from vText, so the two cannot silently share
  escaping behaviour again (per maintainer review).
• PROXIMITY (RFC 9074) is now recognized as TEXT rather than falling back to
  the unknown type — a latent gap this change surfaced. It had passed
  test_calendar_types
  only because vUnknown used to subclass vText.

Known limitation

A jCal unknown value containing a raw line break cannot be represented as a
bare iCal content line (RFC 7265 is silent here, and RFC 5545 makes it
impossible). This is only reachable from jCal input and fails loudly rather than
emitting invalid iCalendar. If a value genuinely needs a newline, it should be
declared VALUE=TEXT.

Checklist

• I've added a change log entry to /news, following the instructions in Change log entry format.
• I've added or updated tests if applicable.
• I've run and ensured all tests pass locally by following Run tests.
• I've added or edited documentation, both as docstrings to be rendered in the API documentation and narrative documentation, as necessary.

Additional information

Tests are parametrized over the affected characters and conversion directions,
and cover the VALUE boundary, unrecognized parameters, IMAGE, and the
vText/vUnknown overlap. tox -e nopytz passes.

AI disclosure: I used Claude Code (Anthropic's Claude Opus) to investigate the
bug, draft this change and its tests, and write this description. I reviewed the
output, made changes as necessary, and validated everything locally.

---

📚 Documentation preview 📚: https://icalendar--1450.org.readthedocs.build/en/1450/

[read-the-docs-community]

Documentation build overview

📚 icalendar | 🛠️ Build #33135579 | 📁 Comparing 92dbf5b against latest (78f43a6)

  🔍 Preview build  

22 files changed · ± 22 modified

± Modified

• 404.html
• genindex.html
• _modules/icalendar/attr.html
• _modules/icalendar/error.html
• reference/api/icalendar.cal.component.html
• reference/api/icalendar.error.html
• reference/api/icalendar.parser.content_line.html
• reference/api/icalendar.prop.factory.html
• reference/api/icalendar.prop.html
• reference/api/icalendar.prop.text.html
• and 12 more...

[stevepiercy]

This is exceptional work. Thank you for your effort!

Most of my suggestions are minor tweaks and clarifications, with one concern about creating a new private method instead of changing the existing one. Would you please take a look? Thank you!

[lcampanella98]

Thanks for the thorough review! Addressed your comments. There are 2 remaining open threads on the versionchanged and the class-level imports. Details in the threads.

[stevepiercy]

Thanks for making the changes, explaining choices made, and adding an example.

I'd like to add to the example, as shown, and it surfaced an issue. Would you please take a look? Thank you!

[lcampanella98]

Applied the three Example suggestions (the vText/vUnknown comparison) in one commit. I checked the combined doctest locally and it passes. Verified docs render as well.

[stevepiercy]

@lcampanella98 thank you for your contribution to improve icalendar. It's a pleasure to collaborate with you.

Important

For maintainers, please note that the version number in the docstring in the hidden and unresolved conversation is currently 7.2.0. Please leave this PR open until release, and update if necessary. Thank you!

[lcampanella98]

Happy to contribute and collaborate. Thanks for the review!