Module plume.pg.template

Import et préparation des modèles de formulaire.

class plume.pg.template.LocalTemplatesCollection

Bases : dict

Répertoire des modèles disponibles en local.

Les modèles locaux se substitueront aux modèles importés du serveur PostgreSQL si l’extension PlumePg n’est pas installée sur la base courante.

Un objet de classe LocalTemplatesCollection est un dictionnaire dont les clés sont des noms des modèles et les valeurs sont les modèles en tant que tels (objets :py:class:TemplateDict).

Attributes:

labelslist(str)

Liste des noms des modèles locaux.

conditionslist(dict)

Liste des modèles avec leur configuration, notamment leurs conditions d’application automatique. Concrètement, il s’agit des informations qu’on aurait trouvées dans la table z_plume.meta_template si PlumePg avait été active sur la base (a minima le champ tpl_label contenant le nom du modèle).

Methods

clear()
copy()
fromkeys(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
items()
keys()
pop(key[, default])	If the key is not found, return the default if given; otherwise, raise a KeyError.
popitem(/)	Remove and return a (key, value) pair as a 2-tuple.
setdefault(key[, default])	Insert key with a value of default if key is not in the dictionary.
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
values()

class plume.pg.template.TemplateDict(categories, tabs=None)

Bases : object

Modèle de formulaire.

Parameters:

categorieslist(dict) or list(tuple(dict))

Liste des catégories de métadonnées prévues par le modèle avec leur paramétrage, résultant de l’exécution de la requête plume.pg.queries.query_get_categories() ou importée d’un modèle local. Si la liste est constituée de tuples, leur premier élément doit être le dictionnaire qui décrit la catégorie, et tout autre élément ne sera pas considéré.

tabslist(str) or list(tuple(str)), optional

Liste ordonnée des libellés des onglets du modèle, résultant de l’exécution de la requête plume.pg.queries.query_template_tabs(), ou importée d’un modèle local. Si la liste est constituée de tuples, leur premier élément doit être le libellé de l’onglet, et tout autre élément ne sera pas considéré.

Attributes:

tabslist(str)

La liste ordonnée des onglets du modèle. Il s’agira d’une liste vide si le modèle ne spécifie pas d’onglets.

shareddict

Les catégories communes utilisées par le modèle. Les clés du dictionnaire sont les chemins N3 des catégories, les valeurs sont des dictionnaires contenant les informations de paramétrage.

localdict

Les catégories locales utilisées par le modèle. Les clés du dictionnaire sont les chemins N3 des catégories, les valeurs sont des dictionnaires contenant les informations de paramétrage.

class plume.pg.template.TemplateQueryBuilder(filepath, no_update=False, preserve=False)

Bases : object

Constructeur des requêtes qui permettent l’import des modèles en base.

La principal difficulté lors de l’import d’un modèle est le fait que les valeurs des clés primaires numériques des tables des modèles et des onglets, qui servent également de clés étrangères dans la table d’association des catégories aux modèles, ne sont a priori pas les mêmes dans la base d’origine du modèle et dans la base cible.

La classe TemplateQueryBuilder propose un processus d’intégration progressive des modèles qui répond à ce problème. Les enregistrements des différentes tables sont ajoutés ou mis à jour un par un, ce qui permet d’assurer la correspondance entre les anciennes et nouvelles clés.

Le générateur TemplateQueryBuilder.queries() fournit les requêtes, à exécuter au fur et à mesure. Après l’exécution de chaque requête, si et seulement si l’attribut TemplateQueryBuilder.waiting vaut True, le résultat doit être ré-intégré avec la méthode TemplateQueryBuilder.feedback():

>>> builder = TemplateQueryBuilder(filepath)
>>> conn = psycopg2.connect(connection_string)
>>> with conn:
...     with conn.cursor() as cur:
...         for query in builder.queries():
...              cur.execute(*query)
...              if builder.waiting:
...                  result = cur.fetchone()
...                  builder.feedback(result)
>>> conn.close()

Le fichier source est un dictionnaire encodé en JSON, comptant au plus de quatre clés : templates, categories, tabs, template_categories. Chaque clé prend en valeur une liste de dictionnaires dont les clés sont les noms des champs des tables meta_template, meta_categorie, meta_tab et meta_template_categories.

À noter que:

• Les modèles et onglets sont reconnus par leur nom. Si un modèle/onglet de même nom qu’un modèle/onglet défini dans le fichier source existe dans la base cible, il sera mis à jour, sinon un nouveau modèle/onglet est ajouté.

• Le processus échouera si les associations modèle-catégorie font référence à des modèles ou onglets non définies dans le fichier source, ou à des catégories qui ne sont définies ni en base ni dans le fichier source.

• Il n’est pas possible d’utiliser cette méthode pour ajouter des catégories communes qui ne seraient pas présentes en base. Celles-ci seront ignorées si elles n’étaient pas utilisées pour des associations modèle-catégorie, et une erreur se produira dans le cas contraire.

• Si le fichier source contient des enregistrements de la table des modèles, toutes les associations modèle-catégorie correspondantes seront supprimées avant import des associations modèle-catégories du fichier source. La suppression peut être évitée en modifiant la valeur du paramètre preserve.

Parameters:

filepathstr or pathlib.Path

Chemin absolu du fichier source. Le contenu du fichier est récupéré à l’initialisation, et stocké dans les attributs de la classe.

no_updatebool, default False

Si True, les données des catégories et onglets ne sont pas mises à jour lorsque les enregistrements existent déjà en base (les enregistrements manquants sont créés dans tous les cas).

preservebool, default False

Si True, les associations modèle-catégorie des modèles ne sont pas supprimées avant recréation. Les associations qui ne sont pas présentes dans le fichier source seront donc préservées.

Attributes:

templateslist(dict)

Données décrivant des modèles, équivalant à des enregistrements de la table meta_template.

categorieslist(dict)

Données décrivant des catégories de métadonnées, équivalant à des enregistrements de la table meta_categorie.

tabslist(dict)

Données décrivant des onglets, équivalant à des enregistrements de la table meta_tab.

template_categorieslist(dict)

Données décrivant l’association d’une catégorie à un modèle, équivalant à des enregistrements de la table meta_template_categories.

map_tpl_iddict

Correspondance entre les identifiants numériques des modèles dans les données sources et leurs équivalents dans la base de données cible. Ce dictionnaire est complété au fur et à mesure de l’exécution et la ré-intégration du résultat des requêtes.

map_tab_iddict

Correspondance entre les identifiants numériques des onglets dans les données sources et leurs équivalents dans la base de données cible. Ce dictionnaire est complété au fur et à mesure de l’exécution et la ré-intégration du résultat des requêtes.

last_type{None, “templates”, “categories”, “tabs”, “template_categories”}

Nature du dernier enregistrement créé ou mis à jour en base. Cet attribut vaut None tant que le générateur TemplateQueryBuilder.queries() n’a pas été lancé.

last_idint or None

Identifiant numérique du dernier enregistrement créé ou mis à jour en base dans les données sources. Cet attribut vaut None tant que le générateur TemplateQueryBuilder.queries() n’a pas été lancé, ou si le dernier enregistrement traité n’était pas un modèle ou un onglet.

waitingbool

True si le résultat de la requête courante doit être ré-intégré grâce à la méthode TemplateQueryBuilder.feedback(), False sinon. Cet attribut vaut également False pour les requêtes qui n’ont pas de résultat, telles les commandes de suppression, il est donc important de tester sa valeur avant de tenter de récupérer le résultat de la requête.

Methods

feedback(result)	À utiliser pour fournir au générateur les résultats de ses requêtes.
queries()	Générateur de requêtes.

feedback(result)

À utiliser pour fournir au générateur les résultats de ses requêtes.

Concrètement, cette méthode construit des dictionnaires de mapping, qui permettent ensuite au générateur de remplacer les anciens identifiants numériques de modèles (ceux de la base sur laquelle a été réalisé l’export) et d’onglets par les nouveaux (ceux de la base sur laquelle est réalisé l’import).

Parameters:

resultlist(tuple(dict)) or tuple(dict) or dict

Le résultat de la dernière requête produite par le générateur TemplateQueryBuilder.queries().

queries()

Générateur de requêtes.

Yields:

PgQueryWithArgs

Une requête prête à être envoyée au serveur PostgreSQL.

plume.pg.template.dump_template_data(filepath, templates=None, categories=None, tabs=None, template_categories=None, tpl_id=None)

Encode en JSON dans un fichier des données de définition des modèles.

Cette fonction permet d’exporter en JSON les données des modèles stockées en base, éventuellement restreintes à un ou plusieurs modèles spécifiés en argument.

Parameters:

filepathstr or pathlib.Path

Chemin absolu du fichier cible.

templateslist(tuple(dict))) or list(dict), optional

Le contenu de la table des modèles (au moins les enregistrements correspondant au(x) modèle(s) à exporter, le cas échéant). Il peut s’agir du résultat brut renvoyé par la requête générée par plume.pg.queries.query_read_meta_template(), ou plus généralement d’une liste de dictionnaires dont les clés sont les noms des champs de la table et les valeurs sont les valeurs prises par ces champs.

categorieslist(tuple(dict))) or list(dict), optional

Le contenu de la table des catégories (au moins les enregistrements correspondant aux catégories utilisées par le(s) modèle(s) à exporter, le cas échéant). Il peut s’agir du résultat brut renvoyé par la requête générée par plume.pg.queries.query_read_meta_categorie(), ou plus généralement d’une liste de dictionnaires dont les clés sont les noms des champs de la table et les valeurs sont les valeurs prises par ces champs.

tabslist(tuple(dict))) or list(dict), optional

Le contenu de la table des onglets (au moins les enregistrements correspondant aux onglets utilisés par le(s) modèle(s) à exporter, le cas échéant). Il peut s’agir du résultat brut renvoyé par la requête générée par plume.pg.queries.query_read_meta_tab(), ou plus généralement d’une liste de dictionnaires dont les clés sont les noms des champs de la table et les valeurs sont les valeurs prises par ces champs.

template_categorieslist(tuple(dict))) or list(dict), optional

Le contenu de la table d’association des catégories aux modèles (au moins les enregistrements correspondant aux catégories utilisées par le(s) modèle(s) à exporter, le cas échéant).). Il peut s’agir du résultat brut renvoyé par la requête générée par plume.pg.queries.query_read_meta_template_categories(), ou plus généralement d’une liste de dictionnaires dont les clés sont les noms des champs de la table et les valeurs sont les valeurs prises par ces champs.

tpl_idint or list(int), optional

L’identifiant unique du modèle de formulaire à exporter, ou une liste d’identifiants. Si cet argument n’est pas fourni, toutes les données seront incluses.

plume.pg.template.search_template(templates, metagraph=None)

Déduit d’un graphe de métadonnées le modèle de formulaire à utiliser.

Parameters:

templateslist of tuples

La liste de tous les modèles disponibles avec leurs conditions d’usage, résultant de l’exécution de la requête plume.pg.queries.query_list_templates().

metagraphplume.rdf.metagraph.Metagraph, optional

Le graphe de métadonnées issu de la dé-sérialisation des métadonnées d’un objet PostgreSQL. Lorsque cet argument n’est pas fourni, vaut None ou un graphe vide, les conditions d’application des modèles portant sur le graphe ne sont pas considérées.

Returns:

str

Le nom de l’un des modèles de la liste ou None si aucun de convient. Dans ce cas, on utilisera le modèle préféré (preferedTemplate) désigné dans les paramètres de configuration de l’utilisateur ou, à défaut, aucun modèle.

Notes

Quand plusieurs modèles conviennent, celui qui a la plus grande valeur de priority est retenu. Si le niveau de priorité est le même, c’est l’ordre alphabétique qui déterminera quel modèle est conservé (car c’est ainsi qu’est triée la liste renvoyée par plume.pg.queries.query_list_templates()), et la présente fonction considère simplement les modèles dans l’ordre.