DESCRIPTION.

Etablit un lien entre un mot clé et une classe, pour effectuer des traitements individuels et collectifs de toutes les lignes.

SYNTAXE.

BDD_Base.create_window_function ( lien , attributs , classe )

BDD_Base ⇨ objet connexion avec une base de données [ OBLIGATOIRE ]

.create_window_function ( ) ⇨ appel de la méthode [ OBLIGATOIRE ]

lien ⇨ mot de liaison [ OBLIGATOIRE ]

attributs ⇨ nombre de paramètres attendus [ OBLIGATOIRE ]

classe ⇨ classe à instancier [ OBLIGATOIRE ]

REMARQUES. 

lien doit être un str ( ) quelconque.

attributs doit être un int ( ) indiquant combien de paramètres doivent être transmis à fonction. Si la quantité d'attributs est indéterminé ou s'il est variable, attributs prendra la valeur -1.

classe doit être le nom d'une classe personnalisée existante, créée et définie au préalable avec l'instruction class. La paire de parenthèse, après le nom de la fonction, de doivent pas être présentes.

La classe personnalisée appelée par la méthode objet.create_aggregate ( ) doit obligatoirement avoir la forme suivante :

class CLS_Nom :

def __init__ ( self ) :

pass

def step ( self , Qa , Qb , ... ,  Qn ) :

pass

def value ( self ) :

pass

def inverse ( self , Qa , Qb , ... ,  Qn ) :

pass

def finalize ( self ) :

return valeur

CLS_Nom est un str ( ) choisi librement désignant classe dans l'appel de la méthode objet.create_aggregate ( ).

def __init__ ( self ) introduit la méthode d'initialisation de la classe. Son seul paramètre doit être self. L'instruction pass sera remplacée, si besoin, par une séquence de code utile à l'initialisation de la classe. Par exemple, pour initialiser un compteur ou donner une valeur de départ à une variable qui sera retournée en fin de traitement.

def step ( self , Qa , Qb , ... ,  Qn ) : introduit la méthode de traitement des données fournies par la table. En plus du paramètre obligatoire, en première position, self, sa définition devra attendre un nombre de paramètres égal à attributs et correspondant à chacun d'eux, la gestion des valeurs NULL devra être appréhendée par le programme. L'instruction pass sera remplacée par le code utile au traitement personnalisé des données transférées depuis la table. Cette méthode sera appelée par tous les enregistrements, fiches, lignes, de la la table associée à la requête contenue dans l'appel de la méthode objet.create_window_function ( ).

def value ( self ) : introduit la méthode de retour éphémère. Son seul paramètre doit être self. L'instruction pass sera remplacée par le code utile pour retourner la valeur éphémère. Cette méthode sera appelée par tous les enregistrements, fiches, lignes, de la la table associée à la requête contenue dans l'appel de la méthode objet.create_window_function ( ).

def inverse ( self , Qa , Qb , ... ,  Qn ) : introduit la méthode d'annulation de traitement. En plus du paramètre obligatoire, en première position, self, sa définition devra attendre un nombre de paramètres égal à attributs et correspondant à chacun d'eux, la gestion des valeurs NULL devra être appréhendée par le programme. L'instruction pass sera remplacée par le code utile pour annuler, si besoin, certains traitements faits aux variables de la classe, ou faire des saut sur certains enregistrements. Cette méthode sera appelée par tous les enregistrements associée à la requête contenue dans l'appel de la méthode objet.create_window_function ( ).

def finalize ( self ) : introduit la méthode terminale du traitement. Son seul paramètre doit être self. Elle sera invoquée à la suite du traitement du dernier enregistrement fourni par la table. Elle devra se terminée par l'instruction return avec une valeur de retour du type attendu par le programme. Cette valeur sera consultable, généralement, à l'aide de curseur.fetchone ( ) ou, plus rarement avec curseur.fetchmany ( ) ou curseur.fetchall ( ). 

Après avoir définie un lien entre un mot clé et une classe grâce à la méthode objet.create_window_function ( ), il sera possible de retourner dans un champ éphémère, et pour chaque enregistrement de la table, ou de la sélection, une valeur. l'ensemble de ces valeurs seront retournées et consultables dans la list ( ) de tuple ( ) par la méthode curseur.fetchall ( ). 

La commande SQL utilisant la méthode  doit avoir la forme générale suivante :

" SELECT item0 , lien ( valeurs ) OVER ( ROWS BETWEEN a PRECEDING AND d FOLLOWING ) AS item1 FROM table "

item0 est le champ donc les valeurs successives seront les premiers éléments des tuple ( ) retournés.

valeurs est le(s) champ(s) donc les valeurs correspondent au paramètre attributs dans objet.create_window_function ( ).

a et b sont des int ( ) permettant de naviguer dans certaines lignes de la table.

item1 est le(s) champ(s) champs éphémères donc les valeurs successives seront les éléments suivants des tuple ( ) retournés.

table est la table ou la sélection à parcourir.

Pour plus de détails sur les commandes BETWEEN, FOLLOWING, OVER, ROWS, PRECEDING, consultez le site de SQLite.

Si attributs est égal à 1, c'est-à-dire si la valeur d'un seul champ est transmis à la méthode classe.step ( ), on pourra préfixer le nom du champ de la commande SQL : 

- ALL, valeur par défaut, pour que toutes les valeurs soit transmises, même si une valeur égale a déjà était traitée ;

- DISTINCT, pour qu'une valeur soit transmise, uniquement si précédemment aucune valeur égale n'a était traitée.

Par exemple, si les valeurs à passer à la méthode classe.step ( ) sont : G ; G ; N ; G ; P ; N ; G ; P ; G ; N.

- sans préfixe, équivaut avec le préfixe par défaut, c'est-à-dire ALL ;

- avec ALL, elle sera appelée 10 fois pour traiter G ; G ; N ; G ; P ; N ; G ; P ; G ; N , soit 5 fois G, 3 fois N et 2 fois P ;

- avec DISTINCT, elle sera appelée 3 fois pour traiter G ; N ; P , soit 1 fois G, 1 fois N et 1 fois P.

La création d'un objet curseur est facultative. Toutes les méthodes de la classe sqlite3.Cursor ( ) : curseur.execute ( ), curseur.fetchall ( ), ... , peuvent être appelées anonymement. Dans ce cas Python crée un objet curseur éphémère, utilise la méthode appelée, directement, de cette objet curseur éphémère, puis ferme cette objet curseur éphémère. Toutefois la création d'un objet curseur avec la méthode CUR_Curseur = BDD_Basse.cursor ( ) est vivement conseillée. 

Voir la classe sqlite3.Cursor ( ) pour plus d'information sur les objets curseur.

EXEMPLE. 

import sqlite3

# --- Définition de la classe d'agrégation ---

class CLS_Calculs :

# --- Constructeur de classe --- 

def __init__ ( self ) :

self.fiches = 0

self.rayon = 0

# --- Traitement individuel de chaque fiche de la table ou de la sélection --- 

def step ( self , Q ) :

print ( f"Le double de { Q } est { Q * 2 } et son triple est { Q * 3 }." )

self.fiches += 1

self.rayon = Q

# --- Traitement individuel de chaque fiche et retourne de la valeur éphémère --- 

def value ( self ) :

print ( f"La surface d'un rond de rayon { self.rayon } est  { 2 * self.rayon * 9.86 }.\n" )

return  2 * self.rayon * 9.86

# --- Navigation dans les ligne de la table --- 

def inverse ( self , Q ) :

print ( f"La méthode inverse de la valeur { Q } est exécutée ...\n" )

# --- Actions à effectuer une fois après avoir traité toutes les fiches --- 

def finalize ( self ) :

print ( f"\n{ self.fiches } fiches ont été traité." )

return self.fiches

# --- Fin de définition de la classe d'agrégation ---

LST_Premiers = [ ( 1 , 1 ) , ( 2 , 4 ) , ( 3 , 9 ) , ( 5 , 25 ) , ( 7 , 49 ) ]

BDD_Connexion = sqlite3.Connection ( ":memory:" )

BDD_Connexion.create_aggregate ( "calcul" , 1 , CLS_Calculs ) # si une requête contient le mot calcul, instancier CLS_Calculs

BDD_Connexion.execute ( " CREATE TABLE IF NOT EXISTS Premiers ( Nombre INTEGER , Carre INTEGER ) " )

BDD_Connexion.executemany ( " INSERT INTO Premiers ( Nombre , Carre ) VALUES ( ? , ? ) " , LST_Premiers )

BDD_Connexion.commit ( )

# instancier CLS_Calculs, pour chaque fiche exécute et retourne une valeur dans le champs éphémère surface

kselection = BDD_Connexion.execute ( " SELECT Nombre , calcul ( Nombre ) OVER ( ROWS BETWEEN 0 PRECEDING AND 0 FOLLOWING ) AS surface FROM Premiers " )

# affichage des tuple ( ) retournés avec la valeur de Nombre et du calcul pour surface

print ( kselection.fetchall ( ) ) 

BDD_Connexion.close ( )