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:

  1. We can work with first class objects t1.string1, VS dicts of attributes t1["string1"].
  2. We can add additional methods to the Tuple classes that would not otherwise be available, EG t1.formattedStringInt()
  3. 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:

  1. Create a Tuple in Python and register it.
  2. Create a Tuple in TypeScript and register it.
  3. 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 :

  1. Add this import up the top of the file

    from peek_plugin_tutorial._private.tuples import loadPrivateTuples
    from peek_plugin_tutorial.tuples import loadPublicTuples
    
  2. Add this line after the docstring in the load() method

    loadPrivateTuples()
    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.