Module:Wikidata/Chemin/Documentation
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
modifierExemple introductif
modifierUn 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}}
- Q572133 (« Antéros »)
- Q106240 (« Déimos »)
- Q121973 (« Éros »)
- Q105019 (« Phobos »)
- Q978079 (« Harmonie »)
- Q1425549 (« Himéros »)
- Q831583 (« Phlégias »)
- Q580862 (« Antiope »)
- Q4217252 (« Adrestia »)
- Q3268334 (« Lycaon »)
- ...(?)
- 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
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 ») :
- Q38012 (« Héra »)
- Q199923 (« Dioné »)
- Q103107 (« Léto »)
- Q38012 (« Héra »)
- Q103107 (« Léto »)
- Q205233 (« Maïa »)
- Q40730 (« Déméter »)
- Q542758 (« Styx »)
- Q776139 (« Sémélé »)
- Q40730 (« Déméter »)
- ...(?)
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
modifierDans 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
- C =
Q991 (« Fiodor Dostoïevski ») → P19 (« lieu de naissance ») → Q656 (« Saint-Pétersbourg ») → P1448 (« nom officiel ») → P580 (« date de début ») →
- P =P19 (« lieu de naissance »)
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 commenature
. 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 P1 est un chemin et P2 est un chemin alors
P1/P2
est également un cheminP1/P2
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 P1 est un chemin et P2 est un chemin alors
P1|P2
est également un chemin.P1|P2
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 cheminMexique → limitrophe de → USA
(dans ce cas le résultat du dévorage estUSA
. *
- 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-jacentP
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é, commeDonald Duck → père → Picsou
, mais pasGhandi → nature → être humain
nihumain → 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, etP{4,6}
doit dévorer entre 4 et 6 fois. C’est équivalent àP/P/P/P/P?/P?
Résultats
modifierCe 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
modifier- 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
modifierFonctions exportables :
fonction(frame)
– description (courte description defonction(frame)
et autres informations pertinentes).fonction2()
– description2 (courte description defonction2()
et autres informations pertinentes).
Autres fonctions :
fonction()
– description2 (courte description defonction()
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
modifierpartir d’une déclaration
modifierLister 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)
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
modifierVoir aussi la page de test permettant de tester diverses modifications apportées (quand il y en aura une)