Developers documentation
Version: v0.0.7

The model must be export to a database file to create a study save file. This file use SQLite3³ format and the extention .pamhyr. So, each model componante must be register into this study file. To create, update, set and get information into SQLite database we use SQL command. The database use version number and some modification could be perform to update database. For each model componante, correspond one or more SQL table to store information. To normalize the interaction with database we made two classes, SQLModel and SQLSubModel. The Study class use SQLModel because is the top of the model hierachy. The rest of model class inherits to SQLSubModel.

A class who inherits SQLSubModel, must implement some methods:

• _sql_create: Class method to create the database scheme
• _sql_update: Class method to update the database scheme if necessary
• _sql_load: Class method to load data from DB
• _sql_save: Method to save current object into DB

Class method take in arguments: The class (cls), a function to execute SQL command into the database (execute). In addition, the update method take the previous version of database, load method take an optional arguments data if additional infomation ar needed, and who can contains whatever you want. The method save take in arguments the current object (self), a function to execute SQL command into the database (execute), and optional data (data).

The class who inherits SQLSubModel can also define an class attribute _sub_classes to set a formal class dependencies into database. This attribute is use at database creation to create all table, and at update to update all the database table. Let see examples of SQLSubModel usage for two classes Foo and Bar with Foo contains list of Bar (Listing 1 and 2).

from Model.Tools.PamhyrDB import SQLSubModel

class Bar(SQLSubModel):
    _id_cnt = 0
    def __init__(self, id = -1, x = 0, y = 0):
        self._x = x
        self._y = y
        if id == -1:
            self.id = Bar._id_cnt + 1
        else:
            self.id = id
        Bar._id_cnt = max(id, Bar._id_cnt+1)

    @classmethod
    def _sql_create(cls, execute):
        execute("""
          CREATE TABLE bar (
            id INTEGER NOT NULL PRIMARY KEY,
            x INTEGER NOT NULL,
            y INTEGER NOT NULL,
            foo_id INTEGER NOT NULL,
            FOREIGN KEY(foo_id) REFERENCES foo(id),
          )""")
        return True

    @classmethod
    def _sql_update(cls, execute, version):
        # If version is lesser than 0.0.2, add column to bar table
        major, minor, release = version.strip().split(".")
        if major == minor == "0":
            if int(release) < 2:
                execute("ALTER TABLE bar ADD COLUMN y INTEGER")
        return True

    @classmethod
    def _sql_load(cls, execute, data = None):
        new = []
        table = execute(
            f"SELECT id, x, y FROM bar WHERE foo_id = {data['id']}"
        )
        for row in table:
            bar = cls(
                id = row[0], x = row[1], y = row[2],
            )
            new.append(bar)
        return new

    def _sql_save(self, execute, data = None):
        execute("INSERT INTO bar (id,x,y,foo_id) VALUES " +
                f"({self.id}, {self._x}, {self._y}, {data['id']})")

class Foo(SQLSubModel):
    _id_cnt = 0
    _sub_classes = [Bar]

    def __init__(self, id = -1, name = ""):
        self._name = name
        self._bar = []
        # ...

    @classmethod
    def _sql_create(cls, execute):
        execute("""
          CREATE TABLE foo (
            id INTEGER NOT NULL PRIMARY KEY,
            name TEXT NOT NULL,
          )
        """)
        return cls._create_submodel(execute)

    @classmethod
    def _sql_update(cls, excute, version):
        return cls._update_submodel(execute, version)

    @classmethod
    def _sql_load(cls, execute, data = None):
        new = []
        table = execute(
            "SELECT id, name FROM foo"
        )
        for row in table:
            foo = cls(
                id = row[0],
                name = row[1],
            )
            data = {
                "id": row[0],     # Current Foo ID
            }
            foo._bar = Bar._sql_load(execute, data=data)
            new.append(foo)
        return new

    def _sql_save(self, execute, data = None):
        execute(f"DELETE FROM foo WHERE id = {self.id}")
        execute(f"DELETE FROM bar WHERE foo_id = {self.id}")
        # Save new data
        execute(f"INSERT INTO bar (id,name) VALUES ({self.id}, {self._name})")
        data = {"id": self.id}
        for bar in self._bar:
            bar._sql_save(execute, data=data)

Let see the results database scheme for Pamhyr2 at version v0.0.7 in Figure 3.

A abstract class PamhyrModelList is available and provide some of basic methods for object list in Model. This abstract class implement some classic action in View like: insert new object, delete object, sort, move object up, move object down, and so on. An variant exists for multiple list with same type of object, each sublist is called tab, because in View, this kind of list si prensented in different table PamhyrModelListWithTab.

A abstract class PamhyrModelDict is available and provide some of basic methods for object dictionary in Model. This class is like PamhyrModelList but use a dictionary instead of list.

We define as possible all Pamhyr2 windows and custom widgets with "Qt designer". This application generate UI file who describes interface organisation with table, layout, button, etc. This method is faster than hand made windows and widget creation, and saves us some purely descriptive code. The UI files are saved into src/View/ui for window, and /src/View/ui/Widgets for custom widget.

The abstract class PamhyrWindow and PamhyrDialog are used for most of Pamhyr2 window. These class allow to create an window for Pamhyr2 GUI and implemente some useful methods. The super class method difine some generic value from optional parameters, for examples:

• self._study: The study giving in constructor parameters study (typically a Model.Study class object)
• self._config: The configuration giving in constructor parameters config (typically a Config class object)
• self._trad: The traductor dictionary giving in constructor parameters trad (typically a Model.Tools.PamhyrTranslate class object)

from View.Tools.PamhyrWindow import PamhyrWindow
from View.My.Translate import MyTranslate
from View.My.Table import MyTableModel

class MyWindow(PamhyrWindow):
    _pamhyr_ui = "MyUI"
    _pamhyr_name = "My window"

    def __init__(self, study=None, config=None,
                 my_data=None,
                 parent=None):
        self._my_data = my_data

        super(MyWindow, self).__init__(
            # Window title
            title = self._pamhyr_name + " - " + study.name,
            # Window standard data
            study = study, config = config,
            trad = MyTranslate(),
            parent = parent,
            # Activate undo/redo and copy/paste shortcut
            options = ["undo", "copy"]
        )

        # Add custom data to hash window computation
        self._hash_data.append(self._my_data)

        # Setup custom window components
        self.setup_table()
        self.setup_connections()

    def setup_table(self):
        # Init table(s)...

    def setup_connections(self):
        # Init action connection(s)...

    # ...

Typically we called method setup_*, the method to initialize some window componants or connections.

An abstract class PamhyrTableModel is available to define a simple QAbstractTableModel shortly. In simple cases, there are only data and setData methode to implement, but the constructor needs more information than a classic QAbstractTableModel class.

from View.Tools.PamhyrTable import PamhyrTableModel

class MyTableModel(PamhyrTableModel):
    def data(self, index, role):
        # Retrun data at INDEX...

    @pyqtSlot()
    def setData(self, index, value, role=Qt.EditRole):
        # Set VALUE at INDEX...

# Table model creation (Window.py: setup_table)
table_headers = self._trad.get_dict("table_headers")
self._model = MyTableModel(
    table_view = table,         # The table view object
    table_headers = table_headers, # The table column headers dict
                                   # (with traduction)
    editable_headers = ["foo", "bar"], # List of editable column name
    delegates = {
        "bar": self.my_delegate, # Custom delegate for column 'bar'
    },
    data = self._my_lst,         # The data
    undo = self._undo_stack,     # The window undo command stack
)

All model modification must be done by an QUndoCommand, this command allow to undo and redo an action. This a Qt class wi can inherit to define custom undo command (see example Listing 7)

class AddNodeCommand(QUndoCommand):
    def __init__(self, graph, node):
        QUndoCommand.__init__(self)

        self._graph = graph
        self._node = node

    def undo(self):
        self._graph.remove_node(self._node.name)

    def redo(self):
        self._graph.insert_node(self._node)

All undo command must be push into a QUndoStack (see Listing 8) to perform the action and allow user undo and redo this action. In PamhyrWindow (and PamhyrDialog) the undo stack is automatically create if the option "undo" is activate at window creation, this stack is accessible at self._undo_stack.

self._undo_stack.push(
    AddNodeCommand(
        self._graph,
        node
    )
)

To define a new plot you can create a class who inherit to PamhyrPlot. The creator need at leaste five argument:

• A canvas of type MplCanvas
• A (optional) trad of type PamhyrTranslate
• A data used in draw and update to create and update the plot
• A optional toolbar of type PamhyrToolbar
• A parent window

This class must implement two method draw and update, the first method to draw the plot from scratch, the second to update the plot if data has changed.

from View.Tools.PamhyrPlot import PamhyrPlot

class MyPlot(PamhyrPlot):
    def __init__(self, canvas=None, trad=None, toolbar=None
                 data=None, parent=None):
        super(MyPlot, self).__init__(
            canvas=canvas,
            trad=trad,
            data=data,
            toolbar=toolbar,
            parent=parent
        )

      self.label_x = self._trad["x"]
      self.label_y = self._trad["y"]

      # Optional configuration
      self._isometric_axis = False

      self._auto_relim_update = True
      self._autoscale_update = True

    def draw(self):
        # Draw function code...

    def update(self):
        # Update function code...

    def clear(self):
        # Clear plot values...

    # ...

On GNU/Linux building GNU/Linux packages is easy, you just need python in version 3.8 must be installed with venv and pyinstaller packages (see Listing 9 for Debian and derived system). Finally, run the linux.sh script (see Listing 10).

sudo apt install python3.8
python3 -m pip install venv
python3 -m pip install pyinstaller

cd packages
./linux.sh

To make the Windows packages you have two choice: If you use Windows you can use the script packages/windows.bat, other else you can use the script packages/wine.sh. Each script need a specific software environment.

On windows, you needs python on version 3.8, pyinstaller and NSIS⁴ installed. On GNU/Linux you need wget, wine and winetricks installed.

The Linux ci-runner need some software and dependencies in addtion of gitlab-ci.

sudo apt install                                \
     emacs emacs-goodies-el                     \
     texlive-full                               \
     python3.8 python3.8-venv
sudo python3 -m pip install pyinstaller

The ci-runner environment for Wine need at least wine version 8, let see who to add wine official depot to your linux distribution.

sudo apt install wine-stable winetricks

In addition, the environment need windows version of:

• Python 3.8.10
• Git
• PowerShell
• Gitlab-ci
• Nsis

Now, we can install pyinstaller on this windows environment:

wine python -m pip install pyinstaller

Org uses the * character to define a new document section. To add a sub-section, you can add an additional * to the current section⁶.

* Top level headline
** Second level
*** Third level
    some text
*** Third level
    more text
* Another top level headline

Org-mode is a markup file, using markup in the text to modify the appearance of a portion of text⁷.

You can add some code blocks⁸ in the document.

Here is an example for python source code:

#+CAPTION: Get os type name in Python code
#+begin_src python
import os

print(f"Document build on system: {os.name}")
#+end_src

If you use GNUEmacs, it is also possible to run the code inside a block and export (or not) the reuslts in the document.

import os

print(f"Document build on system: {os.name}")

Document build on system: posix

If we export the file to PDF, org-mode use \LaTeX. So we can add some piece of \LaTeX into the document⁹. For exemple, we can add math formula like $E=mc^2$ (\(E=mc^2\)) or \[E=mc^2\]:

\[E=mc^2\]

But we can also add every type of \LaTeX:

# Add latex in line
#+LATEX: <my line of latex>

# Add multiple line of LaTeX
#+BEGIN_EXPORT latex
<my latex here>
#+END_EXPORT

It is also possible to add specific \LaTeX file header with #+LATEX_HEADER. In this document we use the file doc/tools/latex.org for all \LaTeX headers.

In this document, we use a few macros¹⁰ to simplify writing. They allow you to define sequences of text to be replaced, so that the macro name is replaced by its value. They are defined in the doc/tools/macro.org file. Once defined, they can be used in the document as follows: {{{<macro-name>}}}. You can also have macros with arguments, in this case: {{{<macro-name>(arg1,...)}}}. Les macros peuvent aussi utiliser du code emacs-lisp.

# Exemple of macro définition

#+MACRO: toto               tata
#+MACRO: add                \(($1 + $2)\)
#+MACRO: emacs-version      (eval (nth 2 (split-string (emacs-version))))

Macro apply:

• Marco {{{toto}}}: tata
• Marco {{{add(x,y)}}}: \((x + y)\)
• Marco {{{emacs-version}}}: 26.3

The references use the \LaTeX bibtex tools. The bib file is in /doc/tools/ref.bib and use for developers and user documentation. In document, use {{{cite(<name>)}}} to cite a paper.