icalendar.parser.parameter module#

Functions for parsing parameters.

class icalendar.parser.parameter.HasToIcal(*args, **kwargs)[source]#

Bases: Protocol

Protocol for objects with a to_ical method.

to_ical()[source]#

Convert to iCalendar format.

Return type:: bytes

class icalendar.parser.parameter.Parameters(*args, **kwargs)[source]#

Bases: CaselessDict[str | list[str]]

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'})

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)[source]#

Parses the parameter format from ical text format.

Return type:: Self

classmethod from_jcal(jcal)[source]#: Parse jCal parameters.

classmethod from_jcal_property(jcal_property)[source]#

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.

classmethod from_xcal(element)[source]#

Parse xCal from RFC 6321.

Parameters:: element (Element | ElementAdapter) – The xCal element to parse.
Raises:: XCalParsingError – If the provided xCal is invalid.
Return type:: Parameters
Returns:: Parameters: The parsed parameters.

Example

This parses the parameters from an xCal string.

>>> from icalendar import Parameters
>>> from xml.etree.ElementTree import fromstring
>>> xcal_string = '''
... <parameters>
...     <language>
...         <text>en-US</text>
...     </language>
... </parameters>
... '''
>>> xml_element = fromstring(xcal_string)
>>> parameters = Parameters.from_xcal(xml_element)
>>> parameters['language'] == 'en-US'
True

get_multiple(key)[source]#

Get mulitple values as a list.

Note

Do not modify the list. This is only for iteration.

Return type:: list

is_utc()[source]#

Whether the TZID parameter is UTC.

Return type:: bool

params()[source]#

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

Return type:: KeysView[str]

quote_also = {'CN': " '"}#

to_ical(sorted=True)[source]#

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"

Return type:

bytes

to_jcal(exclude_utc=False)[source]#

Return the jCal representation of the parameters.

Parameters:: exclude_utc (bool) – Exclude the TZID parameter if it is UTC
Return type:: dict[str, str]

to_xcal(element)[source]#

Add the xCal representation of the parameters according to RFC 6321.

No parameters are added when they are empty or parameters are already present in the element.

Parameters:: element (Element) – The parameters are added to this element as first child.
Return type:: None

property tzid: str | None#: The TZID parameter from RFC 5545.

update_tzid_from(dt)[source]#

Update the TZID parameter from a datetime object.

This sets the TZID parameter or deletes it according to the datetime. RFC 5545 Section 3.2.19 prohibits TZID on UTC datetimes, which use the Z suffix instead.

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'})

Setter accepts:: str | None

icalendar.parser.parameter.dquote(val, always_quote=False)[source]#

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. Values ending with a backslash \ are quoted, too, because the parser would otherwise read it as escaping the following delimiter.

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.parameter.param_value(value, always_quote=False)[source]#

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.parameter.q_join(lst, sep=',', always_quote=False)[source]#

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 (Sequence[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.parameter.q_split(st, sep=',', maxsplit=-1)[source]#

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.parameter.rfc_6868_escape(param_value)#

Take care of RFC 6868 escaping.

^ -> ^^
" -> ^'
newline -> ^n

Return type:: str

icalendar.parser.parameter.rfc_6868_unescape(param_value)#

Take care of RFC 6868 unescaping.

^^ -> ^
^n -> system specific newline
^' -> "
^ with others stay intact

Return type:: str

icalendar.parser.parameter.single_string_parameter(upper=False)#

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

Parameters:: upper (bool) – Convert the return value of the property getter to uppercase.
Returns:: The property for the parameter.

icalendar.parser.parameter.validate_param_value(value, quoted=True)[source]#

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