Module:Wikidata/Chemin/Documentation

Ceci est la page de documentation pour Module:Wikidata/Chemin

Page en cours de rédaction
Cette page est inachevée. Veuillez considérer le plan et le contenu comme incomplet et en préparation, temporaires et sujets à caution. Si vous souhaitez participer, il vous est recommandé de consulter sa page de discussion au préalable.

Le module Wikidata/Chemin est une implémentation un peu adaptée des PropertyPath de Q54871 (« SPARQL ») en Lua poun Wikidata et les clients Wikibase.

Il existe cependant quelques différences entre les chemins de propriétés sparql et cette implémentation:

la syntaxe est étendue pour gérer les qualificatifs des déclarations (opérateur >)
contrairement au cas de l’implémentation sparql, il est nécessaire de fournir un point de départ pour le calcul des valeurs possibles au bout du chemin
il est possible d’utiliser les identifiants Wikidata des propriétés sans préfixe d’uri, et il est également possible d’utiliser les intitulés des propriétés dans la langue principale du wiki (par exemple il est possible d’utiliser père pour la propriété P22 (« père »)
l’opérateur ^ ne peut pas fonctionner en lua avec l’API mw.wikibase actuelle (mai 2019)

Limitation : Le support des rangs. Pour l’instant il n’y a pas de moyen de prendre en compte les déclarations de rang « normal » s’il y en a des privilégiées ou « déprécié ».

Chemins

Exemple introductif

Un chemin pour trouver les petits-enfants "enfant/enfant" sera notre premier chemin. Nous allons l’utiliser en paramètre d’un modèle de démonstration capable d’utiliser des chemins, à partir d’un élément choisi, prenons l’élément du Dieu Grec Zeus (Q34201 (« Zeus ») : {{Liste valeur chemin wikidata|Q34201|enfant/enfant}}

Le modèle liste en premier résultat (au moment de l’écriture de ces lignes) Q572133 (« Antéros »). La raison de sa présence est l’existence d’une déclaration Wikidata

Q34201 (« Zeus »)

P22 (« père ») : Q40901 (« Arès »)

puis sur Q40901 (« Arès ») d’une déclaration

Q40901 (« Arès »)

P22 (« père ») : Q572133 (« Antéros ») .

En réalité Zeus à de nombreux autres petits enfants qui ne sont par montrés parce que le modèle se limite par défaut à un certain nombre de résultats.

De manière similaire, si nous voulons lister les mères des enfants de Zeus nous pouvons utiliser le chemin enfant/P25 grâce à la propriété P25 (« mère ») :

Ces exemples n’utilisent qu’un seul connecteur, / qui permet d’exprimer une séquence de déclarations. Il en existe d’autre que nous allons décrire brièvement dans la section suivante, qui peuvent se combiner pour créer des chemins plus complexes.

Opérateurs

Dans ce qui suit, un chemin d’entités sera une séquence d’éléments et de propriétés. Un chemin d’entités sera potentiellement terminé par une valeur Wikidata comme une date ou une quantité. Voici un exemple de chemin d’entités Q1001 (« Mahatma Gandhi ») → P31 (« nature de l’élément ») → Q5 (« être humain ») → P279 (« sous-classe de ») → Q215627 (« personne ») ou Q34201 (« Zeus ») → P40 (« enfant ») → Q40901 (« Arès ») → P40 (« enfant ») → Q572133 (« Antéros »). Il est possible de créer des chemins à partir des déclarations Wikidata en partant d’un élément est en suivant les propriétés principales et valeurs principales des différentes déclaration, mais également en suivant les propriétés des qualificatifs et leurs valeurs. Dans ce dernier cas, un chemin peut ressembler à ceci Q991 (« Fiodor Dostoïevski ») → P19 (« lieu de naissance ») → Q656 (« Saint-Pétersbourg ») → P1448 (« nom officiel ») → P580 (« date de début »)

Nous allons maintenant décrire la manière de faire correspondre les « chemins de propriétés » (qu’on appellera également « motif de chemin »), qu’on peut voir comme des motifs, à l’instar des expressions rationnelles à des chemins d’entités. Pour cela nous allons introduire l’opération de « dévorage », entre un chemin de propriété et un chemin d’entités. On dira qu’une propriété peut « dévorer » un chemin d’entité C si la première propriété du chemin est P. Le résultat de l’opération sera le chemin auquel on aura ôté les deux premiers éléments. Par exemple si

P peut dévorer C pour donner le résultat suivant Q656 (« Saint-Pétersbourg ») → P1448 (« nom officiel ») → P580 (« date de début »). Aucune autre propriété ne peut dévorer ce chemin. Nous allons l’étendre dans la suite à des chemins plus complexes que ceux composés avec une unique propriété. L’opération de « dévorage » est utilisée pour construire l’opération de « correspondance » entre un chemin de propriété et un chemin d’entité. Elle peut trouver tous les chemins d’entités qu’on peut construire en partant d’un élément et en suivant les différentes propriétés. Un chemin de propriété correspond à un chemin d’entité si le chemin de propriété peut dévorer entièrement le chemin, à l'exception de son dernier élément.

Par exemple : le chemin Mexique → limitrophe de → USA → limitrophe de → Canada correspond au motif limitrophe de/limitrophe de mais ne correspond pas à limitrophe de ni à limitrophe de/limitrophe de/limitrophe de. Le premier ne correspond pas parce que certaines parties du chemin ne sont pas dévorées, et le dernier parce que le dernier limitrophe de n’a rien à dévorer.

Ce module implémente l’opération d’énumérer les chemins d’entités qui correspondent (peuvent être totalement dévorés) par un motif de chemins. Les différents motifs ont définis dans la suite à l’aide d’opérateurs, pour lesquels on étendra l’opération de dévorage.

Un chemin est construit à partir de chemins élémentaires (des propriétés) et d’opérateurs qui combinent des chemins.

chemin élémentaire: Un chemin élémentaire est soit un identifiant de propriété, comme P31, soit un intitulé de propriété en français comme nature. Un chemin élémentaire dévore un chemin d’entité comme expliqué ci-dessus.
/: l’opérateur de séquençage. Voir l’exemple introductif. Si Modèle:Var est un chemin et Modèle:Var est un chemin alors Modèle:Var/Modèle:Var est également un chemin Modèle:Var/Modèle:Var dévorera un chemin d’entités CE si P1 dévore CE dans un premier temps, puis si P2 dévore le résultat de ce premier dévorage dans un deuxième temps.
|: L’opérateur d’alternative. Si Modèle:Var est un chemin et Modèle:Var est un chemin alors Modèle:Var|Modèle:Var est également un chemin. Modèle:Var|Modèle:Var dévorera un chemin CI si soit P1 dévore IP, soit P2 dévore CI. Le résultat est le résultat de l’opération de dévorage de l’alternative qui correspond.
?: Un opérateur qui rend le chemin qui précède optionnel. Il « dévorera » quelque chose quoi qu’il arrive. Par exemple le motif limitrophe de? en partant de l’élément « Mexico » correspondra au chemin d’entité Mexique (dans ce cas le résultat de l’opération laisse le chemin inchangé) mais également le chemin Mexique → limitrophe de → USA (dans ce cas le résultat du dévorage est USA .
*: Un opérateur (qui correspond à l’étoile de Kleene) qui comme le précédent dévore quelque chose quoi qu’il arrive. Si P est un motif, alors P* est aussi un motif. Il peut manger des chemins de taille arbitraire (en théorie, il existe une limite dans l’implémentation) en répétant le dévorage autant de fois que possible l’opération de dévorage de P. Par exemple le code (père|mère)* va correspondre aux chemins d’entités qui mène d’une personne vers tous ses ancêtres (en incluant elle-même). Elle trouvera le père et la mère de quelqu’un, puis les parents de ces parents, les parents des grands parents et ainsi de suite.
+: P+ est équivalent à P/P*. Similaire à l’opérateur * sauf que le chemin sous-jacent P doit pouvoir dévorer au moins une fois.
>: Cet opérateur sert dans le cas ou on s’intéresse aux qualificatifs d’une déclaration. Par exemple le motif union de>de va dévorer les « snaks » qualificateur avec la propriété P642 (« de ») des déclarations Modèle:P' d’un élément. La valeur à partir de laquelle le prochain opérateur dans une séquence commencera est la valeur du qualificatif.; Cet opérateur peut également être utilisé au tout début d’un motif si le point de départ du chemin est une déclaration, et pas un élément (voir l’exemple plus bas).
!: Cet opérateur permet de définir une correspondance par la négative en spécifiant des propriétés qui ne seront pas dévorées. Toute propriété non listée pourra l’être. Il est suivi soit d’une propriété, soit d’une liste de propriété entre parenthèses séparées par des |. Par exemple !(nature|sous-classe de) vont correspondre avec n’importe quel chemin d’une seule propriété, comme Donald Duck → père → Picsou, mais pas Ghandi → nature → être humain ni humain → sous-classe de → animal. Également utilisable avec l’opérateur > pour exclure un ensemble de qualificateur.
{nombre} et {min, max}: Cet opérateur est utile pour spécifier la répétition d’un dévorage de chemin un certain nombre (borné) de fois. P{4} est équivalent à P/P/P/P, c’est-à-dire que P doit dévorer exactement quatre préfixes d’un chemin, et P{4,6} doit dévorer entre 4 et 6 fois. C’est équivalent à P/P/P/P/P?/P?

Résultats

Ce module représente et retourne les chemins qui sont en correspondance avec un chemin sous forme d’une structure de données de type ResultNode qui représente un noeud d’un chemin en correspondance.

Techniquement le chemin est une liste chaînée de ces nœuds. La liste représente le chemin en ordre inverse, le nœud retourné est le dernier nœud d’un chemin. Chaque nœud peut être considéré comme un « snak » ou comme une « déclaration » (statement) dans le modèle de données Lua (en fait ce sont exactement des snak ou statement du module mw.wikibase, auxquels sont ajoutés d’autres attributs et méthodes). Un nœud de résultat peut être utilisé tel quel comme n’importe quel snak ou statement dans les fonctions du module Module:Wikidata.

Les nœuds précédents dans la liste peuvent être récupérés grâce à l’attribut "parent" d’un nœud.

Interface

Main functions
iterate

path (string), start_item (string, entity object) -> iterator (on result node)

function that takes a path and a start item and returns an iterable object, usable in lua for loops that iterates over the set of paths matching the pattern, each represented by a ResultNode (see above)

Utilisation

Fonctions exportables :

fonction(frame) – description (courte description de fonction(frame) et autres informations pertinentes).
fonction2() – description2 (courte description de fonction2() et autres informations pertinentes).

Autres fonctions :

fonction() – description2 (courte description de fonction() et autres informations pertinentes).

Modules externes et autres éléments dont ce module a besoin pour fonctionner :

mw.title – description (courte description expliquant la dépendance de ce module externe).

Exemples

partir d’une déclaration

Lister les dates de début des mandats des présidents de la république française Q191954 (« président de la République française ») par un moyen un peu tordu pour l’exemple. Utilise P1308 (« titulaire ») sur l’élément « président de la RF pour récupérer tous les présidents et P39 (« fonction ») sur les éléments des présidents, et P522 (« type d'orbite ») comme qualificateur.

local elem_presidence = "Q191954"
local res = ""
for fonction in ppath.iterate(elem_presidence, "titulaire/fonction") do -- pour chacune des fonctions occupées par présidents de la république
	res = res .. wd.formatStatement(fonction)
	if elem_presidence == fonction:item_value() then -- si la fonction est celle de président de la RF
		for date in ppath.iterate(fonction, ">P580") do -- on itère sur les dates de début des déclarations
			res = res .. wd.formatSnak(date)
		end
	end
end

du module Module:Wikidata/Chemin/Documentation/Exemple/prez qui nous donne (une seule date parce qu’il n’y a pour l’instant pas de support des rangs)

Erreur de script : le module « Wikidata/Chemin/Documentation/Exemple/prez » n’existe pas.

Note : Ce code est légèrement plus compliqué qu’il pourrait l’être parce que les date de début de titularisation sont aussi présentes en qualificatif des déclarations « titulaires » de Q191954 (« président de la République française »), on pourrait de contenter de

local elem_presidence = "Q191954"
local res = ""
for date in ppath.iterate(elem_presidence, "titulaire>P580") do -- pour chacune des fonctions occupées par présidents de la république
	res = res .. wd.formatSnak(date)
end

Autres

Voir aussi la page de test permettant de tester diverses modifications apportées (quand il y en aura une)

Projet Scribunto