complete questionnaire.md and add link to go back to README.md

Author: DevCTx

README.md

@@ -1,11 +1,27 @@
+[README.md](./README.md)
+
 # Unit Tests Practice
 
-This repository has been prepared to practice the automated testing framework unittest through different angles.
+### This repository has been prepared to practice the 'unittest' automated testing framework through different angles
+### It is based on the use of simple quizzes importer and viewer.
+
+---
+
+>python ./questionnaire_import.py 
+
+Loads some quizzes from a sample list in the program and converts them into a specific json [format](./questionnaire.md#expected-json-schema) before to save them 
+into the [json_questionnaires](./json_questionnaires) folder
+
+More info : [questionnaire_import.md](./questionnaire_import.md)
+
+---
+
+>python ./questionnaire.py <questionnaire.json>
+
+Displays the quizz in argument and counts the number of good answers
+
+More info : [questionnaire.md](./questionnaire.md)
+
+---
 
-./questionnaire_import.py : Allows to load some questionnaires into json format
-These ones arrives 
-# These questionnaires have been loaded from openquizzdb on https://www.kiwime.com/oqdb/files/
-# The API which allows to directly load them have been disconnected and is not available anymore
-# Some questionnaires have thus been transfered on www.codeavecjonathan.com for allowing
-# to be manipulated through this exercise
 

empty.json

@@ -0,0 +1,105 @@
+[README.md](./README.md) > [questionnaire.md](./questionnaire.md)
+
+# Questionnaire.py
+
+Displays the quizz in argument and counts the number of good answers
+
+```commandline
+python questionnaire.py <questionnaire.json>
+```
+
+## Sample :
+
+```commandline
+python questionnaire.py .\json_questionnaires\animaux_leschats_confirme.json
+```
+```commandline
+Catégorie : Animaux
+Difficulté : confirmé
+Titre : Les chats
+
+QUESTION 1
+  À quelle classe d'animaux vertébrés regroupant près de 5.400 espèces appartient le chat ?
+   1 - Mammifères
+   2 - Reptiles
+   3 - Oiseaux
+   4 - Poissons
+Votre réponse (entre 1 et 4) :
+```
+```commandline
+Bonne réponse
+
+Score final : 14 sur 20
+```
+---
+
+Questionnaire.py can accept a json file from :
+* the current folder 
+* a different folder
+* an URL
+
+Questionnaire.py tries to load the json file in argument or print :
+- [```Error in argument```] if no one or more than one argument is passed
+- [```Incorrect extension```] if the file as no json extension 
+- [```Invalid Path```] if the path to the file can not be reached  
+- [```No File```] if the file can not be find into the path folder 
+- [```Invalid URL```] if the path to the server can not be reached  
+- [```File not found```] if the file can not be reached on the distant server
+- [```Incompatible or no data in JSON file```] if the json file cannot be loaded and decoded
+- [```Incompatible Json schema```] if the loaded json file does not match the 
+expected [schema](./questionnaire.md#expected-json-schema)
+- [```The title of the quizz is missing```] if the titre is an empty string
+
+These messages may also be printed but are <u>not critical</u> to the quiz
+- [```Skipped question : nothing to ask in question```] if the question is an empty string
+- [```Skipped question : no one or more than one good answer in question```] if a question has no one or more than 
+one ```boolean```  at ```True``` in its answers
+
+At least, if all questions have been skipped, [```No compatible question in this quizz```] will be printed.
+
+---
+## Expected Json Schema
+
+```categorie``` and ```difficulte``` properties are not required but ```titre``` and ```questions``` are mandatory
+
+
+Each questions must have at least 2 possible answers and each answers must be defined by a ```string``` and 
+a ```boolean``` only
+
+
+```json lines
+schema = {
+    "$schema": "http://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "required": [ "titre", "questions" ],
+    "properties": {
+        "categorie": {"type": "string"},
+        "titre": {"type": "string"},
+        "questions": {
+            "type": "array",
+            "default": [],
+            "items": {
+                "type": "object",
+                "properties": {
+                    "titre": {"type": "string"},
+                    "choix": {
+                        "type": "array",
+                        "minItems": 2,
+                        "items": {
+                            "type": "array",
+                            "minItems": 2,
+                            "prefixItems": [
+                                {"type": "string"}, 
+                                {"type": "boolean"}
+                            ],
+                            "items": false
+                        }
+                    }
+                }
+            }
+        },
+        "difficulte": {"type": "string"}
+    }
+}
+```
+

json_file_without_extension

@@ -40,7 +40,7 @@ class bcolors:
     UNDERLINE = '\033[4m'
 
 def printerr(msg):
-    return print(f"{bcolors.FAIL}{msg}{bcolors.ENDC}")
+    return print(f"{bcolors.FAIL}Error : {msg}{bcolors.ENDC}")
 
 
 class Question:
@@ -118,38 +118,54 @@ class Questionnaire:
         }
     }
 
-    def __init__(self, json_questionnaire):
+    def __init__(self, json_questionnaire, filename):
         '''Test the expected json schema before to initiate'''
 
         try:
             validate(json_questionnaire, self.schema)
         except jsonschema.exceptions.ValidationError:
             printerr(f"Incompatible Json schema in file : {filename}")
         else:
-            # 'categorie', 'difficulte' : non-blocking properties, but better to be completed as unknown if absent
+            # 'categorie', 'difficulte' : non-critical properties, but better to be completed as unknown if absent
             self.categorie = json_questionnaire['categorie'] if json_questionnaire.get('categorie') else 'inconnue'
             self.difficulte = json_questionnaire['difficulte'] if json_questionnaire.get('difficulte') else 'inconnue'
 
-            # 'titre' or 'questions' : required properties already checked into schema
-            self.titre = json_questionnaire['titre']
-            self.questions = []
-            for json_question in json_questionnaire['questions']:
-                self.questions.append( Question.FromJSON(json_question) )
+            # 'titre' or 'questions' are required properties
+            # all the types are already verified into the schema validator but the len=0 may also identify an error
+            if len(json_questionnaire['titre']) <= 0 :
+                printerr(f"The title of the quizz is missing in file : {filename}")
+            else:
+                self.titre = json_questionnaire['titre']
+                self.questions = []
+                for idx, json_question in enumerate(json_questionnaire['questions']):
+                    if len(json_question['titre']) <= 0:   # This is not critical but the question won't be added
+                        printerr(f"Skipped question : nothing to ask in question {idx} file : {filename}")
+                    else:
+                        good_answers = [ choix[0] for choix in json_question['choix'] if choix[1]==True]
+                        if len(good_answers)!=1:           # This is not critical but the question won't be added
+                            printerr(f"Skipped question : no one or more than one good answer "
+                                     f"in question {idx} file : {filename}")
+                        else:
+                            self.questions.append(Question.FromJSON(json_question))
 
     def run(self):
         # Launch of the questionnaire
+        print(f"=== QUESTIONNAIRE ===")
         print(f"Catégorie : {self.categorie}")
         print(f"Difficulté : {self.difficulte}")
         print(f"Titre : {self.titre}\n")
 
         score = 0
         index = 0
-        for question in self.questions:
-            index+=1
-            if question.ask(index):
-                score += 1
+        if len(self.questions) <= 0 :
+            print("No compatible question in this quizz")
+        else:
+            for question in self.questions:
+                index+=1
+                if question.ask(index):
+                    score += 1
 
-        print("Score final :", score, "sur", len(self.questions))
+            print("Score final :", score, "sur", len(self.questions))
         return score
 
 
@@ -189,7 +205,7 @@ def load_json_argv( sysargv ):
         try:    # Opening of the JSON file
             json_file = open(filename, "r")
         except OSError:
-            printerr(f"Invalid File : {filename}")
+            printerr(f"Invalid Path to : {filename}")
             return None
         except FileNotFoundError:
             printerr(f"No File : {filename}")
@@ -202,16 +218,16 @@ def load_json_argv( sysargv ):
                     printerr(f"Incompatible or no data in JSON file : {filename}")
                     return None
 
-    return json_data
+    return json_data, filename
 
 
 
 def main():
 
-    json_data = load_json_argv( sys.argv )
+    json_data, filename = load_json_argv( sys.argv )
 
     if json_data:
-       Questionnaire(json_data).run()
+       Questionnaire(json_data, filename).run()
 
 if __name__ == "__main__":
     main()

questionnaire.md

@@ -1,12 +1,22 @@
+[README.md](./README.md) > [questionnaire_import.md](./questionnaire_import.md)
+
 # Questionnaire_import.py
 
-These quizzes were uploaded from http://www.openquizzdb.org/ or https://www.kiwime.com/oqdb/files/
+Loads some quizzes from a sample list in the program :
+* openquizzdb_50.json
+* openquizzdb_86.json
+* openquizzdb_241.json
+* openquizzdb_90.json
+
+and converts them into a specific json [format](./questionnaire.md#expected-json-schema) before to save them 
+into the [json_questionnaires](./json_questionnaires) folder
 
-The API that allowed them to be uploaded for free has been disconnected and is no longer available. Some quizzes have 
-thus been transferred to www.codeavecjonathan.com to simulate a download and be manipulated through this exercise
+Those quizzes were initially downloaded from http://www.openquizzdb.org/ or https://www.kiwime.com/oqdb/files/ but the 
+API that allowed to do it for free has been disconnected and is no longer available. Those quizzes have 
+thus been transferred on www.codeavecjonathan.com to be manipulated through this exercise
 
 
-### Initial json quizz format :
+### Sample of the initial json quiz format :
 ```json
 {
     "fournisseur" : "OpenQuizzDB - Fournisseur de contenu libre (https://www.openquizzdb.org)",
@@ -31,7 +41,7 @@ thus been transferred to www.codeavecjonathan.com to simulate a download and be
     {
         "fr" :
         {
-            "débutant" : [
+            "débutant" : [10 items
                 0 : {
                     "id": 1,
                     "question": "À quelle classe d'animaux vertébrés appartient le chat ?",
@@ -46,7 +56,8 @@ thus been transferred to www.codeavecjonathan.com to simulate a download and be
                     },
                 1: {},
                 ...
-                10: {},
+                10: {}
+            ],
             "confirmé" : [10 items],
             "expert" : [10 items],
         },
@@ -66,11 +77,11 @@ Each category comprises 10 questions with 4 possible answers to be proposed to t
 The good answer is saved under ```réponse``` 
 ___
 
-> questionnaire_import.py
+> python questionnaire_import.py
 
-loads json quiz files and converts them to a new format by creating one file per difficulty category
+loads json quiz files and converts them to a new json format by creating one file per difficulty category
 
-### json quizz format after import :
+### Sample of the json quizz format after import :
 ```json
 {
   "categorie" : "Animaux",
@@ -93,47 +104,11 @@ loads json quiz files and converts them to a new format by creating one file per
 }
 ```
 This file represents the second ```confirmé``` difficulty and therefore contains the first 20 questions
-The ```débutant``` quiz contains only the first 10 questions and the ```expert``` quiz contains all the questions
+The ```débutant``` quiz contains only the first 10 questions and the ```expert``` quiz contains the whole 30 questions
 
-The only rubrics kept are: ```catégorie```, ```nom```, of ```catégorie-nom-slogan``` in French (fr) and the items of the
-```quizz``` in French(fr). These last ones are compiled to have 4 propositions and a boolean parameter indicating if the
-answer is the good one. 
+The only keys kept are: ```catégorie```, ```nom```, of ```catégorie-nom-slogan``` in French (```fr```) and the items of
+the ```quizz``` in French(```fr```). These last ones are compiled to have 4 propositions and a boolean parameter 
+indicating if the answer is the good one. 
 
 ---
-### The schema must so match with the one tested in ./questionnaire.py
-```json
-schema = {
-    "$schema": "http://json-schema.org/draft/2020-12/schema",
-    "type": "object",
-    "required": [ "titre", "questions" ],
-    "properties": {
-        "categorie": {"type": "string"},
-        "titre": {"type": "string"},
-        "questions": {
-            "type": "array",
-            "default": [],
-            "items": {
-                "type": "object",
-                "properties": {
-                    "titre": {"type": "string"},
-                    "choix": {
-                        "type": "array",
-                        "minItems": 2,
-                        "items": {
-                            "type": "array",
-                            "minItems": 2,
-                            "prefixItems": [
-                                {"type": "string"}, 
-                                {"type": "boolean"}
-                            ],
-                            "items": false
-                        }
-                    }
-                }
-            }
-        },
-        "difficulte": {"type": "string"}
-    }
-}
-```
-
+### The schema must so match with the one tested in [./questionnaire.py](./questionnaire.md#expected-json-schema)