vobject

Warnings

• breaking The `vobject` library has two main series: 0.9.x and 1.x. Version 0.9.x (including the current 0.9.9) maintains compatibility with Python 2.7 and earlier Python 3 versions. The upcoming 1.x series will *only* support Python 3.8 and later. Be aware of this when planning Python environment upgrades or starting new projects.
  Fix: For new projects or Python 3.8+, consider waiting for the 1.x series or explicitly targeting 0.9.x if Python 2.7 compatibility is required. Check the official documentation for the latest guidance on the 1.x release.
• gotcha When parsing iCalendar or vCard strings, `vobject.readOne()` and `vobject.readComponents()` expect well-formed input, including closing `END:` tags for all components. Missing `END:` tags or malformed input will result in parsing errors (e.g., `SyntaxError` or `StopIteration`).
  Fix: Ensure input strings are complete and correctly formatted. Use triple quotes for multi-line strings in Python code to preserve line feeds. When processing external data, consider pre-validation or robust error handling around parsing calls.
• gotcha Accessing properties directly via `item.contents['property_name']` will return a list, even if only one value exists for that property. You often need to access `item.contents['property_name'][0].value` to get the actual value. Convenience attributes like `item.summary.value` or `item.dtstart.value` are available for common, single-value properties.
  Fix: For single-value properties, prefer direct attribute access (e.g., `component.dtstart.value`). For potentially multi-value properties or when inspecting the raw structure, be mindful that `item.contents` returns lists and iterate or access by index accordingly.
• gotcha During serialization (`.serialize()`), `vobject` automatically adds mandatory iCalendar/vCard properties like `UID`, `DTSTAMP`, and `PRODID` if they are not already present. While usually beneficial for creating valid files, this can be unexpected if strict control over all output properties is desired before serialization.
  Fix: If specific values for mandatory properties are required, ensure they are explicitly added to the vobject component before calling `.serialize()`.
• deprecated Users running `vobject` on Python 3.9+ may encounter `DeprecationWarning: invalid escape sequence` messages, primarily originating from internal regular expressions in `vobject/base.py`. These are warnings and do not stop execution but indicate potential future compatibility issues or a need for updated regex patterns.
  Fix: These are generally benign warnings for now. Keep `vobject` updated to its latest versions, as these might be addressed in future releases, particularly in the 1.x series targeting newer Python versions.

Install

• pip install vobject Install vobject

Imports

• vobject

  import vobject

• readOne

  vobject.readOne(...)

  Used to parse a single vCard or iCalendar component from a string or stream.
• readComponents

  vobject.readComponents(...)

  Used to parse multiple vCard or iCalendar components from a string or stream, returning an iterator.
• newFromBehavior

  vobject.newFromBehavior('vcalendar')

  Creates a new vobject component with a specific behavior (e.g., 'vcalendar', 'vevent', 'vcard').
• iCalendar

  vobject.iCalendar()

  Convenience function for creating a new VCALENDAR object.
• vCard

  vobject.vCard()

  Convenience function for creating a new VCARD object.

Quickstart

This quickstart demonstrates how to create a basic iCalendar event, add properties including datetime objects, and then serialize it into an iCalendar string. It also shows how to parse a vCard string using `vobject.readOne()` and access its properties. Note that `vobject` automatically adds mandatory components like `UID` and `DTSTAMP` during serialization if they are not explicitly set.

import vobject
import datetime

# Create a new iCalendar object
cal = vobject.iCalendar()

# Add an event component
event = cal.add('vevent')

# Add properties to the event
event.add('summary').value = 'Meeting with AI team'
event.add('dtstart').value = datetime.datetime(2026, 4, 15, 10, 0, 0, tzinfo=datetime.timezone.utc)
event.add('dtend').value = datetime.datetime(2026, 4, 15, 11, 0, 0, tzinfo=datetime.timezone.utc)

# Print the iCalendar object in a human-readable format
print('--- Pretty Print ---')
print(cal.prettyPrint())

# Serialize the iCalendar object to its string representation
# vobject will automatically add missing mandatory properties like UID and DTSTAMP
ical_string = cal.serialize()
print('\n--- Serialized iCalendar ---')
print(ical_string)

# Example of parsing a vCard from a string
vcard_string = """
BEGIN:VCARD
VERSION:3.0
N:Doe;John;;;
FN:John Doe
EMAIL;TYPE=WORK:john.doe@example.com
END:VCARD
"""

try:
    parsed_vcard = vobject.readOne(vcard_string)
    print('\n--- Parsed vCard (FN) ---')
    print(parsed_vcard.fn.value)
except Exception as e:
    print(f"Error parsing vCard: {e}")