TouchPortalAPI.sdk_spec

  1"""
  2Touch Portal API spec tables
  3
  4Each lookup table corresponds to a major "collection" in TP SDK,
  5which are all listed in the TP API Reference page (https://www.touch-portal.com/api/index.php?section=reference)
  6The tables can be used for generating and/or validating entry.tp files.
  7Some tables, like for Actions, may contain nested data structures (like Action Data).
  8
  9Table attributes:
 10  - `v`: minimum TP SDK version
 11  - `r`: required true/false
 12  - `t`: value type (default is `str`)
 13  - `d`: default value, if any
 14  - `c`: optional list of valid value(s) (choices)
 15  - `l`: lookup table for child data structures, if any
 16
 17TODO: List valid attribute values per SDK version?
 18"""
 19
 20__copyright__ = """
 21This file is part of the TouchPortal-API project.
 22Copyright TouchPortal-API Developers
 23Copyright (c) 2021 Maxim Paperno
 24All rights reserved.
 25
 26This program is free software: you can redistribute it and/or modify
 27it under the terms of the GNU General Public License as published by
 28the Free Software Foundation, either version 3 of the License, or
 29(at your option) any later version.
 30
 31This program is distributed in the hope that it will be useful,
 32but WITHOUT ANY WARRANTY; without even the implied warranty of
 33MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 34GNU General Public License for more details.
 35
 36You should have received a copy of the GNU General Public License
 37along with this program.  If not, see <https://www.gnu.org/licenses/>.
 38"""
 39
 40TPSDK_DEFAULT_VERSION = 6
 41""" Default Touch Portal SDK version for generating entry.tp JSON. """
 42
 43TPSDK_ATTRIBS_SETTINGS = {
 44# key name              sdk V   required    [type(s)]    [default value]    [valid value list]
 45  'name':             { 'v': 3, 'r': True,  't': str },
 46  'type':             { 'v': 3, 'r': True,  't': str,   'd': "text",        'c': ["text","number"] },
 47  'default':          { 'v': 3, 'r': False, 't': str },
 48  'maxLength':        { 'v': 3, 'r': False, 't': int },
 49  'isPassword':       { 'v': 3, 'r': False, 't': bool },
 50  'minValue':         { 'v': 3, 'r': False, 't': int },
 51  'maxValue':         { 'v': 3, 'r': False, 't': int },
 52  'readOnly':         { 'v': 3, 'r': False, 't': bool,  'd': False },
 53}
 54""" [Settings structure](https://www.touch-portal.com/api/index.php?section=settings) """
 55
 56TPSDK_ATTRIBS_STATE = {
 57# key name              sdk V   required    [type(s)]    [default value]    [valid value list]
 58  'id':               { 'v': 1, 'r': True,  't': str },
 59  'type':             { 'v': 1, 'r': True,  't': str,   'd': "text",        'c': ["text","choice"]},
 60  'desc':             { 'v': 1, 'r': True,  't': str },
 61  'default':          { 'v': 1, 'r': True,  't': str,   'd': "" },
 62  "parentGroup":      {"v": 6, "r": False, "t": str},
 63  'valueChoices':     { 'v': 1, 'r': False, 't': list },
 64}
 65""" [State structure](https://www.touch-portal.com/api/index.php?section=states) """
 66
 67TPSDK_ATTRIBS_EVENT = {
 68# key name              sdk V   required    [type(s)]    [default value]    [valid value list]
 69  'id':               { 'v': 1, 'r': True,  't': str },
 70  'name':             { 'v': 1, 'r': True,  't': str },
 71  'format':           { 'v': 1, 'r': True,  't': str },
 72  'type':             { 'v': 1, 'r': True,  't': str,   'd': "communicate", 'c': ["communicate"] },
 73  'valueChoices':     { 'v': 1, 'r': True,  't': list,  'd': [] },
 74  'valueType':        { 'v': 1, 'r': True,  't': str,   'd': "choice",      'c': ["choice"] },
 75  'valueStateId':     { 'v': 1, 'r': True,  't': str },
 76}
 77""" [Event structure](https://www.touch-portal.com/api/index.php?section=events) """
 78
 79TPSDK_ATTRIBS_ACT_DATA = {
 80# key name              sdk V   required    [type(s)]    [default value]    [valid value list]
 81  'id':               { 'v': 1, 'r': True,  't': str },
 82  'type':             { 'v': 1, 'r': True,  't': str,   'd': "text",        'c': ["text","number","switch","choice","file","folder","color"] },
 83  'label':            { 'v': 1, 'r': True,  't': str },
 84  'default':          { 'v': 1, 'r': True,  't': (str,int,float,bool), 'd': "" },
 85  'valueChoices':     { 'v': 1, 'r': False, 't': list },
 86  'extensions':       { 'v': 2, 'r': False, 't': list },
 87  'allowDecimals':    { 'v': 2, 'r': False, 't': bool },
 88  'minValue':         { 'v': 3, 'r': False, 't': int },
 89  'maxValue':         { 'v': 3, 'r': False, 't': int }
 90}
 91""" [Action Data structure](https://www.touch-portal.com/api/index.php?section=action-data) """
 92
 93TPSDK_ATTRIBS_ACTION = {
 94# key name              sdk V   required    [type(s)]    [default value]    [valid value list]   [lookup table]
 95  'id':               { 'v': 1, 'r': True,  't': str },
 96  'name':             { 'v': 1, 'r': True,  't': str },
 97  'prefix':           { 'v': 1, 'r': True,  't': str },  # dynamic default? based on category name?
 98  'type':             { 'v': 1, 'r': True,  't': str,   'd': "communicate", 'c': ["communicate","execute"] },
 99  'description':      { 'v': 1, 'r': False, 't': str },
100  'format':           { 'v': 1, 'r': False, 't': str },
101  'executionType':    { 'v': 1, 'r': False, 't': str },
102  'execution_cmd':    { 'v': 1, 'r': False, 't': str },
103  'tryInline':        { 'v': 1, 'r': False, 't': bool },
104  'hasHoldFunctionality': { 'v': 3, 'r': False, 't': bool },
105  'data':             { 'v': 1, 'r': False, 't': list, 'l': TPSDK_ATTRIBS_ACT_DATA },
106}
107""" [Dynamic Action structure](https://www.touch-portal.com/api/index.php?section=dynamic-actions) """
108
109TPSDK_ATTRIBS_CONNECTOR = {
110# key name              sdk V   required    [type(s)]    [default value]    [valid value list]   [lookup table]
111  'id':               { 'v': 4, 'r': True,  't': str },
112  'name':             { 'v': 4, 'r': True,  't': str },
113  'format':           { 'v': 4, 'r': False, 't': str },
114  'data':             { 'v': 4, 'r': False, 't': list, 'l': TPSDK_ATTRIBS_ACT_DATA },  # same data as Actions? TP API docs are still vague
115}
116""" [Connector structure](https://www.touch-portal.com/api/index.php?section=connectors) """
117
118TPSDK_ATTRIBS_CATEGORY = {
119# key name              sdk V   required    [type(s)]  [lookup table]
120  'id':               { 'v': 1, 'r': True,  't': str },  # dynamic default id based on plugin id?
121  'name':             { 'v': 1, 'r': True,  't': str },  # dynamic default based on plugin name?
122  'imagepath':        { 'v': 1, 'r': False, 't': str },
123  'actions':          { 'v': 1, 'r': False, 't': list, 'l': TPSDK_ATTRIBS_ACTION },
124  'connectors':       { 'v': 4, 'r': False, 't': list, 'l': TPSDK_ATTRIBS_CONNECTOR },
125  'states':           { 'v': 1, 'r': False, 't': list, 'l': TPSDK_ATTRIBS_STATE },
126  'events':           { 'v': 1, 'r': False, 't': list, 'l': TPSDK_ATTRIBS_EVENT },
127}
128""" [Category structure](https://www.touch-portal.com/api/index.php?section=categories) """
129
130TPSDK_ATTRIBS_ROOT = {
131# key name              sdk V   required    [type(s)]    [default value]            [valid value list]   [lookup table]
132  'sdk':              { 'v': 1, 'r': True,  't': int,   'd': TPSDK_DEFAULT_VERSION, 'c': [1,2,3,4,5,6] },
133  'version':          { 'v': 1, 'r': True,  't': int,   'd': 1 },
134  'name':             { 'v': 1, 'r': True,  't': str },
135  'id':               { 'v': 1, 'r': True,  't': str },
136  'configuration':    { 'v': 1, 'r': False, 't': dict },
137  'plugin_start_cmd': { 'v': 1, 'r': False, 't': str },
138  'plugin_start_cmd_windows': { 'v': 4, 'r': False, 't': str },
139  'plugin_start_cmd_linux':   { 'v': 4, 'r': False, 't': str },
140  'plugin_start_cmd_mac':     { 'v': 4, 'r': False, 't': str },
141  'categories':       { 'v': 1, 'r': True,  't': list,  'd': [], 'l': TPSDK_ATTRIBS_CATEGORY },
142  'settings':         { 'v': 3, 'r': False, 't': list,  'd': [], 'l': TPSDK_ATTRIBS_SETTINGS },
143}
144""" [Plugin structure](https://www.touch-portal.com/api/index.php?section=structure) """