diff options
author | Guido Guenther <agx@sigxcpu.org> | 2008-06-20 09:11:42 +0200 |
---|---|---|
committer | Guido Guenther <agx@sigxcpu.org> | 2008-06-20 09:11:42 +0200 |
commit | bd308fbf5f91cd2d9f86f9ea437bcf54a120a09c (patch) | |
tree | 6361d7bceda4ac2ef9f4b6de0565874f9da0c1a2 /vobject/__init__.py | |
parent | 7a6dcb8d42e0611d4d49130d0cb492d9f58e51d6 (diff) |
Imported Upstream version 0.6.6
Diffstat (limited to 'vobject/__init__.py')
-rw-r--r-- | vobject/__init__.py | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/vobject/__init__.py b/vobject/__init__.py new file mode 100644 index 0000000..d5daf30 --- /dev/null +++ b/vobject/__init__.py @@ -0,0 +1,86 @@ +""" +VObject Overview +================ + vobject parses vCard or vCalendar files, returning a tree of Python objects. + It also provids an API to create vCard or vCalendar data structures which + can then be serialized. + + Parsing existing streams + ------------------------ + Streams containing one or many L{Component<base.Component>}s can be + parsed using L{readComponents<base.readComponents>}. As each Component + is parsed, vobject will attempt to give it a L{Behavior<behavior.Behavior>}. + If an appropriate Behavior is found, any base64, quoted-printable, or + backslash escaped data will automatically be decoded. Dates and datetimes + will be transformed to datetime.date or datetime.datetime instances. + Components containing recurrence information will have a special rruleset + attribute (a dateutil.rrule.rruleset instance). + + Validation + ---------- + L{Behavior<behavior.Behavior>} classes implement validation for + L{Component<base.Component>}s. To validate, an object must have all + required children. There (TODO: will be) a toggle to raise an exception or + just log unrecognized, non-experimental children and parameters. + + Creating objects programatically + -------------------------------- + A L{Component<base.Component>} can be created from scratch. No encoding + is necessary, serialization will encode data automatically. Factory + functions (TODO: will be) available to create standard objects. + + Serializing objects + ------------------- + Serialization: + - Looks for missing required children that can be automatically generated, + like a UID or a PRODID, and adds them + - Encodes all values that can be automatically encoded + - Checks to make sure the object is valid (unless this behavior is + explicitly disabled) + - Appends the serialized object to a buffer, or fills a new + buffer and returns it + + Examples + -------- + + >>> import datetime + >>> import dateutil.rrule as rrule + >>> x = iCalendar() + >>> x.add('vevent') + <VEVENT| []> + >>> x + <VCALENDAR| [<VEVENT| []>]> + >>> v = x.vevent + >>> utc = icalendar.utc + >>> v.add('dtstart').value = datetime.datetime(2004, 12, 15, 14, tzinfo = utc) + >>> v + <VEVENT| [<DTSTART{}2004-12-15 14:00:00+00:00>]> + >>> x + <VCALENDAR| [<VEVENT| [<DTSTART{}2004-12-15 14:00:00+00:00>]>]> + >>> newrule = rrule.rruleset() + >>> newrule.rrule(rrule.rrule(rrule.WEEKLY, count=2, dtstart=v.dtstart.value)) + >>> v.rruleset = newrule + >>> list(v.rruleset) + [datetime.datetime(2004, 12, 15, 14, 0, tzinfo=tzutc()), datetime.datetime(2004, 12, 22, 14, 0, tzinfo=tzutc())] + >>> v.add('uid').value = "randomuid@MYHOSTNAME" + >>> print x.serialize() + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//PYVOBJECT//NONSGML Version 1//EN + BEGIN:VEVENT + UID:randomuid@MYHOSTNAME + DTSTART:20041215T140000Z + RRULE:FREQ=WEEKLY;COUNT=2 + END:VEVENT + END:VCALENDAR + +""" + +import base, icalendar, vcard +from base import readComponents, readOne, newFromBehavior + +def iCalendar(): + return newFromBehavior('vcalendar', '2.0') + +def vCard(): + return newFromBehavior('vcard', '3.0')
\ No newline at end of file |