[RELEASE] pyTSon - A python plugin

[Thomas]

pyTSon

**CAUTION** This is currently alpha software, so it can (and I guess, it will!) crash your client. Callbacks and ts3lib functions need to be tested. So please don't bomb TeamSpeak Systems with crashdumps if you are using this plugin.

pyTSon is a Python plugin for your TeamSpeak 3 client. It offers a python3 (current used version is Python 3.5.7) interface for the plugin sdk. This plugin makes your client scriptable, react on events or write your subroutines callable by hotkeys or from the client's menu.


Batteries included
Did I miss the lua plugin? No, I didn't. The advantage of pyTSon is, that all ts3lib functions the pluginsdk offers are wrapped and all callbacks are accessible (see "What is missing?" down below for some exceptions).
The creation process of a script is much easier, just create a new file with your plugin-class in scripts/ and you are done.

The python standard library is included, either built in the plugin or bundled in include/Lib (which is in sys.path by default). pyTSon has PythonQt included, so that scripts can have UIs written in python, see pyTSon's own configdialog or the scripting console for examples (includes/pytsonui.py). So Qt classes are wrapped into the PythonQt.* modules and there is no external dependency, the TeamSpeak 3 client's Qt libraries are used (so don't create a new QApplication object, the client ones is used!). See http://pythonqt.sourceforge.net/Developer.html for more info on using PythonQt in your scripts.
But be carefull! If you mess up with some internals (like QApplication or Qt's eventloop), you might crash your client. Safest way to be sure, that objects are cleared, is to set the WA_DeleteOnClose attribute on your dialogs or widgets or such.


How do I write a plugin?
Here is a small example plugin:

from ts3plugin import ts3plugin

import ts3lib, ts3defines

class testplugin(ts3plugin):
    name = "test"
    requestAutoload = False
    version = "1.0"
    apiVersion = 21
    author = "Thomas \"PLuS\" Pathmann"
    description = "This is a testplugin"
    offersConfigure = True
    commandKeyword = ""
    infoTitle = ""
    menuItems = []#[(ts3defines.PluginMenuType.PLUGIN_MENU_TYPE_CLIENT, 0, "text", "icon.png")]
    hotkeys = []#[("keyword", "description")]

    def __init__(self):
        ts3lib.printMessageToCurrentTab("Yay, we are running!")

    def stop(self):
        ts3lib.printMessageToCurrentTab("Oh no, we were stopped :(")

    def onNewChannelEvent(self, schid, channelID, channelParentID):
        err, name = ts3lib.getChannelVariableAsString(schid, channelID, ts3defines.ChannelProperties.CHANNEL_NAME)
        if err == ts3defines.ERROR_ok:
            ts3lib.printMessageToCurrentTab("new channel %s" % name)
        else:
            ts3lib.printMessageToCurrentTab("got error %s" % err)

Just create a subclass of ts3plugin and create any callback you wanna react to as method of your class. The 11 class attributes (name, requestAutoload, ..., hotkeys) are needed, otherwise pyTSon refuses to load your script. Your plugin is loaded as a python plugin, so create a subdirectory in the scripts folder.
If you are familiar with the C pluginsdk, you'll get the idea. Otherwise look at docs/pyTSon.pdf or https://pytson.4qt.de for a full list of functions and callbacks (docs are mostly not filled with content, but all functions and callbacks are at least listed with their parameters, I'm working on that).


Includes
Already got a python module you wanna use in your TeamSpeak client? No problem: place it in your plugin subdirectory and use relative imports.
Plugins installed from a repository can also give dependencies from the python package index which are installed to the include directory (which is in sys.path by default).


What is missing?

• Callbacks like ts3plugin_name, ts3plugin_author and such are not wrapped as functions, instead they must be added as class attributes of your python plugin.
• Some callbacks like ts3plugin_setFunctionPointers or ts3plugin_freeMemory, because you don't need them. All memory management is done by the plugin itsself.
• The callbacks onEditPlaybackVoiceDataEvent, onEditPostProcessVoiceDataEvent, onEditMixedPlaybackVoiceDataEvent, onEditCapturedVoiceDataEvent, onCustom3dRolloffCalculationClientEvent, onCustom3dRolloffCalculationWaveEvent, onFileTransferStatusEvent and onUserLoggingMessageEvent are not wrapped. They are called from a different thread than the other callbacks and that would require some thread safety measures.
• Threading. You can't use any python threading methods. Write a c plugin instead.

Downloads
You can get builds from here: https://github.com/pathmann/pyTSon/releases

For additional information, visit the github page: https://github.com/pathmann/pyTSon

pyTSon is released under the GPL.
If you find any bugs, please open a new issue on the github page. If you don't know, in which callback the client crashes, add a print(name) in PluginHost.callMethod and start your client from the commandline (linux) or start your client with -console (windows).