aboutsummaryrefslogtreecommitdiffstats
path: root/libical/src/python/python-binding.txt
diff options
context:
space:
mode:
Diffstat (limited to 'libical/src/python/python-binding.txt')
-rw-r--r--libical/src/python/python-binding.txt434
1 files changed, 434 insertions, 0 deletions
diff --git a/libical/src/python/python-binding.txt b/libical/src/python/python-binding.txt
new file mode 100644
index 0000000000..7fc9e066bf
--- /dev/null
+++ b/libical/src/python/python-binding.txt
@@ -0,0 +1,434 @@
+
+Classes for python binding to libical
+(Indentation indicates inheritance)
+
+ Component
+ Event
+ JournalEntry
+ Todo
+ FreeBusy
+ Timezone
+ Alarm
+ AudioAlarm
+ EmailAlarm
+ ProcedureAlarm
+ DisplayAlarm
+
+ Property
+ Attendee
+ Organizer
+ Status
+ Error
+
+ Time
+ Period
+ Date
+ RecurrenceSet
+
+ Timezone
+ TimezonePhase
+
+ Store
+ FileStore
+ DirStore
+ CAPStore
+ HeapStore
+ MySQLStore
+
+
+
+Component is the central class in the design. The component can be
+though of as a container for child components and properties, or as
+representation of a specific kind of iCal object. The first
+interface offers general property and component accessors, and the
+second treats some types of objects in a special way.
+
+The general interface offers simple manipulators for child property
+and components, and it only works with immediate children. So, given
+the Component:
+
+ BEGIN:VCALENDAR
+ METHOD:PUBLISH
+ BEGIN:VEVENT
+ BEGIN:VALARM
+ COMMENT: An Alarm
+ END:VALARM
+ END:VEVENT
+ END:VCALENDAR
+
+A caller would have to descend three levels to access the COMMENT
+property in the alarm, but only one to access the METHOD property.
+
+Libical is almost entirely dedicated to the general interface; it
+includes all of the *get_first_*, *_next_next_*, *_add_* and *_remove_*
+routines.
+
+The specific interface works with derived classes of Property and
+Component. In this interface, the caller could get the COMMENT in the
+alarm in the example in two steps. First the caller would ask the
+Event object for its alarms, then then the caller would ask the first
+Alarm object for its comment.
+
+The Specific interface is part of the
+derived classes of Component. This interface names all of the types of
+properties and components that can be accessed from the derived
+component type.
+
+In libical, the specific interface is primarily the "convenience
+routines in icalcomponent.h, such as:
+
+
+ struct icaltimetype icalcomponent_get_dtend(icalcomponent* comp);
+ void icalcomponent_set_dtend(icalcomponent* comp, struct icaltimetype v);
+
+ void icalcomponent_set_duration(icalcomponent* comp,
+ struct icaldurationtype v);
+ struct icaldurationtype icalcomponent_get_duration(icalcomponent* comp);
+
+These routines are smarter and do more work than the general
+interface. From the general interface, you can set the DTEND
+property of a component by creating the property and adding it to a
+component. But, if the component already has a DURATION property, then
+this is an error -- a component can't have both.
+
+icalcomponent_set_dtend determines if the component already has a
+DURATION. If it does, it substracts the dtstart time from the new
+dtend time and sets the duration to that. Otherwise, it creates aor
+changes the DTEND.
+
+Also, icalcomponent_set_duration works the same regardless if the
+component is a VCALENDAR or a VEVENT. If it is a VCALENDAR, the
+routine descends into the VEVENT before making any changes. If it is
+allready a VEVENT ( or VTODO or VJOURNAL ) the routine just makes the
+changes. With icalcomponent_add_property, you need to do this check
+yourself.
+
+( There should probably be a class between Component
+and Event ,JournalEntry and Todo that names all of the properties and
+components. Then Event, JournalEntry and Todo would remove the
+accessors that did not apply to them. )
+
+Parameters are accessed as dictionaries from Property or as attributes
+of a derived class of Property. Both the names and the values of the
+parameters are strings.
+
+The Store hierarchy is a interface to various ways to store iCal
+components. Each of these has the same interface as its corresponding
+libical module:
+
+ FileStore icalfileset Store iCal components in a single file
+ DirStore icaldirset Use multiple files, one per month of
+ DTSTART
+ CAPStore Access components in a CAP server
+ HeapStore Components stored in memory
+ MySQLStore Components stored in a MySQL
+ database.
+
+The only iCal value objects that will be implemented as Python classes
+are Time, Duration and Period. RecurrenceSet handles recurrence
+rules. It replaces the properties RRULE, RDATE, EXRULE and EXDATE.
+
+(Not all of the libical modules are implemented )
+
+
+How to Use the library
+----------------------
+
+The most common usecases will be something like this:
+
+1)Caller opens a Store object on a file, server or database. The
+caller retrieves one or more component. Some of the components will be
+booked on the user's calendar. Other components will be messages that
+other users have sent, like requests for meetings.
+
+2) The caller will use the Specific interface ( using methods specific
+to each property ) to example the component and decide what to do with
+it.
+
+3) Rarely, the caller will access the general interface to do things
+that the specific interface has not implemented or cannot manage
+well.
+
+4) Cller may create a new component, using a combination of the
+general and specific interfaces. The caller may send the message to
+another user via mail, or may submit it to the user's CAP server with
+the CAPStore class.
+
+
+Following are the methods in each of the classes.
+
+Component
+ Construct from string
+ output string in ical form
+
+ Get a Property by type
+ Get a set of Properties by type
+ Remove a Property by reference
+
+ Get a Component by type
+ Get a set of Components by type
+ Remove a Component by reference
+
+ Validate the component ( insert properties for errors )
+ Count error properties
+ Remove error properties
+ Convert error properties into REQUEST-STATUS properties
+
+Event, JournalEntry, Todo
+
+ Construct from string
+ output string in ical form
+
+ There are get/set accessors for every property. These are
+ listed in a later section
+
+
+FreeBusy
+
+ Construct from string
+ Construct from arguments
+ output string in ical form
+
+ Accessors for the following properties. See below for return
+ types for these properties:
+
+ method
+ prodid
+ attendee
+ dtstamp
+ dtstart
+ freebusy
+ organizer
+ uid
+ comment
+ contact
+ request-status
+ url
+ duration
+ sequence
+
+TimezonePhase
+
+ Construct from string
+ Construct from arguments
+ output string in ical form
+
+ Accessors for the following properties. See below for return
+ types for these properties:
+
+ tzname
+ offsetto
+ offsetfrom
+ rrule
+ rdate
+ comment
+
+TimeZone
+
+ Construct from string
+ Construct from arguments
+ output string in ical form
+
+ Accessors for the following properties. See below for return
+ types for these properties:
+
+ tzid
+ last-modified
+ tzurl
+ standard (returns TimezonePhase)
+ daylight (returns TimezonePhase)
+
+
+Property
+
+ Construct from string
+ Construct from arguments
+ output string in ical form
+
+ Dictionary access to parameters
+
+ Get/set value
+
+Attendee
+
+ Construct from string
+ Construct from arguments
+ output string in ical form
+
+ Access to the following properties and parameters:
+ cuid
+ cutype
+ member
+ role
+ rsvp
+ delto
+ delfrom
+ sentby
+ cn
+ dir
+ language
+
+Organizer
+
+ Access to the following properties:
+ common_name
+ dir
+ sentby
+ language
+
+
+Time
+Date
+Period
+
+ Same interfaces as libical modules.
+
+RecurenceSet
+ I don't know -- need to think about it more.
+
+Store
+ Similar methods to the icalset modules.
+
+
+RFC2445 Properties
+
+This is a list of all of the RFC2445 properties and their associated
+VALUE type.
+
+
+Property Value
+----------------------------
+CALSCALE TEXT
+METHOD TEXT
+PRODID TEXT
+VERSION TEXT
+CATEGORIES TEXT
+CLASS TEXT
+COMMENT TEXT
+DESCRIPTION TEXT
+LOCATION TEXT
+PERCENT-COMPLETE INTEGER
+PRIORITY INTEGER
+RESOURCES TEXT
+STATUS STATUS
+SUMMARY TEXT
+COMPLETED DATE-TIME
+FREEBUSY PERIOD
+TRANSP TEXT
+TZNAME TEXT
+TZOFFSETFROM UTC-OFFSET
+TZOFFSETTO UTC-OFFSET
+TZURL URI
+TZID TEXT
+ATTENDEE CAL-ADDRESS
+CONTACT TEXT
+ORGANIZER CAL-ADDRESS
+RELATED-TO TEXT
+URL URI
+UID TEXT
+EXRULE RECUR
+RRULE RECUR
+ACTION TEXT
+REPEAT INTEGER
+CREATED DATE-TIME
+DTSTAMP DATE-TIME
+LAST-MODIFIED DATE-TIME
+SEQUENCE INTEGER
+X TEXT
+REQUEST-STATUS STRING
+ATTACH URL, BINARY
+GEO FLOAT
+DTEND DATE-TIME
+DUE DATE-TIME
+DTSTART DATE-TIME
+RECURRENCE-ID DATE-TIME
+EXDATE DATE-TIME
+RDATE DATE-TIME, PERIOD
+TRIGGER DATE-TIME, DURATION
+DURATION DURATION
+
+Some of the properties can appear multiple times in a component, other
+can appear only once. For a particular component, the number of times
+a property can apper may also change with the METHOD property
+associated with the component. This list shows which properties can
+appear multiple times for some ( but not all ) combinations of
+component type and METHOD value:
+
+ATTACH
+ATTENDEE
+CATEGORIES
+COMMENT
+CONTACT
+EXDATE
+EXRULE
+FREEBUSY
+NONE
+RDATE
+RELATEDTO
+REQUESTSTATUS
+RESOURCES
+RRULE
+TZNAME
+TZURL
+X
+
+
+This is a list of the value types and their associated python return
+types. A lowercased return type is a python builtin, and an
+uppercase-first-letter is a class in the library:
+
+
+Value Return Type
+-----------------------------------
+BINARY file
+BOOLEAN number
+CAL-ADDRESS string
+DATE Time
+DATE-TIME Time
+DURATION Duration
+FLOAT number
+GEO tuple
+INTEGER number
+METHOD string
+PERIOD Period
+RECUR RecurrenceSet
+TEXT string
+TIME Time
+URI string
+UTC-OFFSET number
+STATUS string
+X string
+
+
+I suspect that the Component class should use the three previous
+tables to create the property accessor methods on the fly. If the
+method generation system is general enough, we could also use it for
+other classes, such as Alarm, Timezone, Attendee, Organizer and
+Freebusy.
+
+
+Memory Handling
+---------------
+
+One of the things that made the perl binding to libcal difficult was
+that if a Component (in perl) returns a reference to a child Component
+(in perl), the child Component (in perl) will contain a reference to a
+libical component. When the caller is done with the child component in
+perl, the caller just drops it and lets perl reclaim the memory.
+
+The destructor for Component needs to free the libical component that
+it holds a reference to, but the child's libical component is still
+being used by libical. So perl frees the libical component and later,
+libical tries to reference freed memory.
+
+The situation is actually a little better than that, because libical
+will throw an error when you try to free a component that is still
+attached to a parent.
+
+So, the perl library has to be able to determine when the destructor
+should free a libical component or not. The perl library calls
+icalcomponent_get_parent(), and if is it non-zero, it does not free
+the component.
+
+It is not hard, just more code, and something to watch out for.
+
generated by cgit v1.2.3 (git 2.25.1) at 2025-02-01 18:36:39 +0800