icalendar.prop.binary module

BINARY values from RFC 5545.

class icalendar.prop.binary.vBinary(obj, params=None)

Bases: object

Binary property values are Base64 encoded.

Removed in version 8.0.0: Removed obj attribute, use bytes to access the binary content.

See also

vBinary.obj removed.

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

Setter accepts:

str | None

property base64data: str

The Base64-encoded string view of this value.

This is the same string that to_ical() produces, exposed as a plain str instead of bytes so you don't need to call base64.b64encode() yourself. See #1550.

Returns:

The Base64-encoded representation of the stored value.

bytes: bytes

The raw binary value of the BINARY property.

This is the authoritative storage method, which round-trips losslessly, including for non-UTF-8 data.

default_value: ClassVar[str] = 'BINARY'

classmethod examples()

Examples of vBinary.

Return type:

list[Self]

static from_ical(ical)

Return type:

bytes

classmethod from_jcal(jcal_property)

Parse jCal from RFC 7265 to a vBinary.

Parameters:

jcal_property (list) – The jCal property to parse.

Raises:

JCalParsingError – If the provided jCal is invalid.

Return type:

Self

classmethod from_xcal(xml)

Parse xCal from RFC 6321.

Parameters:

xml (XCalParser | ElementAdapter | Element) – The XML to parse or a parser.

Raises:

XCalParsingError – If the provided xCal is invalid.

Return type:

VProp

property ical_value: bytes

The raw bytes value of the BINARY property.

Added in version 7.1.0.

Changed in version 7.1.3: Returns the raw stored bytes. Previously the stored value was Base64-decoded, which raised ValueError for non-Base64 input. See #1356.

params: Parameters

to_ical()

Return type:

bytes

to_jcal(name)

The jCal representation of this property according to RFC 7265.

Return type:

list

to_xcal(element)

The xCal representation of this property according to RFC 6321.

property uri: str

Return this value as an RFC 2397 base64 data URI.

The media type comes from the current FMTTYPE parameter, or defaults to application/octet-stream when it is not set. See RFC 2397 for the data URI scheme.

Examples

>>> from icalendar import vBinary
>>> vBinary(b"hello", params={"FMTTYPE": "text/plain"}).uri
'data:text/plain;base64,aGVsbG8='