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

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.

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.

is_utc()[source]#: Whether the TZID parameter is UTC.

params()[source]#: In RFC 5545 keys are called parameters, so this is to be consitent with the naming conventions.

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"

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]

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

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

Enclose parameter values in double quotes when needed.

Deprecated since version 7.0.0: Use the private _dquote() internally. For external use, this function is deprecated. Please contact the maintainers if you rely on this function.

Return type:: str

icalendar.parser.parameter.param_value(value, always_quote=False)[source]#

Convert a parameter value to its iCalendar representation.

Deprecated since version 7.0.0: Use the private _param_value() internally. For external use, this function is deprecated. Please contact the maintainers if you rely on this function.

Return type:: str

icalendar.parser.parameter.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 (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)#

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

Take care of RFC 6868 escaping.

Deprecated since version 7.0.0: Use the private _rfc_6868_escape() internally. For external use, this function is deprecated. Please contact the maintainers if you rely on this function.

Return type:: str

icalendar.parser.parameter.rfc_6868_unescape(param_value)[source]#

Take care of RFC 6868 unescaping.

Deprecated since version 7.0.0: Use the private _rfc_6868_unescape() internally. For external use, this function is deprecated. Please contact the maintainers if you rely on this function.

Return type:: str

icalendar.parser.parameter.single_string_parameter(func=None, upper=False)[source]#

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.parameter.validate_param_value(value, quoted=True)[source]#

Validate a parameter value for unsafe characters.

Deprecated since version 7.0.0: Use the private _validate_param_value() internally. For external use, this function is deprecated. Please contact the maintainers if you rely on this function.

Return type:: None