icalendar.parser module

This module parses and generates contentlines as defined in RFC 5545 (iCalendar), but will probably work for other MIME types with similar syntax. Eg. RFC 2426 (vCard)

It is stupid in the sense that it treats the content purely as strings. No type conversion is attempted.

class icalendar.parser.Contentline(value, strict=False, encoding='utf-8')

Bases: str

A content line is basically a string that can be folded and parsed into parts.

classmethod from_ical(ical, strict=False)

Unfold the content lines in an iCalendar into long content lines.

classmethod from_parts(name, params, values, sorted=True)

Turn a parts into a content line.

parts()

Split the content line into name, parameters, and values parts.

Properly handles escaping with backslashes and double-quote sections to avoid corrupting URL-encoded characters in values.

Example with parameter:

DESCRIPTION;ALTREP="cid:part1.0001@example.org":The Fall'98 Wild

Example without parameters:

DESCRIPTION:The Fall'98 Wild

Return type:

tuple[str, Parameters, str]

strict

to_ical()

Long content lines are folded so they are less than 75 characters wide.

class icalendar.parser.Contentlines(iterable=(), /)

Bases: list

I assume that iCalendar files generally are a few kilobytes in size. Then this should be efficient. for Huge files, an iterator should probably be used instead.

classmethod from_ical(st)

Parses a string into content lines.

to_ical()

Simply join self.

class icalendar.parser.HasToIcal(*args, **kwargs)

Bases: Protocol

Protocol for objects with a to_ical method.

__init__(*args, **kwargs)

to_ical()

Convert to iCalendar format.

Return type:

bytes

class icalendar.parser.Parameters(*args, **kwargs)

Bases: CaselessDict

Parser and generator of Property parameter strings.

It knows nothing of datatypes. Its main concern is textual structure.

Examples

Modify parameters:

>>> from icalendar import Parameters
>>> params = Parameters()
>>> params['VALUE'] = 'TEXT'
>>> params.value
'TEXT'
>>> params
Parameters({'VALUE': 'TEXT'})

Create new parameters:

>>> params = Parameters(value="BINARY")
>>> params.value
'BINARY'

Set a default:

>>> params = Parameters(value="BINARY", default_value="TEXT")
>>> params
Parameters({'VALUE': 'BINARY'})

__init__(*args, **kwargs)

Create new parameters.

always_quoted = ('ALTREP', 'DELEGATED-FROM', 'DELEGATED-TO', 'DIR', 'MEMBER', 'SENT-BY', 'X-ADDRESS', 'X-TITLE', 'LINKREL')

classmethod from_ical(st, strict=False)

Parses the parameter format from ical text format.

classmethod from_jcal(jcal)

Parse jCal parameters.

classmethod from_jcal_property(jcal_property)

Create the parameters for a jCal property.

Parameters:

• jcal_property (list) -- The jCal property [name, params, value, ...]

• default_value (str, optional) -- The default value of the property. If this is given, the default value will not be set.

is_utc()

Whether the TZID parameter is UTC.

params()

In RFC 5545 keys are called parameters, so this is to be consitent with the naming conventions.

quote_also = {'CN': " '"}

to_ical(sorted=True)

Returns an RFC 5545 representation of the parameters.

Parameters:

• sorted (bool) -- Sort the parameters before encoding.

• exclude_utc (bool) -- Exclude TZID if it is set to "UTC"

to_jcal(exclude_utc=False)

Return the jCal representation of the parameters.

Parameters:

exclude_utc (bool) -- Exclude the TZID parameter if it is UTC

Return type:

dict[str, str]

property tzid: str | None

The TZID parameter from RFC 5545.

update_tzid_from(dt)

Update the TZID parameter from a datetime object.

This sets the TZID parameter or deletes it according to the datetime.

Return type:

None

property value: VALUE | str | None

The VALUE parameter from RFC 5545.

Description:

This parameter specifies the value type and format of the property value. The property values MUST be of a single value type. For example, a "RDATE" property cannot have a combination of DATE-TIME and TIME value types.

If the property's value is the default value type, then this parameter need not be specified. However, if the property's default value type is overridden by some other allowable value type, then this parameter MUST be specified.

Applications MUST preserve the value data for x-name and iana- token values that they don't recognize without attempting to interpret or parse the value data.

For convenience, using this property, the value will be converted to an uppercase string.

>>> from icalendar import Parameters
>>> params = Parameters()
>>> params.value = "unknown"
>>> params
Parameters({'VALUE': 'UNKNOWN'})

icalendar.parser.dquote(val, always_quote=False)

Enclose parameter values in double quotes when needed.

Parameter values containing special characters ,, ;, :, or ' must be enclosed in double quotes according to RFC 5545. Double-quote characters in the value are replaced with single quotes since they're forbidden in parameter values.

Parameters:

• val (str) -- The parameter value to quote.

• always_quote (bool) -- If True, always enclose in quotes regardless of content. Defaults to False (only quote when necessary).

Return type:

str

Returns:

The value, enclosed in double quotes if needed or requested.

icalendar.parser.escape_char(text)

Format value according to iCalendar TEXT escaping rules.

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.escape_string(val)

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.foldline(line, limit=75, fold_sep='\\r\\n ')

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.param_value(value, always_quote=False)

Convert a parameter value to its iCalendar representation.

Applies RFC 6868 escaping and optionally quotes the value according to RFC 5545 parameter value formatting rules.

Parameters:

• value (Sequence[str] | str | HasToIcal) -- The parameter value to convert. Can be a sequence, string, or object with a to_ical() method.

• always_quote (bool) -- If True, always enclose the value in double quotes. Defaults to False (only quote when necessary).

Return type:

str

Returns:

The formatted parameter value, escaped and quoted as needed.

icalendar.parser.q_join(lst, sep=',', always_quote=False)

Join a list with a separator, quoting items as needed.

Joins list items with the separator, applying dquote() to each item to add double quotes when they contain special characters.

Parameters:

• lst (list[str]) -- The list of items to join.

• sep (str) -- The separator to use. Defaults to ,.

• always_quote (bool) -- If True, always quote all items. Defaults to False (only quote when necessary).

Return type:

str

Returns:

The joined string with items quoted as needed.

Examples

>>> from icalendar.parser import q_join
>>> q_join(['a', 'b', 'c'])
'a,b,c'
>>> q_join(['plain', 'has,comma'])
'plain,"has,comma"'

icalendar.parser.q_split(st, sep=',', maxsplit=-1)

Split a string on a separator, respecting double quotes.

Splits the string on the separator character, but ignores separators that appear inside double-quoted sections. This is needed for parsing parameter values that may contain quoted strings.

Parameters:

• st (str) -- The string to split.

• sep (str) -- The separator character. Defaults to ,.

• maxsplit (int) -- Maximum number of splits to perform. If -1 (default), then perform all possible splits.

Return type:

list[str]

Returns:

The split string parts.

Examples

>>> from icalendar.parser import q_split
>>> q_split('a,b,c')
['a', 'b', 'c']
>>> q_split('a,"b,c",d')
['a', '"b,c"', 'd']
>>> q_split('a;b;c', sep=';')
['a', 'b', 'c']

icalendar.parser.rfc_6868_escape(param_value)

Take care of RFC 6868 escaping.

• ^ -> ^^

• " -> ^'

• newline -> ^n

Return type:

str

icalendar.parser.rfc_6868_unescape(param_value)

Take care of RFC 6868 unescaping.

• ^^ -> ^

• ^n -> system specific newline

• ^' -> "

• ^ with others stay intact

Return type:

str

icalendar.parser.single_string_parameter(func=None, upper=False)

Create a parameter getter/setter for a single string parameter.

Parameters:

• upper -- Convert the value to uppercase

• func (Callable | None) -- The function to decorate.

Returns:

The property for the parameter or a decorator for the parameter if func is None.

icalendar.parser.split_on_unescaped_comma(text)

Split text on unescaped commas and unescape each part.

Splits only on commas not preceded by backslash. After splitting, unescapes backslash sequences in each part.

Parameters:

text (str) -- Text with potential escaped commas (e.g., "foo\, bar,baz")

Return type:

list[str]

Returns:

List of unescaped category strings

Examples

>>> from icalendar.parser import split_on_unescaped_comma
>>> split_on_unescaped_comma(r"foo\, bar,baz")
['foo, bar', 'baz']
>>> split_on_unescaped_comma("a,b,c")
['a', 'b', 'c']
>>> split_on_unescaped_comma(r"a\,b\,c")
['a,b,c']
>>> split_on_unescaped_comma(r"Work,Personal\,Urgent")
['Work', 'Personal,Urgent']

icalendar.parser.split_on_unescaped_semicolon(text)

Split text on unescaped semicolons and unescape each part.

Splits only on semicolons not preceded by a backslash. After splitting, unescapes backslash sequences in each part. Used by vCard structured properties (ADR, N, ORG) per RFC 6350.

Parameters:

text (str) -- Text with potential escaped semicolons (e.g., "field1\;with;field2")

Return type:

list[str]

Returns:

List of unescaped field strings

Examples

>>> from icalendar.parser import split_on_unescaped_semicolon
>>> split_on_unescaped_semicolon(r"field1\;with;field2")
['field1;with', 'field2']
>>> split_on_unescaped_semicolon("a;b;c")
['a', 'b', 'c']
>>> split_on_unescaped_semicolon(r"a\;b\;c")
['a;b;c']
>>> split_on_unescaped_semicolon(r"PO Box 123\;Suite 200;City")
['PO Box 123;Suite 200', 'City']

icalendar.parser.unescape_backslash(val)

Unescape backslash sequences in iCalendar text.

Unlike unescape_string(), this only handles actual backslash escapes per RFC 5545, not URL encoding. This preserves URL-encoded values like %3A in URLs.

Processes backslash escape sequences in a single pass using regex matching.

icalendar.parser.unescape_char(text)

Unescape iCalendar TEXT values.

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.unescape_list_or_string(val)

Unescape a value that may be a string or list of strings.

Applies unescape_string() to the value. If the value is a list, unescapes each element.

Parameters:

val (str | list[str]) -- A string or list of strings to unescape.

Return type:

str | list[str]

Returns:

The unescaped values.

icalendar.parser.unescape_string(val)

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.validate_param_value(value, quoted=True)

Validate a parameter value for unsafe characters.

Checks parameter values for characters that are not allowed according to RFC 5545. Uses different validation rules for quoted and unquoted values.

Parameters:

• value (str) -- The parameter value to validate.

• quoted (bool) -- If True, validate as a quoted value (allows more characters). If False, validate as an unquoted value (stricter). Defaults to True.

Raises:

ValueError -- If the value contains unsafe characters for its quote state.

Return type:

None

icalendar.parser.validate_token(name)

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