icalendar.parser.string module#

Functions for manipulating strings and bytes.

icalendar.parser.string.escape_char(text)[source]#

Format value according to iCalendar TEXT escaping rules.

Deprecated since version 7.0.0: Use the private _escape_char() internally. For external use, this function is deprecated. Please use alternative escaping methods or contact the maintainers.

Escapes special characters in text values according to RFC 5545 Section 3.3.11 rules. The order of replacements matters to avoid double-escaping.

Parameters:

text (str | bytes) – The text to escape.

Return type:

str | bytes

Returns:

The escaped text with special characters escaped.

Note

The replacement order is critical:

  1. \N -> \n (normalize newlines to lowercase)

  2. \ -> \\ (escape backslashes)

  3. ; -> \; (escape semicolons)

  4. , -> \, (escape commas)

  5. \r\n -> \n (normalize line endings)

  6. "\n" -> r"\n" (transform a newline character to a literal, or raw, newline character)

icalendar.parser.string.escape_string(val)[source]#

Escape backslash sequences to URL-encoded hex values.

Converts backslash-escaped characters to their percent-encoded hex equivalents. This is used for parameter parsing to preserve escaped characters during processing.

Parameters:

val (str) – The string with backslash escapes.

Return type:

str

Returns:

The string with backslash escapes converted to percent encoding.

Note

Conversions:

  • \, -> %2C

  • \: -> %3A

  • \; -> %3B

  • \\ -> %5C

icalendar.parser.string.foldline(line, limit=75, fold_sep='\\r\\n ')[source]#

Make a string folded as defined in RFC5545 Lines of text SHOULD NOT be longer than 75 octets, excluding the line break. Long content lines SHOULD be split into a multiple line representations using a line "folding" technique. That is, a long line can be split between any two characters by inserting a CRLF immediately followed by a single linear white-space character (i.e., SPACE or HTAB).

Return type:

str

icalendar.parser.string.unescape_char(text)[source]#

Unescape iCalendar TEXT values.

Deprecated since version 7.0.0: Use the private _unescape_char() internally. For external use, this function is deprecated. Please use alternative unescaping methods or contact the maintainers.

Reverses the escaping applied by escape_char() according to RFC 5545 Section 3.3.11 TEXT escaping rules.

Parameters:

text (str | bytes) – The escaped text.

Return type:

str | bytes | None

Returns:

The unescaped text, or None if text is neither str nor bytes.

Note

The replacement order is critical to avoid double-unescaping:

  1. \N -> \n (intermediate step)

  2. \r\n -> \n (normalize line endings)

  3. \n -> newline (unescape newlines)

  4. \, -> , (unescape commas)

  5. \; -> ; (unescape semicolons)

  6. \\ -> \ (unescape backslashes last)

icalendar.parser.string.unescape_string(val)[source]#

Unescape URL-encoded hex values to their original characters.

Reverses escape_string() by converting percent-encoded hex values back to their original characters. This is used for parameter parsing.

Parameters:

val (str) – The string with percent-encoded values.

Return type:

str

Returns:

The string with percent encoding converted to characters.

Note

Conversions:

  • %2C -> ,

  • %3A -> :

  • %3B -> ;

  • %5C -> \

icalendar.parser.string.validate_token(name)[source]#

Validate that a name is a valid iCalendar token.

Checks if the name matches the RFC 5545 token syntax using the NAME regex pattern ([\w.-]+).

Parameters:

name (str) – The token name to validate.

Raises:

ValueError – If the name is not a valid token.

Return type:

None