# Touch Portal API and SDK for Python
Easy way to build plugins for [Touch Portal](https://touch-portal.com) using Python.
## Installation
The latest release can be found on [PyPi](https://pypi.org/project/TouchPortal-API/). Simply run:
`pip install TouchPortal-API`
Alternatively, download/clone the source code from this repository and either:
- `pip install <path_to_source>`
- `python <path_to_source>/setup.py install`
- or place the `/TouchPortalAPI` folder and its contents from here into your plugin project's folder.
### Requires
- Python v3.8 or higher.
- Additional Python modules `pyee` and `requests` (dependencies are automatically installed during setup, if necessary).
- This Python API supports Touch Portal API version 3.0, as used in Touch Portal V2.3+.
- Almost all the features from TP API (SDK 6.0 TP V 3.0.11) are fully implemented and tested with real plugins.
## Documentation
The API and SDK are documented in the code using common Python conventions.
Generated documentation is published at https://KillerBOSS2019.github.io/TouchPortal-API/
## Examples
A working plugin example is included in our repository which demonstrates usage of the API and SDK.
Check the [examples folder](https://github.com/KillerBOSS2019/TouchPortal-API/tree/main/examples).
### Basic Usage Example
Make a folder in `%appdata%/TouchPortal/plugins/` or for Mac it would be in `Document/TouchPortal/plugins` called `ExamplePlugin`
and make a file there called `entry.tp` and paste this JSON data into that file:
```json
{
"sdk": 3,
"version": 100,
"name": "Example Plugin",
"id": "ExamplePlugin",
"categories": [
{
"id": "Main",
"name": "Example Plugin",
"actions": [
{
"id": "ExampleAction",
"name": "This is an Example Action",
"prefix": "plugin",
"type": "communicate",
"tryInline": true,
"format": "Print({$ExampleTextData$})",
"data": [
{
"id": "ExampleTextData",
"type": "text",
"label": "text",
"default": "Hello World"
}
]
}
],
"states": [
{
"id": "ExampleState",
"type": "text",
"desc": "Example State",
"default": "None"
}
]
}
]
}
```
Restart Touch Portal and you should see your plugin.
Now create a new file named `plugin.py` with the following
Python script. Note that the plugin, action, and state IDs
used in the script correspond to the ones specified in the
`entry.tp` JSON.
```python
import TouchPortalAPI as TP
# Setup callbacks and connection
TPClient = TP.Client("ExamplePlugin")
# This event handler will run once when the client connects to Touch Portal
@TPClient.on(TP.TYPES.onConnect) # Or replace TYPES.onConnect with 'info'
def onStart(data):
print("Connected!", data)
# Update a state value in TouchPortal
TPClient.stateUpdate("ExampleState", "Connected!")
# Action handlers, called when user activates one of this plugin's actions in Touch Portal.
@TPClient.on(TP.TYPES.onAction) # Or 'action'
def onAction(data):
print(data)
# do something based on the action ID and the data value
if data['actionId'] == "ExampleAction":
# get the value from the action data (a string the user specified)
action_value = getActionDataValue(data.get('data'), 'ExampleTextData')
print(action_value)
# We can also update our ExampleStates with the Action Value
TPClient.stateUpdate("ExampleStates", action_value)
# Shutdown handler, called when Touch Portal wants to stop your plugin.
@TPClient.on(TP.TYPES.onShutDown) # or 'closePlugin'
def onShutdown(data):
print("Got Shutdown Message! Shutting Down the Plugin!")
# Terminates the connection and returns from connect()
TPClient.disconnect()
# After callback setup like we did then we can connect.
# Note that `connect()` blocks further execution until
# `disconnect()` is called in an event handler, or an
# internal error occurs.
TPClient.connect()
```
You should now be able to run this script from a command line (terminal)
and it will interact with Touch Portal. To try it out, create a new button
on a TP page which uses this plugin's "ExampleAction" action.
## Change Log
```
1.7.10 (8/12/2023)
-------------------
- Fixed typo `ADDITIONAL_TPPSDK_ARGS` changed to `ADDITIONAL_TPPSDK_ARGS`
- Fixed tppdoc error when importing py file
- tppbuild optional args is not required to be included in build file.
- Removed some unused imports
- Added "image/webp" format to convertImage_to_base64()
- TpToPy.py action data and state key starts at 1 instead of 0
1.7.9 (8/28/2022)
-------------------
- Typo `ADDITINAL_TPPSDK_ARGS` changed to `ADDITIONAL_TPPSDK_ARGS`
1.7.8 (8/27/2022)
-------------------
- Added ADDITIONAL_TPPSDK_ARGS for additional tppsdk args
- Fixed in tppbuild it will add empty folder at root of the zip
1.7.7 (7/8/2022)
-------------------
- Updated example in examples folder
1.7.6 (7/8/2022)
-------------------
- Merged [#24](https://github.com/KillerBOSS2019/TouchPortal-API/pull/24)
1.7.5 (7/2/2022)
-------------------
- Fixed typo where It can't generate states
- when generating doc `(click to expand)` is now smaller
1.7.4 (6/26/2022)
-------------------
- Fixed doc gen and Python struct gen `format` and `readOnly` is not required key. so It will ignore this.
1.7.3 (6/26/2022)
-------------------
(All this fixes is for doc generator)
- in ToC shows each category
- changed from Sliders to Connectors
- Made it so if theres more than one category for action/state/event/connector it will not show first detail open (Only if theres only 1)
- Instead of showing category Id now it will show category name instead.
1.7.2 (6/25/2022)
-------------------
- Improved efficiency of generating Python struct
- Fixed Tools.convertImage_to_base64() (not all web image containing `content-type` header)
- and many more fixes from first review [pull #24](https://github.com/KillerBOSS2019/TouchPortal-API/pull/24)
1.7.1 (6/24/2022)
-------------------
- Introduced tppdoc
- Introduced convert entry.tp to Python struct
1.7 (6/4/2022)
-------------------
- Updated pdoc
- Added logging
- Added tppBuild
1.6.3 (5/27/2022)
-------------------
- Added shortId
- sdk_spec updated to support parentGroup and new version of SDK
1.6.2 (1/14/2022)
-------------------
- removed extra _ from connectorUpdate
1.6.1 (1/10/2022)
-------------------
- Fixed connectorUpdate method
- connectorValue needs to be a string
- connectorId provided prefix eg "pc_yourpluginid_"
1.6 (8/26/2021)
-------------------
- Notification (https://www.touch-portal.com/api/index.php?section=notifications)
- Added notificationOptionClicked events to class TYPES
- Added showNotification() method
- Connector can be used as silder (https://www.touch-portal.com/api/index.php?section=connectors)
- Added connectorChange events to class TYPES
- Added connectorUpdate method
- Client and Tools classes can now be imported separately as submodules.
- Added and updated lots of API documentation in code using Python "docstrings."
- Reference docs now published at https://KillerBOSS2019.github.io/TouchPortal-API/
1.5 (7/28/2021)
-------------------
- Added tppsdk (Allows you to create entry.tp within your code.)
1.4 (7/12/2021)
-------------------
- Removed Socket Object from callback (v1.3 or older required to remove `client` from callback.)
- Added updateStatesOnBroadcast (automatically send all states on Broadcast message.)
1.3 (6/12/2021)
-------------------
Pull requests from [#5](https://github.com/KillerBOSS2019/TouchPortal-API/pull/5) and [#6](https://github.com/KillerBOSS2019/TouchPortal-API/pull/6)
- Minor cleanups
- Refactor Client to use selectors and non-blocking sockets.
- Sync __init__.py with PyPi version.
- Optimize validations and key safety
- Added createStateMany()
- Added removeStateMany()
1.2 (4/12/2021)
-------------------
- Added isActionBeingHeld(actionId) returns True or False
1.1.1 (3/24/2021)
-------------------
Fixes
Fix: fixed the readme for typo's
Fix: keywords
Fix: updateStates now only updates when value changed
Fix: createState now update the state if it already exists
Fix: updateSetting now only updates when value has changed
1.1.0 (3/23/2021)
-------------------
- Fixed some typos
1.0 (3/23/2021)
-------------------
# Feautres
- Easy to use
- createState
- removeState
- choice Update
- choice Update Specific
- setting Update
- state Update
- State Update Many
- Converting image to base64
- Update check
```
## Touch Portal API documentation
https://www.touch-portal.com/api
## Bugs and Suggestions
Please report any problems using GitHub [Issues](https://github.com/KillerBOSS2019/TouchPortal-API/issues)
and feel free to use the [Discussion](https://github.com/KillerBOSS2019/TouchPortal-API/discussions)
feature as well.
## Contribute
Feel free to suggest a pull request for new features, improvements, or documentation.
If you are not sure how to proceed with something, please start an Issue or Discussion
at the GitHub repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/KillerBOSS2019/TouchPortal-API/",
"name": "touchportal-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "TouchPortal,Touch Portal,API,Plugin,SDK",
"author": "Damien",
"author_email": "DamienWeiFen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/de/b1/488f20edfde00df1cc312ad5ebc105765256b75aa817847502243a26c6db/touchportal_api-1.7.10.tar.gz",
"platform": null,
"description": "# Touch Portal API and SDK for Python\nEasy way to build plugins for [Touch Portal](https://touch-portal.com) using Python.\n\n## Installation\nThe latest release can be found on [PyPi](https://pypi.org/project/TouchPortal-API/). Simply run:\n\n`pip install TouchPortal-API`\n\nAlternatively, download/clone the source code from this repository and either:\n- `pip install <path_to_source>`\n- `python <path_to_source>/setup.py install`\n- or place the `/TouchPortalAPI` folder and its contents from here into your plugin project's folder.\n\n### Requires\n- Python v3.8 or higher.\n- Additional Python modules `pyee` and `requests` (dependencies are automatically installed during setup, if necessary).\n- This Python API supports Touch Portal API version 3.0, as used in Touch Portal V2.3+.\n- Almost all the features from TP API (SDK 6.0 TP V 3.0.11) are fully implemented and tested with real plugins.\n\n\n## Documentation\n\nThe API and SDK are documented in the code using common Python conventions.\n\nGenerated documentation is published at https://KillerBOSS2019.github.io/TouchPortal-API/\n\n\n## Examples\n\nA working plugin example is included in our repository which demonstrates usage of the API and SDK.\nCheck the [examples folder](https://github.com/KillerBOSS2019/TouchPortal-API/tree/main/examples).\n\n### Basic Usage Example\n\nMake a folder in `%appdata%/TouchPortal/plugins/` or for Mac it would be in `Document/TouchPortal/plugins` called `ExamplePlugin`\nand make a file there called `entry.tp` and paste this JSON data into that file:\n\n```json\n{\n \"sdk\": 3,\n \"version\": 100,\n \"name\": \"Example Plugin\",\n \"id\": \"ExamplePlugin\",\n \"categories\": [\n {\n \"id\": \"Main\",\n \"name\": \"Example Plugin\",\n \"actions\": [\n {\n \"id\": \"ExampleAction\",\n \"name\": \"This is an Example Action\",\n \"prefix\": \"plugin\",\n \"type\": \"communicate\",\n \"tryInline\": true,\n \"format\": \"Print({$ExampleTextData$})\",\n \"data\": [\n {\n \"id\": \"ExampleTextData\",\n \"type\": \"text\",\n \"label\": \"text\",\n \"default\": \"Hello World\"\n }\n ]\n }\n ],\n \"states\": [\n {\n \"id\": \"ExampleState\",\n \"type\": \"text\",\n \"desc\": \"Example State\",\n \"default\": \"None\"\n }\n ]\n }\n ]\n}\n```\n\nRestart Touch Portal and you should see your plugin.\nNow create a new file named `plugin.py` with the following\nPython script. Note that the plugin, action, and state IDs\nused in the script correspond to the ones specified in the\n`entry.tp` JSON.\n\n```python\nimport TouchPortalAPI as TP\n\n# Setup callbacks and connection\nTPClient = TP.Client(\"ExamplePlugin\")\n\n# This event handler will run once when the client connects to Touch Portal\n@TPClient.on(TP.TYPES.onConnect) # Or replace TYPES.onConnect with 'info'\ndef onStart(data):\n print(\"Connected!\", data)\n # Update a state value in TouchPortal\n TPClient.stateUpdate(\"ExampleState\", \"Connected!\")\n\n# Action handlers, called when user activates one of this plugin's actions in Touch Portal.\n@TPClient.on(TP.TYPES.onAction) # Or 'action'\ndef onAction(data):\n print(data)\n # do something based on the action ID and the data value\n if data['actionId'] == \"ExampleAction\":\n # get the value from the action data (a string the user specified)\n action_value = getActionDataValue(data.get('data'), 'ExampleTextData')\n print(action_value)\n # We can also update our ExampleStates with the Action Value\n TPClient.stateUpdate(\"ExampleStates\", action_value)\n\n# Shutdown handler, called when Touch Portal wants to stop your plugin.\n@TPClient.on(TP.TYPES.onShutDown) # or 'closePlugin'\ndef onShutdown(data):\n print(\"Got Shutdown Message! Shutting Down the Plugin!\")\n # Terminates the connection and returns from connect()\n TPClient.disconnect()\n\n# After callback setup like we did then we can connect.\n# Note that `connect()` blocks further execution until\n# `disconnect()` is called in an event handler, or an\n# internal error occurs.\nTPClient.connect()\n```\n\nYou should now be able to run this script from a command line (terminal)\nand it will interact with Touch Portal. To try it out, create a new button\non a TP page which uses this plugin's \"ExampleAction\" action.\n\n\n## Change Log\n\n```\n1.7.10 (8/12/2023)\n-------------------\n- Fixed typo `ADDITIONAL_TPPSDK_ARGS` changed to `ADDITIONAL_TPPSDK_ARGS`\n- Fixed tppdoc error when importing py file\n- tppbuild optional args is not required to be included in build file.\n- Removed some unused imports\n- Added \"image/webp\" format to convertImage_to_base64()\n- TpToPy.py action data and state key starts at 1 instead of 0\n\n\n1.7.9 (8/28/2022)\n-------------------\n- Typo `ADDITINAL_TPPSDK_ARGS` changed to `ADDITIONAL_TPPSDK_ARGS`\n\n1.7.8 (8/27/2022)\n-------------------\n- Added ADDITIONAL_TPPSDK_ARGS for additional tppsdk args\n- Fixed in tppbuild it will add empty folder at root of the zip\n\n1.7.7 (7/8/2022)\n-------------------\n- Updated example in examples folder\n\n1.7.6 (7/8/2022)\n-------------------\n- Merged [#24](https://github.com/KillerBOSS2019/TouchPortal-API/pull/24)\n\n1.7.5 (7/2/2022)\n-------------------\n- Fixed typo where It can't generate states\n- when generating doc `(click to expand)` is now smaller\n\n1.7.4 (6/26/2022)\n-------------------\n- Fixed doc gen and Python struct gen `format` and `readOnly` is not required key. so It will ignore this.\n\n1.7.3 (6/26/2022)\n-------------------\n(All this fixes is for doc generator)\n- in ToC shows each category\n- changed from Sliders to Connectors\n- Made it so if theres more than one category for action/state/event/connector it will not show first detail open (Only if theres only 1)\n- Instead of showing category Id now it will show category name instead.\n\n1.7.2 (6/25/2022)\n-------------------\n- Improved efficiency of generating Python struct\n- Fixed Tools.convertImage_to_base64() (not all web image containing `content-type` header)\n- and many more fixes from first review [pull #24](https://github.com/KillerBOSS2019/TouchPortal-API/pull/24)\n\n1.7.1 (6/24/2022)\n-------------------\n- Introduced tppdoc\n- Introduced convert entry.tp to Python struct\n\n1.7 (6/4/2022)\n-------------------\n- Updated pdoc\n- Added logging \n- Added tppBuild\n\n1.6.3 (5/27/2022)\n-------------------\n- Added shortId\n- sdk_spec updated to support parentGroup and new version of SDK\n\n1.6.2 (1/14/2022)\n-------------------\n- removed extra _ from connectorUpdate\n\n1.6.1 (1/10/2022)\n-------------------\n- Fixed connectorUpdate method\n - connectorValue needs to be a string\n - connectorId provided prefix eg \"pc_yourpluginid_\"\n\n1.6 (8/26/2021)\n-------------------\n- Notification (https://www.touch-portal.com/api/index.php?section=notifications)\n - Added notificationOptionClicked events to class TYPES\n - Added showNotification() method\n- Connector can be used as silder (https://www.touch-portal.com/api/index.php?section=connectors)\n - Added connectorChange events to class TYPES\n - Added connectorUpdate method\n- Client and Tools classes can now be imported separately as submodules.\n- Added and updated lots of API documentation in code using Python \"docstrings.\"\n - Reference docs now published at https://KillerBOSS2019.github.io/TouchPortal-API/\n\n\n1.5 (7/28/2021)\n-------------------\n- Added tppsdk (Allows you to create entry.tp within your code.)\n\n1.4 (7/12/2021)\n-------------------\n- Removed Socket Object from callback (v1.3 or older required to remove `client` from callback.)\n- Added updateStatesOnBroadcast (automatically send all states on Broadcast message.)\n\n1.3 (6/12/2021)\n-------------------\nPull requests from [#5](https://github.com/KillerBOSS2019/TouchPortal-API/pull/5) and [#6](https://github.com/KillerBOSS2019/TouchPortal-API/pull/6)\n- Minor cleanups\n- Refactor Client to use selectors and non-blocking sockets.\n- Sync __init__.py with PyPi version.\n- Optimize validations and key safety\n- Added createStateMany()\n- Added removeStateMany()\n\n1.2 (4/12/2021)\n-------------------\n- Added isActionBeingHeld(actionId) returns True or False\n\n1.1.1 (3/24/2021)\n-------------------\nFixes\n\nFix: fixed the readme for typo's\nFix: keywords\nFix: updateStates now only updates when value changed\nFix: createState now update the state if it already exists\nFix: updateSetting now only updates when value has changed\n\n1.1.0 (3/23/2021)\n-------------------\n- Fixed some typos\n\n1.0 (3/23/2021)\n-------------------\n# Feautres\n- Easy to use\n- createState\n- removeState\n- choice Update\n- choice Update Specific\n- setting Update\n- state Update\n- State Update Many\n- Converting image to base64\n- Update check\n```\n\n## Touch Portal API documentation\nhttps://www.touch-portal.com/api\n\n## Bugs and Suggestions\nPlease report any problems using GitHub [Issues](https://github.com/KillerBOSS2019/TouchPortal-API/issues)\nand feel free to use the [Discussion](https://github.com/KillerBOSS2019/TouchPortal-API/discussions)\nfeature as well.\n\n## Contribute\nFeel free to suggest a pull request for new features, improvements, or documentation.\nIf you are not sure how to proceed with something, please start an Issue or Discussion\nat the GitHub repository.\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "Touch Portal API and SDK for Python",
"version": "1.7.10",
"project_urls": {
"Documentation": "https://KillerBOSS2019.github.io/TouchPortal-API/",
"Homepage": "https://github.com/KillerBOSS2019/TouchPortal-API/",
"Issues": "https://github.com/KillerBOSS2019/TouchPortal-API/issues",
"Source": "https://github.com/KillerBOSS2019/TouchPortal-API/"
},
"split_keywords": [
"touchportal",
"touch portal",
"api",
"plugin",
"sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50f5dc903300b8184f77045c928d2f5aeaadd07f1e7f0e0c5a7bbe760f8645af",
"md5": "cbaadc42539131bd325d1dc9b23b96a1",
"sha256": "da0398ef87183d4e406cfd216b2152050d7be1bff6127f05c420e4caa425b292"
},
"downloads": -1,
"filename": "touchportal_api-1.7.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cbaadc42539131bd325d1dc9b23b96a1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 58275,
"upload_time": "2023-08-12T20:35:39",
"upload_time_iso_8601": "2023-08-12T20:35:39.979090Z",
"url": "https://files.pythonhosted.org/packages/50/f5/dc903300b8184f77045c928d2f5aeaadd07f1e7f0e0c5a7bbe760f8645af/touchportal_api-1.7.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "deb1488f20edfde00df1cc312ad5ebc105765256b75aa817847502243a26c6db",
"md5": "dde643a06f7368f12b4e7be8737defd0",
"sha256": "85c76423fb2d1ac502ffd8a4f397ce0cefefe19e65b1fc2a61b00103b2b14093"
},
"downloads": -1,
"filename": "touchportal_api-1.7.10.tar.gz",
"has_sig": false,
"md5_digest": "dde643a06f7368f12b4e7be8737defd0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 53824,
"upload_time": "2023-08-12T20:35:41",
"upload_time_iso_8601": "2023-08-12T20:35:41.274604Z",
"url": "https://files.pythonhosted.org/packages/de/b1/488f20edfde00df1cc312ad5ebc105765256b75aa817847502243a26c6db/touchportal_api-1.7.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-12 20:35:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KillerBOSS2019",
"github_project": "TouchPortal-API",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "touchportal-api"
}
JSON
