{"id":4845,"library":"vobject","title":"vobject","description":"vobject is a pure-Python package for parsing and creating iCalendar and vCard files. It supports Python 3.8 or later for the 1.x series (which is under active development, though 0.9.x is currently the latest stable release), while the 0.9.x series (including 0.9.9) supports Python 2.7 and earlier Python 3 versions. The latest version, 0.9.9, was released in December 2024. The project is actively maintained by the py-vobject organization on GitHub, with recent bug fixes and feature additions.","status":"active","version":"0.9.9","language":"en","source_language":"en","source_url":"https://github.com/py-vobject/vobject","tags":["icalendar","vcard","calendar","contact","parser","serializer"],"install":[{"cmd":"pip install vobject","lang":"bash","label":"Install vobject"}],"dependencies":[{"reason":"Required for date and time parsing/serialization, including recurrence rules.","package":"python-dateutil","optional":false},{"reason":"Python 2/3 compatibility layer, required for the 0.9.x series.","package":"six","optional":false},{"reason":"Required by the 'change_tz' script for advanced timezone conversions; not needed for core library functionality.","package":"pyicu","optional":true}],"imports":[{"symbol":"vobject","correct":"import vobject"},{"note":"Used to parse a single vCard or iCalendar component from a string or stream.","symbol":"readOne","correct":"vobject.readOne(...)"},{"note":"Used to parse multiple vCard or iCalendar components from a string or stream, returning an iterator.","symbol":"readComponents","correct":"vobject.readComponents(...)"},{"note":"Creates a new vobject component with a specific behavior (e.g., 'vcalendar', 'vevent', 'vcard').","symbol":"newFromBehavior","correct":"vobject.newFromBehavior('vcalendar')"},{"note":"Convenience function for creating a new VCALENDAR object.","symbol":"iCalendar","correct":"vobject.iCalendar()"},{"note":"Convenience function for creating a new VCARD object.","symbol":"vCard","correct":"vobject.vCard()"}],"quickstart":{"code":"import vobject\nimport datetime\n\n# Create a new iCalendar object\ncal = vobject.iCalendar()\n\n# Add an event component\nevent = cal.add('vevent')\n\n# Add properties to the event\nevent.add('summary').value = 'Meeting with AI team'\nevent.add('dtstart').value = datetime.datetime(2026, 4, 15, 10, 0, 0, tzinfo=datetime.timezone.utc)\nevent.add('dtend').value = datetime.datetime(2026, 4, 15, 11, 0, 0, tzinfo=datetime.timezone.utc)\n\n# Print the iCalendar object in a human-readable format\nprint('--- Pretty Print ---')\nprint(cal.prettyPrint())\n\n# Serialize the iCalendar object to its string representation\n# vobject will automatically add missing mandatory properties like UID and DTSTAMP\nical_string = cal.serialize()\nprint('\\n--- Serialized iCalendar ---')\nprint(ical_string)\n\n# Example of parsing a vCard from a string\nvcard_string = \"\"\"\nBEGIN:VCARD\nVERSION:3.0\nN:Doe;John;;;\nFN:John Doe\nEMAIL;TYPE=WORK:john.doe@example.com\nEND:VCARD\n\"\"\"\n\ntry:\n    parsed_vcard = vobject.readOne(vcard_string)\n    print('\\n--- Parsed vCard (FN) ---')\n    print(parsed_vcard.fn.value)\nexcept Exception as e:\n    print(f\"Error parsing vCard: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially when migrating across major Python versions."},{"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.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If specific values for mandatory properties are required, ensure they are explicitly added to the vobject component before calling `.serialize()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"0.9.x on Python 3.9+"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}