|
- """
- 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
-
- """
-
- from .base import newFromBehavior, readOne, readComponents
- from . import icalendar, vcard
-
-
- def iCalendar():
- return newFromBehavior('vcalendar', '2.0')
-
-
- def vCard():
- return newFromBehavior('vcard', '3.0')
|
