imip-agent

Annotated docs/wiki/Developing

1384:9baa0aae5b43
1069:37921ab84c01
2017-10-31 Paul Boddie file changeset files shortlog Provided a convenience function for instantiating handler objects. Added a mode that produces output instead of sending messages without also producing debugging information. client-editing-simplification
paul@1007 1 
= Developing imip-agent =
paul@1007 2 
 
 paul@1007      3 
To start developing the imip-agent software further, first obtain the code
 
 paul@1007      4 
by following the advice on the [[../Downloads|downloads page]]. Obtaining
 
 paul@1007      5 
the code directly from the repository is advisable since any changes you
 
 paul@1007      6 
make can then be tracked and managed.
 
 paul@1007      7 
 
 paul@1007      8 
<<TableOfContents(2,3)>>
 
 paul@1007      9 
 
 paul@1007     10 
== Distribution Contents ==
 
 paul@1007     11 
 
 paul@1007     12 
The software distribution contains the following directories:
 
 paul@1007     13 
 
 paul@1007     14 
{{{#!table
 
 paul@1007     15 
'''Directory''' || '''Description'''
 
 paul@1007     16 
==
 
 paul@1007     17 
`conf`
 
 paul@1007     18 
|| Example configuration files (see the
 
 paul@1007     19 
.. [[../GettingStarted|getting started guide]] for details)
 
 paul@1007     20 
==
 
 paul@1007     21 
`docs`
 
 paul@1007     22 
|| Documentation, including these wiki pages
 
 paul@1007     23 
==
 
 paul@1007     24 
`htdocs`
 
 paul@1007     25 
|| Resources for the [[../CalendarManager|management interface]]
 
 paul@1007     26 
==
 
 paul@1007     27 
`imiptools`
 
 paul@1007     28 
|| A Python package providing mail handling and support for calendar
 
 paul@1007     29 
.. object processing
 
 paul@1007     30 
==
 
 paul@1007     31 
`imipweb`
 
 paul@1007     32 
|| A Python package providing Web-related functionality for the
 
 paul@1007     33 
.. [[../CalendarManager|management interface]]
 
 paul@1007     34 
==
 
 paul@1007     35 
`messages`
 
 paul@1007     36 
|| Localised messages for the [[../AgentPrograms|agent programs]] and
 
 paul@1007     37 
.. [[../CalendarManager|management interface]]
 
 paul@1007     38 
==
 
 paul@1007     39 
`tests`
 
 paul@1007     40 
|| A suite of tests used to verify the behaviour of the software
 
 paul@1007     41 
.. (see the [[../Testing|testing guide]])
 
 paul@1007     42 
==
 
 paul@1007     43 
`tools`
 
 paul@1007     44 
|| Tools for [[../Administration|administration]] (see also the
 
 paul@1007     45 
.. [[../GettingStarted|getting started guide]])
 
 paul@1007     46 
}}}
 
 paul@1007     47 
 
 paul@1007     48 
At the top level of the distribution, the following files are found:
 
 paul@1007     49 
 
 paul@1007     50 
{{{#!table
 
 paul@1007     51 
'''File''' || '''Description'''
 
 paul@1007     52 
==
 
 paul@1007     53 
`imip_person.py`
 
 paul@1007     54 
||<rowspan="3"> The main program files for the
 
 paul@1007     55 
             .. [[../AgentPrograms|agent programs]]
 
 paul@1007     56 
==
 
 paul@1007     57 
`imip_person_outgoing.py`
 
 paul@1007     58 
==
 
 paul@1007     59 
`imip_resource.py`
 
 paul@1007     60 
==
 
 paul@1007     61 
`imip_manager.py`
 
 paul@1007     62 
|| The [[../CalendarManager|management interface]] main program file
 
 paul@1007     63 
==
 
 paul@1007     64 
`markup.py`
 
 paul@1007     65 
|| A Python library providing HTML generation support
 
 paul@1007     66 
==
 
 paul@1007     67 
`README.txt`
 
 paul@1007     68 
|| Some basic documentation
 
 paul@1007     69 
==
 
 paul@1007     70 
`vCalendar.py`
 
 paul@1007     71 
||<rowspan="3"> Handling of vCalendar and related data formats
 
 paul@1007     72 
==
 
 paul@1007     73 
`vContent.py`
 
 paul@1007     74 
==
 
 paul@1007     75 
`vRecurrence.py`
 
 paul@1007     76 
}}}
 
 paul@1007     77 
 
 paul@1007     78 
== Architectural Components ==
 
 paul@1007     79 
 
 paul@1007     80 
The principal components of the software architecture are described below.
 
 paul@1007     81 
 
 paul@1007     82 
=== vContent ===
 
 paul@1007     83 
 
 paul@1007     84 
The v-prefixed libraries are concerned with the basic interpretation of
 
 paul@1007     85 
calendar-related data. For the most part, these libraries should already
 
 paul@1007     86 
behave in a predictable and reliable fashion and should not need much
 
 paul@1007     87 
further development. There are perhaps some deficiencies in the
 
 paul@1007     88 
`vRecurrence` module that are described on the
 
 paul@1007     89 
[[../CalendaringSupport|calendaring standards page]].
 
 paul@1007     90 
 
 paul@1007     91 
It is not inconceivable that a `vCard` module be introduced in the future
 
 paul@1007     92 
to handle vCard data, thus enhancing the data about people within
 
 paul@1007     93 
imip-agent, perhaps also supporting mechanisms to obtain free/busy and
 
 paul@1007     94 
other information about scheduling participants.
 
 paul@1007     95 
 
 paul@1007     96 
=== imiptools ===
 
 paul@1007     97 
 
 paul@1007     98 
The bulk of the work done in imip-agent happens within `imiptools`. When
 
 paul@1007     99 
used from [[../AgentPrograms|agent programs]] launched by the mail system,
 
 paul@1007    100 
the different modules support the "handler" functionality that involves
 
 paul@1007    101 
obtaining information from calendar data, performing the necessary action
 
 paul@1007    102 
related to a scheduling method, and generating responses or notifications.
 
 paul@1007    103 
More details are given about these activities in the guide to
 
 paul@1007    104 
[[../IncomingMessages|incoming message handling]].
 
 paul@1007    105 
 
 paul@1007    106 
When used from the [[../CalendarManager|management interface]], the
 
 paul@1007    107 
modules support the Web-based functionality as a more general calendar
 
 paul@1007    108 
system client, typically handling a single calendar object at any given
 
 paul@1007    109 
time.
 
 paul@1007    110 
 
 paul@1069    111 
The `imiptools.stores` package provides the basis for calendar data
 
 paul@1069    112 
persistence. From the very start, the nature of data organisation for
 
 paul@1069    113 
calendar users was centred on the storage of each user's free/busy records,
 
 paul@1069    114 
since the priority was to generate such records from messages exchanged
 
 paul@1069    115 
over e-mail, and the use of plain text files was chosen as the simplest
 
 paul@1069    116 
and most transparent approach. Beyond this, the need to retain calendar
 
 paul@1069    117 
objects arose, and thus a [[../FilesystemUsage|filesystem-based approach]]
 
 paul@1069    118 
was cultivated to manage such data.
 
 paul@1069    119 
 
 paul@1069    120 
In the future, other persistence mechanisms could be supported. However,
 
 paul@1069    121 
aside from performance concerns around access to free/busy schedules,
 
 paul@1069    122 
there may be no urgent need to adopt relational database technologies,
 
 paul@1069    123 
particularly as each user's data should remain isolated from that of
 
 paul@1069    124 
other users, and thus the volumes of data should remain relatively small
 
 paul@1069    125 
if managed well enough.
 
 paul@1069    126 
 
 paul@1007    127 
=== imipweb ===
 
 paul@1007    128 
 
 paul@1007    129 
Most of the `imipweb` package is concerned with the display of calendar
 
 paul@1007    130 
information as Web pages and the handling of submitted data over the Web
 
 paul@1007    131 
as users interact with those Web pages. The `imip_manager.py` file is
 
 paul@1007    132 
deployed as a [[https://tools.ietf.org/html/rfc3875|CGI]] program, and it
 
 paul@1007    133 
acts as a simple "switch" that shows the appropriate kind of Web page (or
 
 paul@1007    134 
"view") depending on the requested URL, delegating to one of the modules
 
 paul@1007    135 
within the `imipweb` package to do so:
 
 paul@1007    136 
 
 paul@1007    137 
|| '''Module'''       || '''View'''        ||
 
 paul@1007    138 
|| `imipweb.calendar` || Calendar          ||
 
 paul@1007    139 
|| `imipweb.event`    || Individual events ||
 
 paul@1007    140 
|| `imipweb.profile`  || User profile      ||
 
 paul@1007    141 
 
 paul@1007    142 
A general `imipweb.resource` module supports the different views with
 
 paul@1007    143 
common functionality. Useful abstractions for period and date information
 
 paul@1007    144 
are provided in the `imipweb.data` module. The CGI interfacing is defined
 
 paul@1007    145 
in the `imipweb.env` module.
 
 paul@1007    146 
 
 paul@1007    147 
One of the most awkward aspects of providing a Web interface to events is
 
 paul@1007    148 
the need to provide a comprehensive enough representation of period data
 
 paul@1007    149 
as expressed in calendar objects that can be held in a form defined in a
 
 paul@1007    150 
Web page, interpreted by the program, written back to the form, all
 
 paul@1007    151 
without losing information.
 
 paul@1007    152 
 
 paul@1009    153 
== Localisation ==
 
 paul@1009    154 
 
 paul@1009    155 
The traditional [[https://www.gnu.org/s/gettext|gettext]] mechanisms for
 
 paul@1009    156 
translating labels, messages and other user-readable strings are employed
 
 paul@1009    157 
in the imip-agent code. Some tools have been provided to maintain this
 
 paul@1009    158 
localisation.
 
 paul@1009    159 
 
 paul@1009    160 
To extract "messages" from the code, run the `tools/i18n_messages.sh`
 
 paul@1009    161 
script:
 
 paul@1009    162 
 
 paul@1009    163 
{{{
 
 paul@1009    164 
tools/i18n_messages.sh
 
 paul@1009    165 
}}}
 
 paul@1009    166 
 
 paul@1009    167 
This produces a file called `imip-agent.pot` in the current directory,
 
 paul@1009    168 
and it also attempts to merge any new messages into the existing message
 
 paul@1009    169 
translations found in the `messages` directory. Such translation files
 
 paul@1009    170 
have the following form:
 
 paul@1009    171 
 
 paul@1009    172 
{{{
 
 paul@1009    173 
messages/xx_XX.imip-agent.po
 
 paul@1009    174 
}}}
 
 paul@1009    175 
 
 paul@1009    176 
Here, `xx` is usually an [[WikiPedia:ISO_639-1|ISO 639-1]] language code,
 
 paul@1009    177 
whereas `XX` is usually an [[WikiPedia:ISO_3166-1|ISO 3166-1]] country code.
 
 paul@1009    178 
 
 paul@1009    179 
Translators should inspect and edit their files in the `messages`
 
 paul@1009    180 
directory and then use the `tools/i18n_format.sh` script to generate the
 
 paul@1009    181 
translations that the software will use:
 
 paul@1009    182 
 
 paul@1009    183 
{{{
 
 paul@1009    184 
tools/i18n_format.sh
 
 paul@1009    185 
}}}
 
 paul@1009    186 
 
 paul@1009    187 
This installs the "compiled" translations into the `locale` directory in
 
 paul@1009    188 
a location of the following form:
 
 paul@1009    189 
 
 paul@1009    190 
{{{
 
 paul@1009    191 
locale/xx_XX/LC_MESSAGES/imip-agent.mo
 
 paul@1009    192 
}}}
 
 paul@1009    193 
 
 paul@1009    194 
The `tools/install.sh` script will copy the `locale` directory into the
 
 paul@1009    195 
installation location unless the `--no-locale-dir` option is given. This is
 
 paul@1009    196 
provided to allow any centrally-installed translations to take precedence
 
 paul@1009    197 
over any locally-available translations.