About VObject

VObject is intended to be a full-featured Python package for parsing and generating vCard and vCalendar files. It was originally developed in concert with the Open Source Application Foundation's Chandler project by Jeffrey Harris. Many thanks to all the contributors for their dedication and support. The project is currently being maintained by Eventable and Sameen Karim.

Currently, iCalendar files are supported and well tested. vCard 3.0 files are supported, and all data should be imported, but only a few components are understood in a sophisticated way. The Calendar Server team has added VAVAILABILITY support to VObject's iCalendar parsing. Please report bugs and issues directly on GitHub.

VObject is licensed under the Apache 2.0 license. License

Useful scripts included with VObject:

Installation PyPI version

To install with pip, run:

pip install vobject

Or download the package and run:

python setup.py install

VObject requires Python 2.7 or higher, along with the dateutil and six packages.

Running tests Build Status

To run all tests, use:

python tests/tests.py

Usage

iCalendar

Creating iCalendar objects

VObject has a basic datastructure for working with iCalendar-like syntaxes. Additionally, it defines specialized behaviors for many of the commonly used iCalendar objects.

To create an object that already has a behavior defined, run:

>>> import vobject
>>> cal = vobject.newFromBehavior('vcalendar')
>>> cal.behavior
<class 'vobject.icalendar.VCalendar2_0'>

Convenience functions exist to create iCalendar and vCard objects:

>>> cal = vobject.iCalendar()
>>> cal.behavior
<class 'vobject.icalendar.VCalendar2_0'>
>>> card = vobject.vCard()
>>> card.behavior
<class 'vobject.vcard.VCard3_0'>

Once you have an object, you can use the add method to create children:

>>> cal.add('vevent')
<VEVENT| []>
>>> cal.vevent.add('summary').value = "This is a note"
>>> cal.prettyPrint()
 VCALENDAR
    VEVENT
       SUMMARY: This is a note

Note that summary is a little different from vevent, it's a ContentLine, not a Component. It can't have children, and it has a special value attribute.

ContentLines can also have parameters. They can be accessed with regular attribute names with _param appended:

>>> cal.vevent.summary.x_random_param = 'Random parameter'
>>> cal.prettyPrint()
 VCALENDAR
    VEVENT
       SUMMARY: This is a note
       params for  SUMMARY:
          X-RANDOM ['Random parameter']

There are a few things to note about this example

If you want to access the full list of parameters, not just the first, use <paramname>_paramlist:

>>> cal.vevent.summary.x_random_paramlist
['Random parameter']
>>> cal.vevent.summary.x_random_paramlist.append('Other param')
>>> cal.vevent.summary
<SUMMARY{'X-RANDOM': ['Random parameter', 'Other param']}This is a note>

Similar to parameters, If you want to access more than just the first child of a Component, you can access the full list of children of a given name by appending _list to the attribute name:

>>> cal.add('vevent').add('summary').value = "Second VEVENT"
>>> for ev in cal.vevent_list:
...     print ev.summary.value
This is a note
Second VEVENT

The interaction between the del operator and the hiding of the underlying list is a little tricky, both del cal.vevent and del cal.vevent_list delete all vevent children:

>>> first_ev = cal.vevent
>>> del cal.vevent
>>> cal
<VCALENDAR| []>
>>> cal.vevent = first_ev

VObject understands Python's datetime module and tzinfo classes.

>>> import datetime
>>> utc = vobject.icalendar.utc
>>> start = cal.vevent.add('dtstart')
>>> start.value = datetime.datetime(2006, 2, 16, tzinfo = utc)
>>> first_ev.prettyPrint()
     VEVENT
        DTSTART: 2006-02-16 00:00:00+00:00
        SUMMARY: This is a note
        params for  SUMMARY:
           X-RANDOM ['Random parameter', 'Other param']

Components and ContentLines have serialize methods:

>>> cal.vevent.add('uid').value = 'Sample UID'
>>> icalstream = cal.serialize()
>>> print icalstream
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//PYVOBJECT//NONSGML Version 1//EN
BEGIN:VEVENT
UID:Sample UID
DTSTART:20060216T000000Z
SUMMARY;X-RANDOM=Random parameter,Other param:This is a note
END:VEVENT
END:VCALENDAR

Observe that serializing adds missing required lines like version and prodid. A random UID would be generated, too, if one didn't exist.

If dtstart's tzinfo had been something other than UTC, an appropriate vtimezone would be created for it.

Parsing iCalendar objects

To parse one top level component from an existing iCalendar stream or string, use the readOne function:

>>> parsedCal = vobject.readOne(icalstream)
>>> parsedCal.vevent.dtstart.value
datetime.datetime(2006, 2, 16, 0, 0, tzinfo=tzutc())

Similarly, readComponents is a generator yielding one top level component at a time from a stream or string.

>>> vobject.readComponents(icalstream).next().vevent.dtstart.value
datetime.datetime(2006, 2, 16, 0, 0, tzinfo=tzutc())

More examples can be found in source code doctests.

vCards

Creating vCard objects

Making vCards proceeds in much the same way. Note that the 'FN' attribute is required.

>>> j = vobject.vCard()
>>> j.add('n')
 <N{}    >
>>> j.n.value = vobject.vcard.Name( family='Harris', given='Jeffrey' )
>>> j.add('fn')
 <FN{}>
>>> j.fn.value ='Jeffrey Harris'
>>> j.add('email')
 <EMAIL{}>
>>> j.email.value = 'jeffrey@osafoundation.org'
>>> j.email.type_param = 'INTERNET'
>>> j.prettyPrint()
 VCARD
    EMAIL: jeffrey@osafoundation.org
    params for  EMAIL:
       TYPE ['INTERNET']
    FN: Jeffrey Harris
    N:  Jeffrey  Harris

serializing will add any required computable attributes (like 'VERSION')

>>> j.serialize()
'BEGIN:VCARD\r\nVERSION:3.0\r\nEMAIL;TYPE=INTERNET:jeffrey@osafoundation.org\r\nFN:Jeffrey Harris\r\nN:Harris;Jeffrey;;;\r\nEND:VCARD\r\n'
>>> j.prettyPrint()
 VCARD
    VERSION: 3.0
    EMAIL: jeffrey@osafoundation.org
    params for  EMAIL:
       TYPE ['INTERNET']
    FN: Jeffrey Harris
    N:  Jeffrey  Harris 

Parsing vCard objects

>>> s = """
... BEGIN:VCARD
... VERSION:3.0
... EMAIL;TYPE=INTERNET:jeffrey@osafoundation.org
... FN:Jeffrey Harris
... N:Harris;Jeffrey;;;
... END:VCARD
... """
>>> v = vobject.readOne( s )
>>> v.prettyPrint()
 VCARD
    VERSION: 3.0
    EMAIL: jeffrey@osafoundation.org
    params for  EMAIL:
       TYPE [u'INTERNET']
    FN: Jeffrey Harris
    N:  Jeffrey  Harris
>>> v.n.value.family
u'Harris'

Multi-Value Properties

Multi-value properties are properties of a component that can contain multiple values. An easy example would be email. A vCard can contain both someone's work email address and their home email address. When dealing with multi-value properties, the getting and setting of values happens slightly differentely than singleton properties.

Adding Multi-Value Properties

You should add multi-value properties by creating multiple ContentLines and giving each a value. You can also set the property list explicitly, but this is not advised.

>>> v = vobject.vCard()
>>> v.add('fn').value = "Jeffery Harris"
>>> v.add('email').value = 'jeffrey@osafoundation.org'
>>> v.add('email').value = 'jeffrey@example.com'
>>> print v.email_list
 [<EMAIL{}jeffrey@osafoundation.org>, <EMAIL{}jeffery@example.com>]
>>> print v.serialize()
 BEGIN:VCARD
 VERSION:3.0
 EMAIL:jeffrey@osafoundation.org
 EMAIL:jeffery@example.com
 FN:Jeffery Harris
 END:VCARD

Accessing Multi-Value Properties

You can access multi-value entries either by grabbing the relevent entry in the `contents` dictionary or by directly accessing the attribute and appending _list to the property name.

>>> s = """
... BEGIN:VCARD
... VERSION:3.0
... EMAIL;TYPE=INTERNET:jeffrey@osafoundation.org
... FN:Jeffrey Harris
... N:Harris;Jeffrey;;;
... TEL;TYPE=WORK,VOICE:(111) 555-1212
... TEL;TYPE=HOME,VOICE:(404) 555-1212
... END:VCARD
... """
>>> v = vobject.readOne( s )
>>> for tel in v.contents['tel']:
...     print tel
 <TEL{u'TYPE': [u'WORK', u'VOICE']}(111) 555-1212>
 <TEL{u'TYPE': [u'HOME', u'VOICE']}(404) 555-1212>
>>> for tel in v.contents['tel']:
...     print tel.value
 (111) 555-1212
 (404) 555-1212
>>> v.tel_list
 [<TEL{'TYPE': ['WORK', 'VOICE']}(111) 555-1212>,
  <TEL{'TYPE': ['HOME', 'VOICE']}(404) 555-1212>]

Release History

29 June 2017

vobject 0.9.5 released (view).

To install, use pip install vobject, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil and six are required. Python 2.7 or higher is required.

Release Notes

22 January 2017

vobject 0.9.4.1 released (view).

To install, use pip install vobject, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil and six are required. Python 2.7 or higher is required.

Release Notes

20 January 2017

vobject 0.9.4 released (view).

To install, use pip install vobject, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil and six are required. Python 2.7 or higher is required.

Release Notes

26 August 2016

vobject 0.9.3 released (view).

To install, use pip install vobject, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil and six are required. Python 2.7 or higher is required.

Release Notes

13 March 2016

vobject 0.9.2 released (view).

To install, use pip install vobject, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil and six are required. Python 2.7 or higher is required.

Release Notes

16 February 2016

vobject 0.9.1 released (view).

To install, use pip install vobject, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil and six are required. Python 2.7 or higher is now required.

Release Notes

3 February 2016

vobject 0.9.0 released (view).

To install, use pip install vobject, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 2.4.0 and six are required. Python 2.7 or higher is now required.

Release Notes

28 January 2016

vobject 0.8.2 released (view).

To install, use pip install vobject, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

27 February 2009

vobject 0.8.1c released (SVN revision 217).

To install, use easy_install, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

12 January 2009

vobject 0.8.1b released (SVN revision 216).

To install, use easy_install, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

29 December 2008

vobject 0.8.0 released (SVN revision 213).

To install, use easy_install, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

25 July 2008

vobject 0.7.1 released (SVN revision 208).

To install, use easy_install, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

16 July 2008

vobject 0.7.0 released (SVN revision 206).

To install, use easy_install, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

30 May 2008

vobject 0.6.6 released (SVN revision 201).

To install, use easy_install, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

28 May 2008

vobject 0.6.5 released (SVN revision 200).

To install, use easy_install, or download the archive and untar, run python setup.py install. Tests can be run via python setup.py test. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

21 February 2008

vobject 0.6.0 released (SVN revision 193).

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

14 January 2008

vobject 0.5.0 released (SVN revision 189).

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

19 November 2007

vobject 0.4.9 released (SVN revision 187).

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

7 January 2007

vobject 0.4.8 released (SVN revision 180).

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

21 December 2006

vobject 0.4.7 released (SVN revision 172), hot on the heals of yesterday's 0.4.6.

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

20 December 2006

vobject 0.4.6 released (SVN revision 171)

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

8 December 2006

vobject 0.4.5 released (SVN revision 168)

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

9 October 2006

vobject 0.4.4 released (SVN revision 159)

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 1.1 or later is required. Python 2.4 is also required.

Release Notes

22 September 2006

vobject 0.4.3 released (SVN revision 157)

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 0.9 or later is required. Python 2.4 is also required.

Release Notes

29 August 2006

vobject 0.4.2 released (SVN revision 153)

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 0.9 or later is required. Python 2.4 is also required.

Release Notes

4 August 2006

vobject 0.4.1 released (SVN revision 152)

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 0.9 or later is required. Python 2.4 is also required.

Release Notes

2 August 2006

vobject 0.4.0 released (SVN revision 151)

To install, use easy_install, or download the archive and untar, run python setup.py install. dateutil 0.9 or later is required. Python 2.4 is also required.

Release Notes

17 February 2006

vobject 0.3.0 released (SVN revision 129)

To install, untar the archive, run python setup.py install. dateutil 0.9 or later is required. Python 2.4 is also required.

Release Notes

9 January 2006

vobject 0.2.3 released (SVN revision 104)

To install, untar the archive, run python setup.py install. dateutil 0.9 or later is required. Python 2.4 is also required.

Release Notes

4 November 2005

vobject 0.2.2 released (SVN revision 101)

To install, untar the archive, run python setup.py install. dateutil 0.9 or later is required. Python 2.4 is also required.

Release Notes

10 October 2005

vobject 0.2.0 released (SVN revision 97)

To install, untar the archive, run python setup.py install. dateutil 0.9 or later is required. Python 2.4 is also required.

Release Notes

30 September 2005

vobject 0.1.4 released (SVN revision 93)

To install, untar the archive, run python setup.py install. dateutil 0.9 or later is required. As of this release, Python 2.4 is also required.

Release Notes

1 July 2005

vobject 0.1.3 released (SVN revision 88)

To install, untar the archive, run python setup.py install. dateutil 0.9 or later is required. As of this release, Python 2.4 is also required.

Release Notes

24 March 2005

vobject 0.1.2 released (SVN revision 83)

To install, untar the archive, run python setup.py install. dateutil is required. You'll need to apply this patch to be able to read certain VTIMEZONEs exported by Apple iCal, or if you happen to be in Europe!

patch -R $PYTHONLIB/site-packages/dateutil/tz.py dateutil-0.5-tzoffset-bug.patch

Release Notes

25 January 2005

vobject 0.1.1 released (SVN revision 82)

To install, untar the archive, run python setup.py install. dateutil is required. You'll need to apply this patch to be able to read certain VTIMEZONEs exported by Apple iCal, or if you happen to be in Europe!

patch -R $PYTHONLIB/site-packages/dateutil/tz.py dateutil-0.5-tzoffset-bug.patch

Release Notes

13 December 2004

vobject 0.1 released (SVN revision 70)

Release Notes