icalendar.prop.cal_address module#

CAL-ADDRESS values from RFC 5545.

class icalendar.prop.cal_address.vCalAddress(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

Calendar User Address

Value Name:

CAL-ADDRESS

Purpose:

This value type is used to identify properties that contain a calendar user address.

Description:

The value is a URI as defined by [RFC3986] or any other IANA-registered form for a URI. When used to address an Internet email transport address for a calendar user, the value MUST be a mailto URI, as defined by [RFC2368].

Example

mailto: is in front of the address.

mailto:jane_doe@example.com

Parsing:

>>> from icalendar import vCalAddress
>>> cal_address = vCalAddress.from_ical('mailto:jane_doe@example.com')
>>> cal_address
vCalAddress('mailto:jane_doe@example.com')

Encoding:

>>> from icalendar import vCalAddress, Event
>>> event = Event()
>>> jane = vCalAddress("mailto:jane_doe@example.com")
>>> jane.name = "Jane"
>>> event["organizer"] = jane
>>> print(event.to_ical().decode().replace('\\r\\n', '\\n').strip())
BEGIN:VEVENT
ORGANIZER;CN=Jane:mailto:jane_doe@example.com
END:VEVENT
property CN: str#

Specify the common name to be associated with the calendar user specified.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the common name to be associated with the calendar user specified by the property. The parameter value is text. The parameter value can be used for display text to be associated with the calendar address specified by the property.

property CUTYPE: CUTYPE | str#

Identify the type of calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the type of calendar user specified by the property. If not specified on a property that allows this parameter, the default is INDIVIDUAL. Applications MUST treat x-name and iana-token values they don't recognize the same way as they would the UNKNOWN value.

property DELEGATED_FROM: tuple[str]#

Specify the calendar users that have delegated their participation to the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. This parameter specifies those calendar users that have delegated their participation in a group-scheduled event or to-do to the calendar user specified by the property. The individual calendar address parameter values MUST each be specified in a quoted-string.

property DELEGATED_TO: tuple[str]#

Specify the calendar users to whom the calendar user specified by the property has delegated participation.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. This parameter specifies those calendar users whom have been delegated participation in a group-scheduled event or to-do by the calendar user specified by the property. The individual calendar address parameter values MUST each be specified in a quoted-string.

property DIR: str | None#

Specify reference to a directory entry associated with the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies a reference to the directory entry associated with the calendar user specified by the property. The parameter value is a URI. The URI parameter value MUST be specified in a quoted-string.

Note

While there is no restriction imposed on the URI schemes allowed for this parameter, CID RFC 2392, DATA RFC 2397, FILE RFC 1738, FTP RFC 1738, HTTP RFC 2616, HTTPS RFC 2818, LDAP RFC 4516, and MID RFC 2392 are the URI schemes most commonly used by current implementations.

property LANGUAGE: str | None#

Specify the language for text values in a property or property parameter.

Description:

This parameter identifies the language of the text in the property value and of all property parameter values of the property. The value of the "LANGUAGE" property parameter is that defined in RFC 5646.

For transport in a MIME entity, the Content-Language header field can be used to set the default language for the entire body part. Otherwise, no default language is assumed.

property PARTSTAT: PARTSTAT | str#

Specify the participation status for the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the participation status for the calendar user specified by the property value. The parameter values differ depending on whether they are associated with a group-scheduled "VEVENT", "VTODO", or "VJOURNAL". The values MUST match one of the values allowed for the given calendar component. If not specified on a property that allows this parameter, the default value is NEEDS-ACTION. Applications MUST treat x-name and iana-token values they don't recognize the same way as they would the NEEDS-ACTION value.

property ROLE: ROLE | str#

Specify the participation role for the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the participation role for the calendar user specified by the property in the group schedule calendar component. If not specified on a property that allows this parameter, the default value is REQ-PARTICIPANT. Applications MUST treat x-name and iana-token values they don't recognize the same way as they would the REQ-PARTICIPANT value.

property RSVP: bool#

Specify whether there is an expectation of a favor of anreply from the calendar user specified by the property value.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the expectation of a reply from the calendar user specified by the property value. This parameter is used by the "Organizer" to request a participation status reply from an "Attendee" of a group-scheduled event or to-do. If not specified on a property that allows this parameter, the default value is False.

property SENT_BY: str | None#

Specify the calendar user that is acting on behalf of the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the calendar user that is acting on behalf of the calendar user specified by the property. The parameter value MUST be a mailto URI as defined in RFC 2368. The individual calendar address parameter values MUST each be specified in a quoted-string.

property VALUE: str#

The VALUE parameter or the default.

Purpose:

VALUE explicitly specify the value type format for a property value.

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.

Returns:

The VALUE parameter or the default.

Examples

The VALUE defaults to the name of the property. Note that it is case-insensitive but always uppercase.

>>> from icalendar import vBoolean
>>> b = vBoolean(True)
>>> b.VALUE
'BOOLEAN'

Setting the VALUE parameter of a typed property usually does not make sense. For convenience, using this property, the value will be converted to an uppercase string. If you have some custom property, you might use it like this:

>>> from icalendar import vUnknown, Event
>>> v = vUnknown("Some property text.")
>>> v.VALUE = "x-type"  # lower case
>>> v.VALUE
'X-TYPE'
>>> event = Event()
>>> event.add("x-prop", v)
>>> print(event.to_ical())
BEGIN:VEVENT
X-PROP;VALUE=X-TYPE:Some property text.
END:VEVENT
default_value: ClassVar[str] = 'CAL-ADDRESS'#
property email: str#

The email address without mailto: at the start.

classmethod examples()[source]#

Examples of vCalAddress.

Return type:

list[None]

classmethod from_ical(ical)[source]#
Return type:

None

classmethod from_jcal(jcal_property)[source]#

Parse jCal from RFC 7265.

Parameters:

jcal_property (list) -- The jCal property to parse.

Raises:

JCalParsingError -- If the provided jCal is invalid.

Return type:

None

property ical_value#

The mailto: part of the address.

property name: str#

Specify the common name to be associated with the calendar user specified.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the common name to be associated with the calendar user specified by the property. The parameter value is text. The parameter value can be used for display text to be associated with the calendar address specified by the property.

classmethod new(email, /, cn=None, cutype=None, delegated_from=None, delegated_to=None, directory=None, language=None, partstat=None, role=None, rsvp=None, sent_by=None)[source]#

Create a new vCalAddress with RFC 5545 parameters.

Creates a vCalAddress instance with automatic mailto: prefix handling and support for all standard RFC 5545 parameters.

Parameters:

  • email (str) -- The email address (mailto: prefix added automatically if missing)

  • cn (str | None) -- Common Name parameter

  • cutype (str | None) -- Calendar user type (INDIVIDUAL, GROUP, RESOURCE, ROOM)

  • delegated_from (str | None) -- Email of the calendar user that delegated

  • delegated_to (str | None) -- Email of the calendar user that was delegated to

  • directory (str | None) -- Reference to directory information

  • language (str | None) -- Language for text values

  • partstat (str | None) -- Participation status (NEEDS-ACTION, ACCEPTED, DECLINED, etc.)

  • role (str | None) -- Role (REQ-PARTICIPANT, OPT-PARTICIPANT, NON-PARTICIPANT, CHAIR)

  • rsvp (bool | None) -- Whether RSVP is requested

  • sent_by (str | None) -- Email of the calendar user acting on behalf of this user

Returns:

A new calendar address with specified parameters

Return type:

vCalAddress

Raises:

TypeError -- If email is not a string

Examples

Basic usage:

>>> from icalendar.prop import vCalAddress
>>> addr = vCalAddress.new("test@test.com")
>>> str(addr)
'mailto:test@test.com'

With parameters:

>>> addr = vCalAddress.new("test@test.com", cn="Test User", role="CHAIR")
>>> addr.params["CN"]
'Test User'
>>> addr.params["ROLE"]
'CHAIR'
params: Parameters#
to_ical()[source]#
to_jcal(name)[source]#

Return this property in jCal format.

Return type:

list