zarafa package

Module contents

High-level python bindings for Zarafa

Copyright 2014 Zarafa and contributors, license AGPLv3 (see LICENSE file for details)

Some goals:

  • To be 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 all text as unicode strings
  • To return/accept binary identifiers in readable (hex-encoded) form
  • To raise well-described exceptions if something goes wrong

Main classes:

Server

Store

User

Company

Store

Folder

Item

Body

Attachment

Address

Outofoffice

Quota

Config

Service

class zarafa.Server

Server class

By default, tries to connect to a Zarafa server as configured in /etc/zarafa/admin.cfg or at UNIX socket /var/run/zarafa

Looks at command-line to see if another server address or other related options were given (such as -c, -s, -k, -p)

Parameters:
  • server_socket – similar to ‘server_socket’ option in config file
  • sslkey_file – similar to ‘sslkey_file’ option in config file
  • sslkey_pass – similar to ‘sslkey_pass’ option in config file
  • config – path of configuration file containing common server options, for example /etc/zarafa/admin.cfg
  • auth_user – username to user for user authentication
  • auth_pass – password to use for user authentication
  • log – logger object to receive useful (debug) information
  • options – OptionParser instance to get settings from (see parser())
guid

Server GUID

user(name, create=False)

Return user with given name; raise exception if not found

get_user(name)

Return user with given name or None if not found

users(remote=False, system=False, parse=True)

Return all users on server

Parameters:
  • remote – include users on remote server nodes
  • system – include system users
create_user(name, email=None, password=None, company=None, fullname=None, create_store=True)

Create a new user on the server

Parameters:
  • name – the login name of the new user
  • email – the email address of the user
  • password – the login password of the user
  • company – the company of the user
  • fullname – the full name of the user
  • create_store – should a store be created for the new user
Returns:

<User>

company(name, create=False)

Return company with given name; raise exception if not found

get_company(name)

Return company with given name or None if not found

companies(remote=False, parse=True)

Return all companies on server

Parameters:remote – include companies without users on this server node
store(guid)

Return store with given GUID; raise exception if not found

get_store(guid)

Return store with given GUID or None if not found

stores(system=False, remote=False, parse=True)

Return all stores on server node

Parameters:
  • system – include system stores
  • remote – include stores on other nodes
public_store

public store in single-company mode

state

Current server state

sync(importer, state, log=None, max_changes=None, window=None)

Perform synchronization against server node

Parameters:
  • importer – importer instance with callbacks to process changes
  • state – start from this state (has to be given)
Log :

logger instance to receive important warnings/errors

class zarafa.Store

Item store

entryid

Store entryid

guid

Store GUID

root

Folder designated as store root

inbox

Folder designated as inbox

junk

Folder designated as junk

calendar

Folder designated as calendar

outbox

Folder designated as outbox

contacts

Folder designated as contacts

drafts

Folder designated as drafts

wastebasket

Folder designated as wastebasket

journal

Folder designated as journal

notes

Folder designated as notes

sentmail

Folder designated as sentmail

tasks

Folder designated as tasks

subtree

Folder designated as IPM.Subtree

suggested_contacts

:class`Folder` designated as Suggested contacts

rss

:class`Folder` designated as RSS items

folder(key, recurse=False, create=False)

Return Folder with given name or entryid; raise exception if not found

Parameters:key – name or entryid
get_folder(key)

Return folder with given name/entryid or None if not found

folders(recurse=True, mail=False, parse=True)

Return all folders in store

Parameters:
  • recurse – include all sub-folders
  • system – include system folders
  • mail – only include mail folders
item(entryid)

Return Item with given entryid; raise exception of not found

size

Store size

last_logon

Return :datetime Last logon of a user on this store

last_logoff

Return :datetime of the last logoff of a user on this store

outofoffice

Return Outofoffice

user

Store owner

class zarafa.User

User class

name

Account name

fullname

Full name

email

Email address

userid

Userid

company

Company the user belongs to

store

Default Store for user or None if no store is attached

archive_store

Archive Store for user or None if not found

quota

User Quota

outofoffice

User Outofoffice

class zarafa.Company

Company class

name

Company name

public_store

Company public store

user(name, create=False)

Return user with given name; raise exception if not found

get_user(name)

Return user with given name or None if not found

users()

Return all users within company

quota

Company Quota

class zarafa.Store

Item store

entryid

Store entryid

guid

Store GUID

root

Folder designated as store root

inbox

Folder designated as inbox

junk

Folder designated as junk

calendar

Folder designated as calendar

outbox

Folder designated as outbox

contacts

Folder designated as contacts

drafts

Folder designated as drafts

wastebasket

Folder designated as wastebasket

journal

Folder designated as journal

notes

Folder designated as notes

sentmail

Folder designated as sentmail

tasks

Folder designated as tasks

subtree

Folder designated as IPM.Subtree

suggested_contacts

:class`Folder` designated as Suggested contacts

rss

:class`Folder` designated as RSS items

folder(key, recurse=False, create=False)

Return Folder with given name or entryid; raise exception if not found

Parameters:key – name or entryid
get_folder(key)

Return folder with given name/entryid or None if not found

folders(recurse=True, mail=False, parse=True)

Return all folders in store

Parameters:
  • recurse – include all sub-folders
  • system – include system folders
  • mail – only include mail folders
item(entryid)

Return Item with given entryid; raise exception of not found

size

Store size

last_logon

Return :datetime Last logon of a user on this store

last_logoff

Return :datetime of the last logoff of a user on this store

outofoffice

Return Outofoffice

user

Store owner

class zarafa.Folder

Item Folder

entryid

Folder entryid

parent

Return parent or None

subfolder_count

Number of direct subfolders

name

Folder name

container_class

Property which describes the type of items a folder holds, possible values * IPF.Appointment * IPF.Contact * IPF.Journal * IPF.Note * IPF.StickyNote * IPF.Task

https://msdn.microsoft.com/en-us/library/aa125193(v=exchg.65).aspx

unread

Number of unread items

item(entryid)

Return Item with given entryid; raise exception of not found

items()

Return all items in folder, reverse sorted on received date

empty(recurse=True, associated=False)

Delete folder contents

Parameters:
  • recurse – delete subfolders
  • associated – delete associated contents
size

Folder size

count

Number of items in folder

Parameters:recurse – include items in sub-folders
folder(key, recurse=False, create=False)

Return Folder with given name or entryid; raise exception if not found

Parameters:key – name or entryid
get_folder(key)

Return folder with given name/entryid or None if not found

folders(recurse=True, depth=0)

Return all sub-folders in folder

Parameters:recurse – include all sub-folders
state

Current folder state

sync(importer, state=None, log=None, max_changes=None, associated=False, window=None)

Perform synchronization against folder

Parameters:
  • importer – importer instance with callbacks to process changes
  • state – start from this state; if not given sync from scratch
Log :

logger instance to receive important warnings/errors

associated

Associated folder containing hidden items

class zarafa.Item

Item

entryid

Item entryid

sourcekey

Item sourcekey

subject

Item subject or None if no subject

size

Item size

body

Item body

received

Datetime instance with item delivery time

stubbed

Is item stubbed by archiver?

read

Return boolean which shows if a message has been read

folder

Parent Folder of an item

importance

Importance

attachments(embedded=False)

Return item attachments

Parameters:embedded – include embedded attachments
header(name)

Return transport message header with given name

headers()

Return transport message headers

eml()

Return .eml version of item

sender

Sender Address

recipients()

Return recipient addresses

class zarafa.Body

Body

text

Plain text representation

html

HTML representation

rtf

RTF representation

type_

original body type: ‘text’, ‘html’, ‘rtf’ or None if it cannot be determined

class zarafa.Attachment

Attachment

mimetype

Mime-type or None if not found

filename

Filename or None if not found

size

Size

data

Binary data

class zarafa.Address

Address

name

Full name

email

Email address

class zarafa.Outofoffice

Outofoffice class

Class which contains a store out of office properties and can set out-of-office status, message and subject.

Parameters:storestore
enabled

Out of office enabled status

subject

Subject

message

Message

start

Out-of-office is activated from the particular datetime onwards

end

Out-of-office is activated until the particular datetime

update(**kwargs)

Update function for outofoffice

class zarafa.Quota

Quota class

Quota limits are stored in bytes.

warning_limit

Warning limit

soft_limit

Soft limit

hard_limit

Hard limit

update(**kwargs)

Update function for Quota limits, currently supports the following kwargs: warning_limit, soft_limit and hard_limit.

TODO: support defaultQuota and IsuserDefaultQuota

class zarafa.Config

Configuration class

Parameters:config – dictionary describing configuration options. TODO describe available options

Example:

config = Config({
    'some_str': Config.String(default='blah'),
    'number': Config.Integer(),
    'filesize': Config.size(), # understands '5MB' etc
})
class zarafa.Service

Encapsulates everything to create a simple Zarafa service, such as:

  • Locating and parsing a configuration file
  • Performing logging, as specifified in the configuration file
  • Handling common command-line options (-c, -F)
  • Daemonization (if no -F specified)
Parameters:
  • name – name of the service; if for example ‘search’, the configuration file should be called /etc/zarafa/search.cfg or passed with -c
  • configConfiguration to use
  • options – OptionParser instance to get settings from (see parser())
zarafa.parser(options='cskpUPufmvCSlbe', usage=None)

Return OptionParser instance from the standard optparse module, containing common zarafa command-line options

Parameters:options – string containing a char for each desired option, default “cskpUPufmvV”

Available options:

-c, –config: Path to configuration file

-s, –server-socket: Zarafa server socket address

-k, –sslkey-file: SSL key file

-p, –sslkey-password: SSL key password

-U, –auth-user: Login as user

-P, –auth-pass: Login with password

-C, –company: Run program for specific company

-u, –user: Run program for specific user

-S, –store: Run program for specific store

-f, –folder: Run program for specific folder

-b, –period-begin: Run program for specific period

-e, –period-end: Run program for specific period

-F, –foreground: Run service in foreground

-m, –modify: Enable database modification (python-zarafa does not check this!)

-l, –log-level: Set log level (debug, info, warning, error, critical)

-I, –input-dir: Specify input directory

-O, –output-dir: Specify output directory

-v, –verbose: Enable verbose output (python-zarafa does not check this!)

-V, –version: Show program version and exit

zarafa.log_exc(*args, **kwds)

Context-manager to log any exception in sub-block to given logger instance

Parameters:log – logger instance

Example usage:

with log_exc(log):
    .. # any exception will be logged when exiting sub-block