=======================================
 Import de la trace brute (06/10/2021)
=======================================

.. role:: en

Trace brute
===========

La trace brute que nous nous proposons d'étudier ici est fournie par l'`API de github`_, plus précisément la partie qui permet de récupérer les `tickets`_ (`issues`:en:) et leurs commentaires.

Pour vous faire gagner du temps, un `script python`_ vous est fourni, qui permet de récupérer tous les tickets et tous les commentaires d'un dépôt. Ce script accepte les arguments suivants :

* Un argument obligatoire donnant le nom du dépôt, sous la forme ``owner/repo`` (par exemple, ``pchampin/sophia_rs`` pour le dépôt https://github.com/pchampin/sophia_rs).

* L'argument optionnel ``--out`` indique dans quel fichier écrire les données récupérées. **Attention**: si le fichier existe déjà, son contenu sera *remplacé*. Si cet argument n'es pas spécifié, les données seront écrites sur la sortie standard.

* L'argument optionnel ``--prev`` permet de spécifier le chemin d'un fichier précédemment produit par le script, pour le même dépôt. Le script interrogera alors l'API de github de telle manière à ne récupérer que les éléments plus récents que ceux ayant déjà été récupérés.

* L'argument optionnel ``--auth`` permet de spécifier un jeton d'authentification github, qui peut être créé sur https://github.com/settings/tokens.

.. warning::

    Il n'est **pas nécessaire** de créer un jeton d'authentification pour utiliser l'API.
    Notez cependant que l'API est soumise à des quotas (nombre limité d'appels par heure) et que ces quotas sont plus importants pour les utilisateurs authentifiés.

    Quoi qu'il en soit, que vous ayez ou non un jeton d'authentification,
    il faut donc utiliser l'API github (et donc le script qui vous est fourni) avec parcimonie, pour ne pas saturer vos quotas.
    Stockez le JSON obtenu dans un fichier, et travaillez ensuite sur ce fichier local.

Le fichier JSON produit par ce script contient un tableau d'objets JSON ; les objets du début du tableau représentent les tickets, ceux de la fin du tableau représentent les commentaires.

.. admonition:: Votre travail

    Choisissez un dépôt github, et récupérez à l'aide du script fourni un fichier JSON contenant tous les tickets et commentaires de ce dépôt.

Modèle de traces
================

On souhaite convertir la trace brute (JSON) récupérée en une trace modélisée en RDF, conforme au modèle de traces décrit dans la `fig-modele`:numref:.

.. figure:: _static/trace_model.svg
    :name: fig-modele
    
    Modèle de traces pour les tickets et les commentaires

Ce diagramme de classe décrit les entités que nous souhaitons représenter, avec leurs propriétés et les relations qu'elles entretiennent. Quelques précisions sont nécessaires.

* Le préfixe ``s:`` correspond à l'IRI http://schema.org/ (un vocabulaire standard que nous réutilisons autant que possible).
* Le préfixe ``ex:`` correspond à l'IRI ``http://exampe.com/ns#`` (un vocabulaire imaginaire qui nous permet de décrire les concepts non présents dans Schema.org).
* En plus des classes `Issue`:en: et `Comment`:en:, on voit que le modèle de traces inclut des entités supplémentaires (`Repository`:en:, `User`:en:, `Label`:en:). En effet, ces entités sont utiles pour représenter l'activité, et elles sont également décrites dans le JSON de la trace brute (comme attributs des tickets et des commentaires).

  - Notons cependant que seules `Issue`:en: (et ses sous-classes) et `Comment`:en: ont le statut d'*obsel*, puisque seules ces entités sont horodatées.

  - Ces entités supplémentaires sont décrites plusieurs fois dans le JSON (notamment les utilisateurs et les labels). Cette redondance n'est pas gênante puisque, dans le graphe RDF, les arcs identiques ne sont pris en compte qu'une seule fois.

* Pour identifier les entités dans notre graphe RDF, on choisit l'IRI qui les identifie dans l'API de github (attribut ``url`` dans le JSON).

  - Par contraste, la propriété ``s:url`` sera utilisée pour pointer vers la représentation HTML de l'entité (attribut ``html_url`` dans le JSON).

* Les identifiants internes (attribut ``id``) utilisés par github ne nous intéressent pas. La propriété ``s:accountId`` de la classe ``User`` correspond au *login* de l'utilisateur concerné ; la propriété ``s:identifier`` de la classe ``Issue`` correspond au numéro de ticket (attribut ``number``).

* Les classes dont le nom est entre parenthèses ne sont pas matérialisées dans le graphe RDF, et donc leurs instances n'auront pas de propriété ``rdf:type`` explicite indiquant qu'elles appartiennent à cette classe.

.. admonition:: Votre travail

    Écrire

    * un contexte JSON-LD qui, associé au JSON retourné par l'API de github, permet de produire un graphe conforme au modèle ci-dessus, et
    * un programme qui utilise une bibliothèque JSON-LD pour appliquer ce contexte et produire le graph RDF au format n-quads.

.. hint::

    Une liste de bibliothèque implémentant JSON-LD est disponible sur https://json-ld.org/#developers.

    Pour développer (`expand`:en:) ou convertir en RDF un document JSON natif, la meilleure solution consiste à fournir le contexte séparément, via l'option ``expandContext`` des algorithmes.

    NB: en PyLD_, les options sont passées via un dictionnaire:

    .. code-block:: python

       jsonld.to_rdf(raw_doc, {
           'expandContext': ctx,  # contexte à appliquer
           'format': 'application/n-quads', # format de sortie
       }))




.. _`API de github`: https://docs.github.com/en/free-pro-team@latest/rest
.. _`tickets`: https://docs.github.com/en/free-pro-team@latest/rest/overview/endpoints-available-for-github-apps#issues
.. _`script python`: _static/import_github_trace.py
.. _PyLD: https://github.com/digitalbazaar/pyld