hdabo: comparison src/hdalab/views/ajax.py

equal deleted inserted replaced

-:b7d19cd87fcf
+:09e00f38d177
 import logging
 logger = logging.getLogger(__name__)
 def tagtranslation(request):
+"""
+Vue donnant des traductions de label de tag pour une langue.
+la recherche se fait dans les objets :class:`hdalab.models.DbpediaFieldsTranslation`.
+Paramêtres GET:
+:var lang: La langue demandée
+:var labels: Un ou plusieurs labels de tag (séparateur : ",")
+Réponse (application/json):
+Un dictionnaire sous la forme ::
+{
+"<label1>": "<translation>",
+"<label2>": "<translation>"
+}
+"""
 lang = request.GET.get('lang',request.LANGUAGE_CODE)
 labels = request.GET.get('labels',None)
 if not labels:
 translations = dict([(t.master.label, t.label) for t in translationqs])
 return HttpResponse(content=json.dumps(translations), content_type='application/json')
-def subcat(category, globtags, level, max_level ):
+def subcat(category, globtags, level, max_level):
+"""
+Méthode récursive utilisée pour reconstruire un arbre de catégories.
+:param object category: La catégorie racine.
+:param dict globtags: dictionnaire flobal des tags.
+:param int level: Niveau de récursion.
+:param int max_level: Niveau maximum de récursion (level <= max_level)
+:returns: L'arbre des catégories.
+"""
 # recursive function used by cattree
 catlabel = category.label
 tags = Tag.objects.filter(wp_categories__wp_category = category).distinct()
 taglabels = [k for k in dict([(t.label,t.label) for t in tags])]
 resobj = {
 subcats = WpCategory.objects.filter(parent_categories__parent_category = category)
 resobj['themes'] += [subcat(subcats[i], globtags, level + 1, max_level ) for i in range(len(subcats))]
 return resobj
 def cleantags(category):
+"""
+Methode annexe qui nettoie recursivement un arbre de catégorie. elle effectue les actions suivantes:
+- retire les clefs correspondant à des listes vides ('contents' et 'themes')
+- trie les listes 'themes' par label
+- trie les listes 'contents' par score
+:param category: la catégorie racine où commencer le traitement.
+"""
 if category.has_key('contents') and len(category['contents']) == 0:
 del category['contents']
 if category.has_key('contents'):
 category['contents'] = sorted(category['contents'], key=lambda content: -content['score'])
 if category.has_key('themes'):
 if len(category['themes']) == 0:
 del category['themes']
 return category
 def cattree(request):
+"""
+Contruit l'arbre de catégorie pour un label.
+Les contenus attachés aux noeud sont des listes de fiches hdalab triées par score.
+Le score pour une fiche est fonction de ses tags, de leur ordre, de leur présence dnas l'arbre des catégories et de leur hauteur dans l'arbre des catégories.
+Paramêtres GET :
+:var label: Le label
+Réponse (application/json):
+Un json représentant l'arbre des catégories avec pour chaque noeud une liste ordonnée de fiches liée à la catégorie.
+exemple ::
+{
+"label": "<label1>",
+"themes": [ { "label": "<label1.1>", "themes": [...], "contents": [...]}, ...],
+"contents": [
+{
+"organization": "Ciclic",
+"description": "Ciclic propose...",
+"score": 7,
+"title": "Vocabulaire de l'analyse filmique...",
+"url": "http://upopi.ciclic.fr/vocabulaire/definition/sceance-11",
+"hda_id": "5879",
+"organization_url": "http://www.ciclic.fr/",
+"id": 14852
+},
+...
+]
+}
+"""
 # Gets the category tree from a label
 ROOT_MAX_TAG_ORDER = 8
 MAX_TAG_ORDER = 8
 MAX_LEVEL = 3
 LEVEL_COEFF = 5
 }
 return HttpResponse(content=json.dumps(resobj), content_type='application/json')
 def sessioninfo(request):
+"""
+Vue gérant les session Hda permettant de sauvegarder un état d'interface.
+Note : Cette vue n'est pas mappée dans le module `hdalab.url`.
+"""
 data = json.loads(request.GET.get('data', "{}"))
 write = False
 if 'sessionid' in request.GET:
 return HttpResponse(content=json.dumps(resobj), content_type='application/json')
 def tagsearch(request):
+"""
+Vue permettant la recherche dans les tag.
+La recherche se fait dans les objets :class:`hdabo.models.Tag`, :class:`hdalab.models.DbpediaFields` et :class:`hdalab.models.DbpediaFieldsTranslation`.
+Paramêtres GET:
+:var (str) term: Le terme à rechercher.
+:var (str) lang: La langue dans laquelle il faut faire la recherche.
+:var (int) count: Le nombre maximum de résultat.
+:var (bool) count_notices: Ajoute ou pas le nombre de notices par tag.
+Réponse (application/json):
+Une liste comprenant les résultats de la recherche.
+exemple ::
+[
+{
+"original_label": "Cathédrale Notre-Dame de Chartres",
+"url": "http://fr.wikipedia.org/wiki/Cath%C3%A9drale_Notre-Dame_de_Chartres",
+"abstract": "La cathédrale Notre-Dame de Chartres ...",
+"value": "Cathédrale Notre-Dame de Chartres",
+"thumbnail": "http://commons.wikimedia.org/wiki/Special:FilePath/Chartres_Cath+Gare.JPG?width=300",
+"nb": 7
+},
+{
+"original_label": "Cathédrale Notre-Dame de Paris",
+"url": "http://fr.wikipedia.org/wiki/Cath%C3%A9drale_Notre-Dame_de_Paris",
+"abstract": "La cathédrale Notre-Dame de Paris...",
+"value": "Cathédrale Notre-Dame de Paris",
+"thumbnail": "http://commons.wikimedia.org/wiki/Special:FilePath/Notre_Dame_de_Paris_DSC_0846w.jpg?width=300",
+"nb": 6
+},
+...
+]
+"""
 q = request.GET.get('term',None)
 maxcount = int(request.GET.get('count','40'))
 lang = request.GET.get('lang',request.LANGUAGE_CODE)
 count_notices_str = request.REQUEST.get("count_notices")
 if q is None or resobj['value'].lower().find(lq) != -1:
 res.append(resobj)
 return HttpResponse(content=json.dumps(res), content_type='application/json')
 def catsearch(request):
+"""
+Vue permettant la recherche de catégorie. On se restreint aux catégories qui sont aussi des tags.
+Paramêtres GET:
+:var (str) term: Le terme à rechercher.
+Réponse (application/json):
+Une liste comprenant le résultat de la recherche.
+exemple ::
+[
+{ "value": "1982 au cinéma" },
+{ "value": "Cinéma italien" },
+{ "value": "2003 au cinéma" },
+...
+]
+"""
 q = request.GET.get('term',None)
 # On ne récupère que les catégories qui sont également des tags
 qrx = '(\\m|\\b)%s'%q
 res = [{'value':t.label} for t in qs]
 return HttpResponse(content=json.dumps(res), content_type='application/json')
 def filter(request):
+"""
+Vue permettant de filtrer par facette des fiches HDA.
+Cette méthode est en fait un simple wrapper pour la méthode `filter_generic`.
+Paramêtres GET:
+:var lang: la langue de recherche (défaut: fr-fr).
+:var period: Période dans laquelle doit se faire la recherche.
+:var label: un mot-clef.
+:var country: Une liste de pays limitant la recherche.
+:var contentlist: Liste de fiches limitant la recherche.
+:var mto: Ordre maximum des tags (défaut: 12).
+:var contentcount: nombre de fiches maximum (défaut : 8).
+:var tagcount: nombre maximum de tag (défaut: 30).
+Réponse (application/json):
+Un objet comprenant le résultat de la recherche.
+"""
 lang = request.GET.get('lang',request.LANGUAGE_CODE)
 periode = request.GET.get('period',None)
 label = request.GET.get('label', None)
 country = request.GET.get('country', None)
 return HttpResponse(content=outputstr, content_type='application/json')
 def filter_generic(lang="fr-fr", periode=None, label=None, country=None, contentlist=None, max_tag_order=12, content_count=8, tag_count=30):
+"""
+Méthode de recherche par facette sur les fiches HDA.
+:param str lang: La langue de recherche (défaut: "fr-fr").
+:param str period: Période d'année limitant la recherche. Le format est `<année-début>,<année-fin>` (défaut: None).
+:param str label: Limite la recherche à un label de tag (défaut: None).
+:param str country: Liste de pays où limiter la recherche. Le format est `<uri dbpedia pays 1>,<uri dbpedia pays 2>...` (défaut: None).
+:param str contentlist: Liste d'id de fiche HDA (:class:`hdabo.models.Datasheet`) limitant la recherche. Le format est `<id1>,<id2>...` (défaut: None)
+:param int max_tag_order: Limite le nombre maximum de tag par fiche (défaut: 12).
+:param int content_count: Limite le nombre de fiches résultat (défaut: 8).
+:param int tag_count: Limite le nombre de tag dans le résultat (défaut: 30).
+:rtype: string
+:returns: Un objet json sérialisé comprenant les résultats de la recherche pour les différentes facettes.
+Clefs de l'objet:
+- :count: Nombre total de fiches.
+- :disciplines: Liste de disciplines artistiques en relation avec les reesultats, triée par score.
+- :countries: Objet dont les clef sont des uri dbpedia de pays et les valeurs sont le nombre de fiches.
+- :tags: Liste de tag triés par score.
+- :sparkline: Liste d'année avec un score, triés par année. Le score est lié au nombre de fiche dont le contenu couvre l'année en question.
+- :contents: Liste de fiches HDA répondant à la recherche, classée par score. Chaque fiche comporte une liste de tag.
+- :tagtranslations: Objet donnant les traductions de label de tag rencontrés dans les résultats.
+exemple::
+{
+"count": 936,
+"disciplines": [
+{
+"translated_label": "Peinture",
+"score": 936,
+"label": "Peinture"
+},
+{
+"translated_label": "Sculpture",
+"score": 88,
+"label": "Sculpture"
+},
+...
+],
+"countries": {
+"http://fr.dbpedia.org/resource/Iran": 1,
+"http://fr.dbpedia.org/resource/Espagne": 16,
+...
+},
+"tags": [
+{
+"url": "http://fr.dbpedia.org/resource/Portrait",
+"id": 63452,
+"translated_label": "Portrait",
+"score": 179,
+"wkpd_url": "http://fr.wikipedia.org/wiki/Portrait",
+"label": "Portrait",
+"thumbnail": "http://commons.wikimedia.org/wiki/Special:FilePath/Fayum02.jpg?width=300"
+},
+...
+],
+"sparkline": [
+{
+"score": 2,
+"year": -600
+},
+{
+"score": 4,
+"year": -500
+},
+...
+{
+"score": 18,
+"year": 2001
+}
+],
+"contents": [
+{
+"description": "Le palais Fesch, ...",
+"title": "Histoires bibliques",
+"url": "http://www.musee-fesch.com/index.php/musee_fesch/content/view/ef_catalogue_sommaire/1513/%28node_id_theme%29/33459",
+"tags": [
+{
+"url": "http://fr.dbpedia.org/resource/Peinture",
+"id": 54648,
+"translated_label": "Peinture",
+"wkpd_url": "http://fr.wikipedia.org/wiki/Peinture",
+"label": "Peinture",
+"order": 1,
+"match": true
+},
+...
+],
+"score": 23,
+"coords": {
+"city_name": "Ajaccio",
+"latitude": 41.916667,
+"longitude": 8.733333
+},
+"hda_id": "4448",
+"id": 13855
+},
+{
+"description": "...",
+"title": "Le XIXe siècle",
+"url": "http://www.grandpalais.fr/fr/article/le-xixe-siecle",
+"tags": [ ... ],
+"score": 22,
+"hda_id": "5217",
+"id": 13582
+},
+...
+],
+"tagtranslations": {
+"Paul Cézanne": "Paul Cézanne",
+"Politique": "Politique",
+"Poésie": "Poésie",
+"Religion": "Religion",
+"Empereur": "Empereur",
+"Saint": "Saint",
+...
+}
+}
+"""
 no_translate_langs = [ 'fr' ]
 key_parts = ("filter",lang,periode,label,country,contentlist,max_tag_order,content_count,tag_count)
 key_parts = [unicode(p).encode("ascii", "ignore") for p in key_parts]
 return outputstr
 def subtree(tree):
+"""
+Methode récursive permettant de remplir un arbre ce catégories avec les fiches HDA correspondantes.
+:param tree: L'arbre de catégorie
+:returns:Un arbre de catégorie rempli de fiches HDA.
+format du paramêtre `tree` ::
+{
+"label": "secteur urbain",
+"contents": [
+{ "label": "banlieue",
+"contents": [
+{ "label": "faubourg" }
+] },
+{ "label": "îlot" },
+...
+]
+}
+Exemple de retour ::
+{
+"label": "secteur urbain",
+"contents": [
+{
+"score": 6,
+"organization": "Institut national de l'audiovisuel ( INA )",
+"description": "Pour faire face à la ...",
+"title": "La construction des grands ensembles de banlieue : l'exemple de Sarcelles",
+"url": "http://fresques.ina.fr/jalons/fiche-media/InaEdu01075/la-construction-des-grands-ensembles-de-banlieue--l-exemple-de-sarcelles",
+"hda_id": "2090",
+"organization_url": "http://www.ina.fr",
+"id": 12360
+},
+{
+"score": 6,
+"organization": "Maison de banlieue et d'architecture",
+"description": "La Maison de banlieue et d'architecture...",
+"title": "Des ensembles assez grands. Mémoire et projets en Essonne",
+"url": "http://maisondebanlieue.fr/wp-content/uploads/2011/05/Cahier11_grands_ensembles.pdf",
+"hda_id": "5893",
+"organization_url": "http://www.maisondebanlieue.fr/",
+"id": 14821
+},
+...
+]
+"themes": [
+{
+"label": "faubourg",
+"content":  [...],
+"themes": [...]
+},
+...
+]
+}
+"""
 MAX_TAG_ORDER = 16
 label = tree['label']
 sub = tree.get('contents',[])
 datasheets = Datasheet.objects.filter(validated = True, taggedsheet__tag__label__iexact = label, taggedsheet__order__lte = MAX_TAG_ORDER).annotate(tagorder=Min('taggedsheet__order')).select_related('organisation').distinct()
 res['themes'] = subcats
 return res
 def filltree(request):
+"""
+Vue permettant d'ajouter des fiches à un arbre de catégories.
+Cette méthode est en fait un simple wrapper pour la méthode :meth:`subtree`.
+Paramêtres GET:
+:var tree: Serialisation json d'un arbre de catégories à remplir. exemple:
+::
+{
+"label": "secteur urbain",
+"contents": [
+{ "label": "banlieue",
+"contents": [
+{ "label": "faubourg" }
+] },
+{ "label": "îlot" },
+...
+]
+}
+Réponse (application/json):
+L'arbre de catégories remplis de fiches HDA (c.f. retour methode :meth:`subtree`)
+"""
 tree = request.GET.get('tree','{}')
 treeobj = json.loads(tree)

branch	documentation
changeset 693	09e00f38d177
parent 620	f45d7494332e