1. Introduction

While Python-MAPI provides complete Python bindings to interface with Kopano Core, it is not very easy to use. Most importantly, this is because it really operates at the MAPI level, which is to say, it is very low-level and often strange. When looking at programs written using Python-MAPI, one easily gets the impression that a much nicer abstraction layer should be possible.

Python-Kopano aims to provide a high-level, more “Pythonic”, abstraction layer above Python-MAPI. While internally it still uses Python-MAPI, it tries to hide as much of the details as possible from the developer, while still allowing her to dive down into MAPI if needed. Simply put, its main goal is to try and bring the productivity often associated with the Python language itself to developing against Kopano Core.

More specifically, some of the goals of Python-Kopano are as follows:

  • To be a fully object-oriented, Pythonic, layer above MAPI
  • To be usable for many common system administration tasks
  • To provide full access to the underlying MAPI layer if needed
  • To return/accept binary identifiers in readable (hex-encoded) form
  • To raise well-described exceptions if something goes wrong

As of Kopano Core 9.0, Python-Kopano is Python3-only.

1.1. Target audience

This document is mainly targeted at Python developers looking to interact with Kopano Core. MAPI knowledge is not required in most cases, although it can be useful to have at least some experience with basic MAPI concepts such as properties.

1.2. Conventions

When dealing with dates, Python-Kopano accepts and returns standard datetime objects. These are currently always, or always have to be, timezone-unaware and system-local. We intend to add a global flag in the future to enable timezone-aware UTC datetimes.

Usually when an attribute can be read, it can also be set. This is a work in progress however. Let us know when you run into a missing setter which would be useful to have.

item.subject = '!!' + item.subject + '!!'

The Item class uses mixin classes to group specific functionality, such as appointment or contact-related functionality, which means there is currently a _lot_ of functionality in the Item class. We do however separately document the mixin classes.

When contributing patches to Python-Kopano, please follow the PEP-8 style guide.