Difference between revisions of "Python API Wrapper Tutorial"

(Created page with "__NOTOC__ This document introduces the Python API library which allows you to administer your MailStore Server via Python. = Installation = The API library is tested agains...")
(No difference)

Revision as of 12:35, 4 April 2014


This document introduces the Python API library which allows you to administer your MailStore Server via Python.

Installation

The API library is tested against Python 3.2 to Python 3.4. It is compatible with the 32bit and the 64bit versions of Python.

You can get your Python binary from the Python download page or you can install it using the package manager of you distribution.

Additionally you need the MailStore API library which has to be installed in your Python's site-packages mailstore directory. The location of the site-packages directory can be found with the following command 

 python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"

Log in

The library can be imported with 

 import mailstore

and now you are able to instantiate the the mailstore.server.Client class 

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)

Default values can be omitted.

The available log in arguments and default values are 

 username = "admin"
 password = "admin"
 host = "127.0.0.1"
 port = 8463
 autoHandleToken = True
 waitTime = 1
 logLevel = 2

When autoHandleToken is enabled, you do not have to care about long running processes, you just have to wait for the result. When this value is set to False, then the status token is returned and you have to handle the token manually. More about this later.

The waitTime value specifies the value that is passed to the get-status call. When you call a long running method like VerifyStore, this is the amount of seconds you have to wait for a status update.

logLevel has to be in the range 0 to 4. The loglevels are defined as following 

0 : "NONE"
1 : "ERROR"
2 : "WARNING"
3 : "INFO" 
4 : "DEBUG"

Log entries will be printed to stdout.

Simple calls

Simple calls will return immediately 

 print(serverClient.GetServerInfo())
 
 {'machineName': 'WIN2012MS', 'version': '8.1.2.9268'}

When the call was succesfull the information is stored in the returned Python dictionary. When the has failed, an HTTP error will be thrown.

When there are no HTTP errors, the returned value is always a python dictionary.

When an error happens, the call will raise an Exception. All MailStore Exceptions are derived from mailstore.errors.MailStoreBaseError which itself is derived from Exception. 

 try:
     print(serverClient.GetUserInfo("not_such_user"))
 except mailstore.errors.MailStoreBaseError as e:
     print(e)
 
 ERROR ('internal MailStore Server error',)
 500 Internal Server Error https://127.0.0.1:8463/JSON/Invoke/GetUserInfo POST userName=not_such_user Command in MethodList: True

Simple examples

To get all user's detailed information you could 

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
 for user in serverClient.GetUserList():
     print(serverClient.GetUserInfo(user["userName"]))

A list with all assigned email address can be retrieved with 

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
 emailaddresses = list()
 for user in serverClient.GetUserList():
     emailaddresses += serverClient.GetUserInfo(user["userName"])['emailAddresses']
 print(emailaddresses)

Long running calls

Long running calls like VerifyStore are running asynchronous on the server. When autoHandleToken is set to True (default), the library polls the status in the background automatically and will return the final result when the process has ended. Set autoHandleToken to False to get the token. In this case you have to handle the token by yourself. There are helper methods available. 

 serverClient = mailstore.server.Client(autoHandleToken=True)
 storeID = 1
 print(serverClient.VerifyStore(storeID))
 
 {'status': 'succeeded', 'progressPercentage': 100, 'messages': [{'text': 'Verifying file group #2...', 'type': 'line'}, {'text': 'Creating a list of messages to be verified...', 'type': 'line'}, {'text': '234 messages are about to be verified.', 'type': 'line'}, {'text': 'Verifying...', 'type': 'line'}, {'text': '  100 messages verified...', 'type': 'line'}, {'text': '  200 messages verified...', 'type': 'line'}, {'text': '  234 messages verified.', 'type': 'line'}, {'text': 'Finished. No errors have been found.', 'type': 'line'}]}

You are able to update the status manually by passing the token to the GetStatus method. The call has finished, when the status has changed from running to something else. 

 import time

 serverClient = mailstore.server.Client(autoHandleToken=False)   
 storeID = 2
 token = serverClient.VerifyStore(storeID)
 print(token)
 while True:
     time.sleep(1)
     status = serverClient.GetToken(token)
     print(status)
     if status["status"] != "running":
         break

 {'statusUrl': '/JSON/Status/243fc983-89c3-19ef-196a-dbe082894cc5', 'statusToken': '243fc983-89c3-19ef-196a-dbe082894cc5'}
 {'progressPercentage': 0, 'messages': [{'type': 'line', 'text': 'Verifying file group #2...'}, {'type': 'line', 'text': 'Creating a list of messages to be verified...'}, {'type': 'line', 'text': '234 messages are about to be verified.'}, {'type': 'line', 'text': 'Verifying...'}, {'type': 'line', 'text': '  100 messages verified...'}], 'status': 'running'}
 {'progressPercentage': 100, 'messages': [{'type': 'line', 'text': 'Verifying file group #2...'}, {'type': 'line', 'text': 'Creating a list of messages to be verified...'}, {'type': 'line', 'text': '234 messages are about to be verified.'}, {'type': 'line', 'text': 'Verifying...'}, {'type': 'line', 'text': '  100 messages verified...'}, {'type': 'line', 'text': '  200 messages verified...'}, {'type': 'line', 'text': '  234 messages verified.'}, {'type': 'line', 'text': 'Finished. No errors have been found.'}], 'status': 'succeeded'}

One could pass the token to the HandleToken method, then the behavior is exactly the same, as when you would have set autoHandleToken=True. 

 with mailstore.spe.Client(autoHandleToken=False) as client:
     instID = "test01"
     storeID = 38
     token = client.VerifyStore(instID, storeID)
     print(client.HandleToken(token))
 
 {'antiXsrfToken': 'KIMJdCpjcuD8O5+xPislG8OysJ0fPgXQcvHQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n  100 messages verified...\r\n  200 messages verified...\r\n  300 messages verified...\r\n  389 messages verified...\r\nFinished. No errors have been found.\r\n', 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'sa8e56590b28b3c57f076168d5913840df', 'result': None, 'statusVersion': 147, 'statusCode': 'succeeded'}

Alternatively one could pass the token to the HandleTokenIter method, then every status update is yielded. 

 with mailstore.spe.Client(autoHandleToken=False) as client:
     instID = "test01"
     storeID = 38
     for status in client.HandleTokenIter(client.VerifyStore(instID, storeID)):
         print(status)
 
 {'antiXsrfToken': 'DEF2dWnoNl7hkgsHqApPZmpsUqEgpih6c/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n389 messages are about to be verified.\r\nVerifying...\r\n', 'statusText': None, 'error': None, 'percentProgress': 0, 'token': 'safd22a51408925dd787ef43a5adc3772c', 'result': None, 'statusVersion': 5, 'statusCode': 'running'}
 {'antiXsrfToken': 'a3NMb7VdnLaTOOnfyJnZWEutbmlzPXd6c/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 6, 'statusCode': 'running'}
 {'antiXsrfToken': 'mi8qpqTdw6hoH+/+o6h65Rx0jiuPR4p6c/HQCGFkbWlu', 'logOutput': '  100 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 1, 'token': None, 'result': None, 'statusVersion': 7, 'statusCode': 'running'}
 [...]

You are able to set the token handling behavior globally and locally. When you instantiate the client with autoHandleToken=True you still are able to call every long running method with autoHandleToken=False and vice versa. Methods that do not return a token, do not accecpt the autoHandleToken parameter. 

 with mailstore.spe.Client(autoHandleToken=True) as client:
     instID = "test01"
     client.MaintainFileSystemDatabases(instID, autoHandleToken=False)

Cancelling long running calls

If you want to cancel a long running call, you have to pass the token of that call to the CancelAsync method 

 import time
 
 with mailstore.spe.Client(autoHandleToken=False) as client:
     instID = "test01"
     storeID = 38
     token = client.VerifyStore(instID, storeID)
     time.sleep(2)
     print(client.CancelAsync(token))
     time.sleep(2)
     print(client.GetStatus(token))
 
 {'antiXsrfToken': 'DUs5EO8ZZ9A8S6lUB/uYwIsAFwTufVpCd/HQCGFkbWlu', 'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': None, 'statusVersion': None, 'statusCode': None}
 {'antiXsrfToken': 'fYO6hoP7eKr1X1SDj++6hhwI9pTwD45Dd/HQCGFkbWlu', 'logOutput': 'Verifying file group #38...\r\nCreating a list of messages to be verified...\r\n3893 messages are about to be verified.\r\nVerifying...\r\n  100 messages verified...\r\n  200 messages verified...\r\n  300 messages verified...\r\n', 'statusText': None, 'error': None, 'percentProgress': 7, 'token': None, 'result': None, 'statusVersion': 17, 'statusCode': 'cancelled'}

Pretty Printing the output

There is a helper function that formats the returned values in more readable manner. 

 mailstore.spe.pprint(client.GetUserInfo("test01","admin"))

 antiXsrfToken lVKkLrjBXeg7KcjdZ/n6050bpfdAILI9F/3QCGFkbWlu
 result
    userName    admin
    privileges
       admin
    authentication    integrated
    fullName    admin
 statusVersion 2
 statusCode succeeded

The CallMethod method

The signature of the CallMethod method is 

CallMethod(self, methodname, arguments = {}, autoHandleToken = None)

This is the most low-level method available. You are able to send "raw" commands to this method.

Function overview

All the methods listed in Function Reference are implemented.

Additional methods

There are additional methods available. Please see the source code for further details.

Retrieved from "https://help.mailstore.com/en/server/index.php?title=Python_API_Wrapper_Tutorial&oldid=4145"