Difference between revisions of "Python API Wrapper Tutorial"

(View all pending changes)
[unchecked revision][unchecked revision]
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
  
−
This document explains the installation and usage of the Python API Wrapper  library, which is meant to be an example implementation of a MailStore Server Administration API client. The Administration API allows developing scripts for the administration of MailStore Server.
+
<p class=msnote>'''Important notice:''' The MailStore Server Administration API wrapper for Python provided on this website, represents an example implementation of an API client. This wrapper should help system administrators and developers to  quickly understand how to use the Administration API of MailStore Server. Please  understand that beyond this documentation no further support is provided.</p>
  
−
<p class=msnote>'''Please note:''' It is strongly recommended to use a non-productive test environment for this tutorial as well as for script development in general, in order to prevent loss of data or other problems. For example, the 30-day-trial version of MailStore Server is perfectly suited for this.</p>
+
This document explains the installation and usage of the MailStore Server Administration API wrapper for Python. In order to prevent loss of data, service interruption or any other problems, it is highly recommended to use a non-productive test environment for this tutorial as well as for script development in general. The 30-day-trial version of MailStore Server is perfectly suited for this.
  
 
== Installation ==
 
== Installation ==
Line 10: Line 10:
 
Python binaries for various operating systems can be downloaded from the [http://www.python.org/download/ Python download page] or installed using the package manager of most Linux distributions.
 
Python binaries for various operating systems can be downloaded from the [http://www.python.org/download/ Python download page] or installed using the package manager of most Linux distributions.
  
−
Additionally need the [ftp://ftp.mailstore.com/pub/Scripts/Python/Python-MailStore-API-Wrapper.zip Python API Wrapper library] has to be installed in the ''mailstore'' subdirectory of Python's site-packages directory. The location of the site-packages directory can be found by executing the following command:
+
Additionally the [ftp://ftp.mailstore.com/pub/Scripts/Python/Python-MailStore-API-Wrapper.zip Python API Wrapper library] has to be installed in the ''mailstore'' subdirectory of Python's site-packages directory. The location of the site-packages directory can be found by executing the following command:
  
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
Line 33: Line 33:
 
{| class="wikitable"
 
{| class="wikitable"
 
! width="150px" | Parameter
 
! width="150px" | Parameter
−
! Default Value
+
! width="100px" | Default Value
 +
! Description
 
|-
 
|-
 
| <tt>username</tt>
 
| <tt>username</tt>
 
| admin
 
| admin
 +
| Username used for connecting to the API.
 
|-
 
|-
 
| <tt>password</tt>
 
| <tt>password</tt>
 
| admin
 
| admin
 +
| Password used for connecting to the API.
 
|-
 
|-
 
| <tt>host</tt>
 
| <tt>host</tt>
 
| 127.0.0.1
 
| 127.0.0.1
 +
| Hostname or IP address of the MailStore Server computer.
 
|-
 
|-
 
| <tt>port</tt>
 
| <tt>port</tt>
 
| 8463
 
| 8463
 +
| TCP port on which MailStore Server is listening for API requests.
 
|-
 
|-
 
| <tt>autoHandleToken</tt>
 
| <tt>autoHandleToken</tt>
 
| True
 
| True
 +
| If set to ''True'', the caller does not need to handle tokens of long running tasks, but instead has to wait for the result. When set to ''False'' and the ''statusCode'' is ''running'', a status token is returned and must be handled appropriately by the caller of the method. Further details about token handling is described the corresponding section [[#Automatic Token Handling]] of this document.
 
|-
 
|-
 
| <tt>waitTime</tt>
 
| <tt>waitTime</tt>
−
| 1
+
| 1000
 +
| Specifies the number of milliseconds the API should wait for a final result. Otherwise the process is treated as ''running'', in which case token handling as defined by the status of ''autoHandleToken'' becomes necessary.
 +
|-
 +
| <tt>callbackStatus</tt>
 +
| None
 +
| Name of callback function to which interim statuses of long running tasks should be passed. This allows keeping track of the tasks' progress even if  ''autoHandleToken'' is enabled. This can be quite useful in order to notify users about the progress without having to deal with the token logic as a whole.
 
|-
 
|-
 
| <tt>logLevel</tt>
 
| <tt>logLevel</tt>
 
| 2
 
| 2
 +
| Has to be in the range ''0'' to ''4'', where 0 (''NONE'') has the lowest verbosity and 4 (''DEBUG'') the highest. The loglevels are defined in the following order (low to high verbosity) ''NONE'', ''ERROR'', ''WARNING'', ''INFO'' and ''DEBUG''. Log entries will always be printed to ''stdout''.
 
|}
 
|}
  
−
If ''autoHandleToken'' is enabled, you do not have to take care of long running processes. Instead wait for the result. When this value is set to ''False'', a status token is returned must be handled appropriately by the calling script. Further details about long running processes are in the corresponding section of this document.
+
== Invoking API Method ==
−
 
+
After the API client has been successfully instantiated, API methods can easily be invoked. When the method call was successful, the ''statusCode'' is ''succeeded'' and the result is stored in the dictionary ''result'' as shown in the following example:
−
The ''waitTime'' value specifies the value that is passed to the ''get-status'' call. When calling a long running method like ''VerifyStore'', this is the amount of seconds to wait for a status update.
 
−
 
 
−
''logLevel'' has to be in the range ''0'' to ''4'' where loglevel 0 (''NONE'') has the lowest verbosity and 4 (''DEBUG'') the highest. The loglevels are defined in the following order (low to high verbosity) ''NONE'', ''ERROR'', ''WARNING'', ''INFO'' and ''DEBUG''.
 
−
 
 
−
Log entries will always be printed to ''stdout''.
 
−
 
 
−
== Invoking Simple Calls ==
 
−
Simple calls will always return immediately and no token handling is required.
 
  
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
−
print(serverClient.GetServerInfo())
+
print(serverClient.GetServerInfo()["result"])
 
   
 
   
−
{'machineName': 'WIN2012MS', 'version': '8.1.2.9268'}
+
{'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'machineName': 'WIN-2012-R2-X64', 'version': '9.0.3.9857'}, 'statusVersion': 2, 'statusCode': 'succeeded'}
 
</source>
 
</source>
  
−
When the call was successful the information is stored in the returned Python dictionary. When it failed, an error will be thrown (see [[#Exception Handling|Exception Handling]] for further details.
+
If ''autoHanldeToken'' was set to ''False'' and the ''statusCode'' returns ''running'', manual token handling is required as described in the [[#Auto Handle Token]] section.
  
−
=== Examples ===
+
For any other ''statusCode'' an error has to be assumed, in which further information such as the error message and details are available in the dictionary ''error'' as shown below:
−
To get details of all users the following code snippet can be used:
 
  
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
−
serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
+
userInfo = serverClient.GetUserInfo("john.doe")
−
for user in serverClient.GetUserList():
+
 
−
    print(serverClient.GetUserInfo(user["userName"]))
+
if userInfo["statusCode"] == 'succeeded':
 +
    print(userInfo["result"]["emailAddresses"])
 +
else:
 +
    print(userInfo["error"]["message"])
 
</source>
 
</source>
  
−
A list with all assigned email addresses can be retrieved with the following code:
+
=== Examples ===
 +
Create a list of all assigned email addresses.
  
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
 
  serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
 
  serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
−
emailaddresses = list()
+
emailAddresses = list()
−
for user in serverClient.GetUserList():
+
for user in serverClient.GetUsers()["result"]:
−
    emailaddresses += serverClient.GetUserInfo(user["userName"])['emailAddresses']
+
emailAddresses += serverClient.GetUserInfo(user["userName"])["result"]["emailAddresses"]
−
print(emailaddresses)
+
print(emailAddresses)
 
</source>
 
</source>
  
−
== Long Running Calls ==
+
== Long Running Tasks ==
−
The execution of certain API methods like ''VerifyStore'' can take several minutes or even hours until it finishes. These long running calls are executed asynchronously in MailStore Server so you must decide whether to poll for status updates regularly and, in order to output the progress, process them in your own script or let the Python API library silently handle this while waiting for the call to finish.
+
The execution of certain API methods like ''VerifyStore'' typically takes several minutes or even hours until it finishes. There are different options available to deal with these tasks:
 +
 
 +
1) automatic token handling
 +
2) automatic token handling with callback function
 +
3) manual token handling
  
−
=== Invoking ===
+
Generally it is recommended to expect that every method call can become a long running task, depending on the ''waitTime'' value, the called method or the overall load on the server. Thus it is not advisable to globally turn of automatic token handling when instantiating the API client.
−
Automatic token handling can be controlled globally, but also turned on or off per method call. Learn more about token handling in the following sections.
 
  
−
==== Automatic Token Handling ====
+
If desired, automatic token handling can be enabled or disabled for each invoked method by adding ''autoHandleToken=True'' to the method's argument list.
−
When ''autoHandleToken'' is set to ''True'' (default), the API wrapper library polls the status automatically in the background and will return the final result when the process has ended.
 
  
−
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
+
'''Important note:''' Once a method has been invoked, its thread cannot be cancelled. This is not a limitation of the Python wrapper, but of the MailStore Server Administration API itself.  
−
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'}]}
 
−
</source>
 
  
−
==== Manual Token Handling ====
+
=== Automatic Token Handling ===
−
If ''autoHandleToken'' is set to ''False'' the calling script receives the token and must handle it all by itself. To poll for status updates manually call the ''GetStatus'' method and use the status token as parameter. The main call has finished when the ''status'' changed to something else than ''running''.  
+
When ''autoHandleToken'' is set to ''True'' (default), the wrapper polls the status of long running tasks automatically in the background and will return the final result when the process has ended.  
  
 +
==== Code ====
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
−
import time
+
import mailstore
  
−
serverClient = mailstore.server.Client(autoHandleToken=False)  
+
serverClient = mailstore.server.Client(autoHandleToken=True)
−
storeID = 2
+
storeId = 1
−
token = serverClient.VerifyStore(storeID)
+
print(serverClient.VerifyStore(storeId))
−
print(token)
+
</source>
−
while True:
 
−
    time.sleep(1)
 
−
    status = serverClient.GetStatus(token)
 
−
    print(status)
 
−
    if status["status"] != "running":
 
−
        break
 
  
−
{'statusUrl': '/JSON/Status/243fc983-89c3-19ef-196a-dbe082894cc5', 'statusToken': '243fc983-89c3-19ef-196a-dbe082894cc5'}
+
==== Output ====
−
{'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'}
+
<source lang="text" smart-tabs="true" toolbar="false" gutter="false">
−
{'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'}
+
{'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'd242d822a59bd4db308eef8b85af7d2a', 'result': None, 'statusVersion': 71, 'statusCode': 'succeeded'}
 
</source>
 
</source>
  
−
Passing the status token to the ''HandleToken'' method will result in exactly the same behavior as if ''autoHandleToken=True'' would have been set.
+
=== Automatic Token Handling with Callback Function ===
 +
If a caller wants to keep track of the progress of a long running task (i.e. to inform the user about the progress), although automatic token handling was enabled, he could pass the name of a function as value of the ''callbackStatus'' argument to the instance of the API client.
  
 +
==== Code ====
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
 
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
−
serverClient = mailstore.server.Client(autoHandleToken=False)
+
import mailstore
−
storeID = 2
 
−
token = serverClient.VerifyStore(storeID)
 
−
print(token)
 
−
print(serverClient.HandleToken(token))
 
−
</source>
 
  
−
==== Selective Token Handling ====
+
def showProgress(progress):
−
The Token handling behavior can be modified globally and locally. If the API client was instantiated with ''autoHandleToken=True'', each method can still be called with ''autoHandleToken=False'' and vice versa to disable or enable automatic token handling whenever necessary. Methods that do not return a token, do not accept the ''autoHandleToken'' parameter.
+
  print(progress["logOutput"], end="")
  
−
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
+
serverClient = mailstore.server.Client(autoHandleToken=True, callbackStatus=showProgress)
−
serverClient = mailstore.server.Client(autoHandleToken=False)
+
storeId = 3
−
storeID = 2
+
print(serverClient.VerifyStore(storeId))
−
token = serverClient.VerifyStore(storeID, autoHandleToken=True)
+
</source>
−
print(token)
 
  
−
{'status': 'succeeded', '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'}], 'progressPercentage': 100}
+
==== Output ====
 +
<source lang="text" smart-tabs="true" toolbar="false" gutter="false">
 +
Verifying file group #3...
 +
Creating a list of messages to be verified...
 +
1249 messages are about to be verified.
 +
Verifying...
 +
  100 messages verified...
 +
  200 messages verified...
 +
  300 messages verified...
 +
  400 messages verified...
 +
  500 messages verified...
 +
  600 messages verified...
 +
  700 messages verified...
 +
  800 messages verified...
 +
  900 messages verified...
 +
  1000 messages verified...
 +
  1100 messages verified...
 +
  1200 messages verified...
 +
  1249 messages verified.
 +
Finished. No errors have been found.
 +
{'error': None, 'result': None, 'logOutput': '  1000 messages verified...\r\n  1100 messages verified...\r\n  1200 messages verified...\r\n 1249 messages verified.\r\nFinished. No errors have been found.\r\n', 'token': 'c56f032d9db263133c1a413f79744b84', 'statusVersion': 71, 'statusText': None, 'percentProgress': 100, 'statusCode': 'succeeded'}
 
</source>
 
</source>
  
−
=== Cancelling ===
+
=== Manual Token Handling ===
−
Currently long running calls cannot be cancelled. This is not a limitation of the Python wrapper, but of the MailStore Management API itself. This will be changed in the next major release of MailStore Server.
+
If ''autoHandleToken'' is set to ''False'' the caller must handle the token all by itself. To poll for status updates manually call the  ''GetStatus'' method and use the last returned value as parameter. ''GetStatus'' will extract the  status token itself, poll for the latest update and return the received data to the caller again. The main call has finished when the ''statusCode'' changed to something different than ''running''. Calling ''GetStatus'' without passing a status token will result in a corresponding exception.
  
−
=== Exception Handling ===
+
==== Code ====
−
 
+
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
−
When there are no errors, the returned value is always a python dictionary.
+
import mailstore
 +
import time
  
−
In case an error occurred, the call will raise an ''Exception''. All MailStore Exceptions are derived from ''mailstore.errors.MailStoreBaseError'' which itself is derived from ''Exception''.
+
serverClient = mailstore.server.Client(password="Passw0rd", host="192.168.250.217", autoHandleToken=False)
 +
storeID = 3
 +
status = serverClient.VerifyStore(storeID)
  
−
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
+
while True:
−
try:
+
    if status["statusCode"] != "running":
−
    print(serverClient.GetUserInfo("not_such_user"))
+
        break
−
except mailstore.errors.MailStoreBaseError as e:
+
    print(status["logOutput"], end="")
−
    print(e)
+
    status = serverClient.GetStatus(status)
−
+
    time.sleep(1)
−
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
 
 
</source>
 
</source>
  
−
== Pretty Printing the Output ==
+
==== Output ====
−
 
+
<source lang="text" smart-tabs="true" toolbar="false" gutter="false">
−
There is a helper function that formats the returned values in more readable manner.
+
Verifying file group #3...
−
 
+
Creating a list of messages to be verified...
−
<source lang="python" smart-tabs="true" toolbar="false" gutter="false">
+
1249 messages are about to be verified.
−
mailstore.pprint(serverClient.GetUserInfo("admin"))
+
Verifying...
−
 
+
  100 messages verified...
−
authentication integrated
+
  200 messages verified...
−
distinguishedName
+
  300 messages verified...
−
privileges
+
  400 messages verified...
−
    admin
+
  500 messages verified...
−
fullName Administrator
+
  600 messages verified...
−
userName admin
+
  700 messages verified...
 +
  800 messages verified...
 +
  900 messages verified...
 +
  1000 messages verified...
 +
  1100 messages verified...
 +
  1200 messages verified...
 +
  1249 messages verified.
 +
Finished. No errors have been found.
 
</source>
 
</source>
  
 
== Methods Overview ==
 
== Methods Overview ==
 +
All the methods listed in [[MailStore_Server_Administration_API_Commands|the method overview]] are implemented in the Python API library. Use
  
−
All the methods listed in [[MailStore_Server_Administration_API_Commands|the method overview]] are implemented in the Python API library.
+
  pydoc mailstore.server
  
−
Additional (helper) methods available. Please refer to the source code of the API wrapper library for further details.
+
to access the build in documentation, which also includes an overview of all methods and their parameters.
  
 
[[de:Python API-Wrapper Tutorial]]
 
[[de:Python API-Wrapper Tutorial]]
 
[[en:Python API Wrapper Tutorial]]
 
[[en:Python API Wrapper Tutorial]]

Revision as of 16:39, 25 August 2014


Important notice: The MailStore Server Administration API wrapper for Python provided on this website, represents an example implementation of an API client. This wrapper should help system administrators and developers to quickly understand how to use the Administration API of MailStore Server. Please understand that beyond this documentation no further support is provided.

This document explains the installation and usage of the MailStore Server Administration API wrapper for Python. In order to prevent loss of data, service interruption or any other problems, it is highly recommended to use a non-productive test environment for this tutorial as well as for script development in general. The 30-day-trial version of MailStore Server is perfectly suited for this.

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.

Python binaries for various operating systems can be downloaded from the Python download page or installed using the package manager of most Linux distributions.

Additionally the Python API Wrapper library has to be installed in the mailstore subdirectory of Python's site-packages directory. The location of the site-packages directory can be found by executing the following command: 

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

Instantiating the API Client

Before the API wrapper library can be used, it must first be imported with: 

 import mailstore

Now the mailstore.server.Client class can be instantiated as follows: 

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

Default values can be omitted. The default admin credentials (username and password set to admin) are only usable when connecting from the MailStore Server computer itself to localhost. Find a listing of all default values in the following table:

Parameter Default Value Description
username admin Username used for connecting to the API.
password admin Password used for connecting to the API.
host 127.0.0.1 Hostname or IP address of the MailStore Server computer.
port 8463 TCP port on which MailStore Server is listening for API requests.
autoHandleToken True If set to True, the caller does not need to handle tokens of long running tasks, but instead has to wait for the result. When set to False and the statusCode is running, a status token is returned and must be handled appropriately by the caller of the method. Further details about token handling is described the corresponding section #Automatic Token Handling of this document.
waitTime 1000 Specifies the number of milliseconds the API should wait for a final result. Otherwise the process is treated as running, in which case token handling as defined by the status of autoHandleToken becomes necessary.
callbackStatus None Name of callback function to which interim statuses of long running tasks should be passed. This allows keeping track of the tasks' progress even if autoHandleToken is enabled. This can be quite useful in order to notify users about the progress without having to deal with the token logic as a whole.
logLevel 2 Has to be in the range 0 to 4, where 0 (NONE) has the lowest verbosity and 4 (DEBUG) the highest. The loglevels are defined in the following order (low to high verbosity) NONE, ERROR, WARNING, INFO and DEBUG. Log entries will always be printed to stdout.

Invoking API Method

After the API client has been successfully instantiated, API methods can easily be invoked. When the method call was successful, the statusCode is succeeded and the result is stored in the dictionary result as shown in the following example: 

print(serverClient.GetServerInfo()["result"])
 
{'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'machineName': 'WIN-2012-R2-X64', 'version': '9.0.3.9857'}, 'statusVersion': 2, 'statusCode': 'succeeded'}

If autoHanldeToken was set to False and the statusCode returns running, manual token handling is required as described in the #Auto Handle Token section.

For any other statusCode an error has to be assumed, in which further information such as the error message and details are available in the dictionary error as shown below: 

userInfo = serverClient.GetUserInfo("john.doe")

if userInfo["statusCode"] == 'succeeded':
    print(userInfo["result"]["emailAddresses"])
else:
    print(userInfo["error"]["message"])

Examples

Create a list of all assigned email addresses. 

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

Long Running Tasks

The execution of certain API methods like VerifyStore typically takes several minutes or even hours until it finishes. There are different options available to deal with these tasks:

1) automatic token handling 2) automatic token handling with callback function 3) manual token handling

Generally it is recommended to expect that every method call can become a long running task, depending on the waitTime value, the called method or the overall load on the server. Thus it is not advisable to globally turn of automatic token handling when instantiating the API client.

If desired, automatic token handling can be enabled or disabled for each invoked method by adding autoHandleToken=True to the method's argument list.

Important note: Once a method has been invoked, its thread cannot be cancelled. This is not a limitation of the Python wrapper, but of the MailStore Server Administration API itself.

Automatic Token Handling

When autoHandleToken is set to True (default), the wrapper polls the status of long running tasks automatically in the background and will return the final result when the process has ended.

Code

import mailstore

serverClient = mailstore.server.Client(autoHandleToken=True)
storeId = 1
print(serverClient.VerifyStore(storeId))

Output

{'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'd242d822a59bd4db308eef8b85af7d2a', 'result': None, 'statusVersion': 71, 'statusCode': 'succeeded'}

Automatic Token Handling with Callback Function

If a caller wants to keep track of the progress of a long running task (i.e. to inform the user about the progress), although automatic token handling was enabled, he could pass the name of a function as value of the callbackStatus argument to the instance of the API client.

Code

import mailstore

def showProgress(progress):
   print(progress["logOutput"], end="")

serverClient = mailstore.server.Client(autoHandleToken=True, callbackStatus=showProgress)
storeId = 3
print(serverClient.VerifyStore(storeId))

Output

Verifying file group #3...
Creating a list of messages to be verified...
1249 messages are about to be verified.
Verifying...
  100 messages verified...
  200 messages verified...
  300 messages verified...
  400 messages verified...
  500 messages verified...
  600 messages verified...
  700 messages verified...
  800 messages verified...
  900 messages verified...
  1000 messages verified...
  1100 messages verified...
  1200 messages verified...
  1249 messages verified.
Finished. No errors have been found.
{'error': None, 'result': None, 'logOutput': '  1000 messages verified...\r\n  1100 messages verified...\r\n  1200 messages verified...\r\n  1249 messages verified.\r\nFinished. No errors have been found.\r\n', 'token': 'c56f032d9db263133c1a413f79744b84', 'statusVersion': 71, 'statusText': None, 'percentProgress': 100, 'statusCode': 'succeeded'}

Manual Token Handling

If autoHandleToken is set to False the caller must handle the token all by itself. To poll for status updates manually call the GetStatus method and use the last returned value as parameter. GetStatus will extract the status token itself, poll for the latest update and return the received data to the caller again. The main call has finished when the statusCode changed to something different than running. Calling GetStatus without passing a status token will result in a corresponding exception.

Code

import mailstore
import time

serverClient = mailstore.server.Client(password="Passw0rd", host="192.168.250.217", autoHandleToken=False)
storeID = 3
status = serverClient.VerifyStore(storeID)

while True:
    if status["statusCode"] != "running":
        break
    print(status["logOutput"], end="")
    status = serverClient.GetStatus(status)
    time.sleep(1)

Output

Verifying file group #3...
Creating a list of messages to be verified...
1249 messages are about to be verified.
Verifying...
  100 messages verified...
  200 messages verified...
  300 messages verified...
  400 messages verified...
  500 messages verified...
  600 messages verified...
  700 messages verified...
  800 messages verified...
  900 messages verified...
  1000 messages verified...
  1100 messages verified...
  1200 messages verified...
  1249 messages verified.
Finished. No errors have been found.

Methods Overview

All the methods listed in the method overview are implemented in the Python API library. Use 

 pydoc mailstore.server

to access the build in documentation, which also includes an overview of all methods and their parameters.

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