Using Kalends
=============

If you have a calendaring product that provides a Kalends interface and you
want to extend the product with views or searching or exports, this file
explains how to be an "event user".

Basic Concepts
--------------
Kalends uses the Component Architecture, which makes heavy use of the concept
of interfaces and adapters. An interface, in this sense, is a contract between
an object and its users. The object promises to implement a certain set of
methods and attributes, as declared by the interface. An adapter is an object
that implements an interface for an object that does not implement it itself.

For example, I may have an iCalendar file. If I just open this file, the file
handler will of course not know anything about the contents of this file or 
how to interpret it as events. If I then write an object that does understand
the iCalendar specification and can extract the events from it, this object
is an adapter.

The interfaces
--------------
The most important interfaces in Kalends are IEventProvider, IEvent and
IOccurrence (interfaces names traditionally start with I). The IEventProvider
is the interface you use to get the events to display or export. To use it, you
must first make sure that your source of events really implements this
interface. You do this in the following way:

    from dateable import kalends
    event_provider = kalends.IEventProvider(eventsource)

This will check whether your event source implements IEventProvider and, if it
doesn't, will try to find an adapter for your source of events and the
IEventProvider interface. (For more information on how this works, see
PROVIDING.txt and the documentation for the Component Architecture.) For
example, eventsource could be an iCalendar file. The file object you get when
opening the file would, of course, not be an event provider or know anything
about events itself, but the adapter would.

You can then ask the event provider for the events:

    events = event_provider.getEvents()

which would return a list of events.

