Add Tuples¶
In this document, define tuples in Python and TypeScript. A Tuple is a defined class in TypeScript (javascript) or Python.
These are not to be confused with the tuple
python built in type.
What are it’s purposes:
- We can work with first class objects
t1.string1
, VS dicts of attributest1["string1"]
. - We can add additional methods to the Tuple classes that
would not otherwise be available, EG
t1.formattedStringInt()
- Defining Tuples simplifies sending data between services via the vortex, If a Tuple object is sent on one end, it will be a Tuple object when it’s deserailised on the other end.
Important
It’s important to import all the tuples when the plugin is loaded on each Peek python service (worker, client, server and agent).
The plugin loading code will throw errors if one of our Tuples is imported first by another plugin and not by us.
Objective¶
In this procedure we’ll do the following:
- Create a Tuple in Python and register it.
- Create a Tuple in TypeScript and register it.
- Create a StringIntTuple in TypeScript and register it.
Tuples File Structure¶
Add Package _private.tuples
¶
The _private.tuples
python package will contain the private python Tuples.
Create the peek_plugin_tutorial/_private/tuples
package, with
the commands
mkdir peek_plugin_tutorial/_private/tuples
touch peek_plugin_tutorial/_private/tuples/__init__.py
Add File TutorialTuple.py
¶
The TutorialTuple.py
defines a simple class that we use to work with data.
This is serialisable by the Vortex.
Create the file
peek_plugin_tutorial/_private/tuples/TutorialTuple.py
and populate it with the following contents.
from vortex.Tuple import Tuple, addTupleType, TupleField
from peek_plugin_tutorial._private.PluginNames import tutorialTuplePrefix
@addTupleType
class TutorialTuple(Tuple):
""" Tutorial Tuple
This tuple is a create example of defining classes to work with our data.
"""
__tupleType__ = tutorialTuplePrefix + 'TutorialTuple'
#: Description of date1
dict1 = TupleField(defaultValue=dict)
#: Description of date1
array1 = TupleField(defaultValue=list)
#: Description of date1
date1 = TupleField()
Edit File _private/tuples/__init__.py
¶
In this step, we add a setup method on the tuples package, this setup method then loads all the handlers needed for the backend.
Edit file peek_plugin_tutorial/_private/tuples/__init__.py
Add the following:
from txhttputil.util.ModuleUtil import filterModules
def loadPrivateTuples():
""" Load Private Tuples
In this method, we load the private tuples.
This registers them so the Vortex can reconstructed them from
serialised data.
"""
for mod in filterModules(__name__, __file__):
__import__(mod, locals(), globals())
Add Package tuples
¶
The tuples
python package will contain the public python Tuples.
The tuples which our plugin wants to share with other plugins.
We won’t define any public tuples here, but we’ll set it up.
See more at Add Plugin Python API.
Create the peek_plugin_tutorial/tuples
package, with
the commands
mkdir peek_plugin_tutorial/tuples
touch peek_plugin_tutorial/tuples/__init__.py
Edit File tuples/__init__.py
¶
In this step, we add a setup method on the tuples package, this setup method then loads all the handlers needed for the backend.
Edit file peek_plugin_tutorial/tuples/__init__.py
Add the following:
from txhttputil.util.ModuleUtil import filterModules
def loadPublicTuples():
""" Load Public Tuples
In this method, we load the public tuples.
This registers them so the Vortex can reconstructed them from
serialised data.
"""
for mod in filterModules(__name__, __file__):
__import__(mod, locals(), globals())
Edit File ServerEntryHook.py
¶
Now, we need to load all our Tuples when the plugin is loaded, for every service.
To do this, we call the methods we’ve added to the tuple
packages above.
Edit file peek_plugin_tutorial/_private/server/ServerEntryHook.py
:
Add this import up the top of the file
from peek_plugin_tutorial._private.tuples import loadPrivateTuples from peek_plugin_tutorial.tuples import loadPublicTuples
Add this line after the docstring in the
load()
methodloadPrivateTuples() loadPublicTuples()
The method should now look similar to this
def load(self):
...
loadStorageTuples() # This line was added in the "Add Storage" guide
loadPrivateTuples()
loadPublicTuples()
logger.debug("Loaded")
Note
If you see a message like this in the log:
Tuple type |%s| not registered within this program.
The above steps haven’t been completed properly and there is a problem with the
tuple loading in the peek services.
Edit File ClientEntryHook.py
¶
This step applies if you’re plugin is using the Client service.
Note
This service was add earlier in this tutorial, see Add Client Service
Edit file peek_plugin_tutorial/_private/client/ClientEntryHook.py
file,
apply the same edits from step
Edit File ServerEntryHook.py.
Edit File AgentEntryHook.py
¶
This step applies if you’re plugin is using the Agent service.
Note
This service was add earlier in this tutorial, see Add Agent Service
Edit file peek_plugin_tutorial/_private/agent/AgentEntryHook.py
file,
apply the same edits from step
Edit File ServerEntryHook.py.
Edit File WorkerEntryHook.py
¶
This step applies if you’re plugin is using the Worker service.
Note
This service is added in this tutorial, see Add Worker Service
Edit file peek_plugin_tutorial/_private/worker/WorkerEntryHook.py
file,
apply the same edits from step
Edit File ServerEntryHook.py.
Test Python Services¶
At this point all the python services should run, you won’t see any differences but it’s a good idea to run them all and check there are no issues.
Tuples Frontends and TypeScript¶
We now move onto the frontends, and TypeScript.
Add Directory plugin-module/_private/tuples
¶
The plugin-module/_private/tuples
directory will contain our example tuple,
written in TypeScript.
Our exampled tuple will be importable with:
import {TutorialTuple} from "@peek/peek_plugin_tutorial";
Create directory peek_plugin_tutorial/plugin-module/_private/tuples
,
with command
mkdir -p peek_plugin_tutorial/plugin-module/_private/tuples
Add File TutorialTuple.ts
¶
The TutorialTuple.ts
file defines a TypeScript class for our
TutorialTuple
Tuple.
Create file
peek_plugin_tutorial/plugin-module/_private/tuples/TutorialTuple.ts
,
with contents
import {addTupleType, Tuple} from "@synerty/vortexjs";
import {tutorialTuplePrefix} from "../PluginNames";
@addTupleType
export class TutorialTuple extends Tuple {
public static readonly tupleName = tutorialTuplePrefix + "TutorialTuple";
// Description of date1
dict1 : {};
// Description of array1
array1 : any[];
// Description of date1
date1 : Date;
constructor() {
super(TutorialTuple.tupleName)
}
}
Add File StringIntTuple.ts
¶
The StringIntTuple.ts
file defines the TypeScript Tuple for the
hybrid Tuple/SQL Declarative that represents StringIntTuple
.
Create file
peek_plugin_tutorial/plugin-module/_private/tuples/StringIntTuple.ts
,
with contents
import {addTupleType, Tuple} from "@synerty/vortexjs";
import {tutorialTuplePrefix} from "../PluginNames";
@addTupleType
export class StringIntTuple extends Tuple {
public static readonly tupleName = tutorialTuplePrefix + "StringIntTuple";
// Description of date1
id : number;
// Description of string1
string1 : string;
// Description of int1
int1 : number;
constructor() {
super(StringIntTuple.tupleName)
}
}
Add File SettingPropertyTuple.ts
¶
The SettingPropertyTuple.ts
file defines the TypeScript Tuple for the
hybrid Tuple/SQL Declarative that represents SettingPropertyTuple
.
The SettingProperty
storage table is the in the storage/Settings.py
file,
It’s the table that stores the key/value pairs.
Create file
peek_plugin_tutorial/plugin-module/_private/tuples/SettingPropertyTuple.ts
,
with contents
import {addTupleType, Tuple} from "@synerty/vortexjs";
import {tutorialTuplePrefix} from "../PluginNames";
@addTupleType
export class SettingPropertyTuple extends Tuple {
// The tuple name here should end in "Tuple" as well, but it doesn't, as it's a table
public static readonly tupleName = tutorialTuplePrefix + "SettingProperty";
id: number;
settingId: number;
key: string;
type: string;
int_value: number;
char_value: string;
boolean_value: boolean;
constructor() {
super(SettingPropertyTuple.tupleName)
}
}
Edit File _private/index.ts
¶
The _private/index.ts
file will re-export the Tuple in a more standard way.
Developers won’t need to know the exact path of the file.
Edit file peek_plugin_tutorial/plugin-module/_private/index.ts
,
Append the line:
export {TutorialTuple} from "./tuples/TutorialTuple";
export {StringIntTuple} from "./tuples/StringIntTuple";
export {SettingPropertyTuple} from "./tuples/SettingPropertyTuple";
This document is complete.