TouchPortalAPI

  1"""
  2## Python API and SDK for Touch Portal.
  3
  4Easy way to build plugins for [Touch Portal](https://touch-portal.com) using Python.
  5
  6Check the [source repository](https://github.com/KillerBOSS2019/TouchPortal-API/)
  7for latest version.
  8
  9Please also refer to the [Touch Portal API documentation](https://www.touch-portal.com/api/)
 10on the Touch Portal site. Most of the documentation for this Python interface assumes at
 11least a basic understanding of how Touch Portal plugins work.
 12
 13
 14## Features
 15
 16### TCP/IP Client
 17
 18The core of the Python API is the `TouchPortalAPI.client.Client` class. This provides a
 19basic TCP/IP sockets-based client to interact with the Touch Portal desktop application
 20as the "server." It includes essential basic methods for exchanging messages between
 21TP and the plugin (send and receive), as well as many "convenience" methods for specific
 22types of messages (as defined by the TP API).
 23
 24Messages from Touch Portal are delivered to the plugin script via event handler callbacks,
 25which can be either individual callbacks per message type, and/or a single handler for all
 26types of messages. The callbacks are executed in separate Thread(s), using a pool of up to
 27any number of concurrent threads as needed (if using more than one thread, the plugin
 28code itself is responsible for thread safety of its internal data).
 29
 30### Runtime Tools
 31
 32Also included are some utilities for possible use within plugins, found in the
 33`TouchPortalAPI.tools` module. These are mostly meant to be used during plugin execution
 34(vs. at development time like the SDK tools).
 35
 36### SDK Tools
 37
 38This project also includes some tools to facilitate plugin development, found in the
 39`TouchPortalAPI.sdk_tools` module, and available as a command-line utility.
 40Currently the main focus is on generating and validating the plugin definition JSON files
 41required for integration with TP. The primary goal being to remove the need to edit any
 42definitions manually, outside of the plugin's code itself, and reduce or remove the need
 43for repeating the same data in multiple places.
 44
 45
 46## Basic API Usage
 47
 48More complete example(s) may be found in the code repository's
 49[examples folder](https://github.com/KillerBOSS2019/TouchPortal-API/tree/main/examples).
 50
 51```python
 52import TouchPortalAPI # Import the api
 53
 54# Initiate the client (replace YourPluginID with your ID)
 55TPClient = TouchPortalAPI.Client('YourPluginID')
 56
 57# This event handler will run once when the client connects to TouchPortal
 58@TPClient.on('info')
 59def onStart(data):
 60    # `data` is a Python `dict` object created from de-serialized JSON data sent by TP.
 61    print('I am Connected!', data)
 62
 63    # Update a state value in TouchPortal
 64    TPClient.stateUpdate("(Your State ID)", "State Value")
 65
 66    # Or create a list with however many states you want and use this method to send them all
 67    updateStates = [
 68        {
 69            "id": "(Your State ID)",
 70            "value": "(The Value You wanted)"
 71        },
 72        {
 73            "id": "(Your 2nd State ID)",
 74            "value": "(The Value You wanted)"
 75        }
 76    ]
 77    TPClient.stateUpdateMany(updateStates)
 78
 79# Action handlers, called when user activates one of this plugin's actions in Touch Portal.
 80@TPClient.on('action')
 81def onActions(data):
 82    print(data)
 83
 84# This function gets called every time when someone changes something in your plugin settings
 85@TPClient.on('settings')
 86def onSettings(data):
 87    print('received data from settings!')
 88
 89# Shutdown handler, called when Touch Portal wants to stop your plugin.
 90@TPClient.on('closePlugin')
 91def onShutdown(data):
 92    print('Received shutdown message!')
 93    # Terminates the connection and returns from connect()
 94    TPClient.disconnect()
 95
 96# Connect to Touch Portal and block (wait) until disconnected
 97TPClient.connect()
 98```
 99
100"""
101__copyright__ = """
102    This file is part of the TouchPortal-API project.
103    Copyright (C) 2021 DamienS
104
105    This program is free software: you can redistribute it and/or modify
106    it under the terms of the GNU General Public License as published by
107    the Free Software Foundation, either version 3 of the License, or
108    (at your option) any later version.
109
110    This program is distributed in the hope that it will be useful,
111    but WITHOUT ANY WARRANTY; without even the implied warranty of
112    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
113    GNU General Public License for more details.
114
115    You should have received a copy of the GNU General Public License
116    along with this program.  If not, see <https://www.gnu.org/licenses/>.
117"""
118
119__version__ = "1.7.8"  # this is read from setup.py and possibly other places
120
121# maintain backwards compatability
122from . client import Client, TYPES
123from . tools import Tools