doctring for non route functions

truthseeker/logic/data_persistance/data_access.py

@@ -18,41 +18,103 @@ engine = create_engine(url_object)
 session = Session(engine)
 
 
-def get_text_from_lid(lang, lid) -> str:
+def get_text_from_lid(lang: str, lid: int) -> str:
+    """
+    Returns the text linked to a language and a locale id
+
+    :param lang: the lang to return the text in
+    :param lid: the locale id the get the text from
+    :return: the text associated to the lang and lid
+    """
     return session.query(tables.Locale).filter_by(LANG=lang, TEXT_ID=lid).one().TEXT
 
 def get_random_place() -> tables.Place:
+    """
+    Returns a random place from the database.
+
+    :return: a Place object
+    """
     return random.choice(session.query(tables.Place).all())
 
 def get_random_npc() -> tables.Npc :
+    """
+    Returns a random npc from the database
+
+    :return: a Npc object
+    """
     return random.choice(session.query(tables.Npc).all())
 
-def get_npc_random_trait_id(npc) -> int:
+def get_npc_random_trait_id(npc_id: int) -> int:
-    reactions = session.query(tables.Reaction).filter_by(NPC_ID=npc.NPC_ID).all()
+    """
+    Returns a random reaction for a given npc
+
+    :param npc_id: the npc to get the reaction from
+    :return: a reaction identified by it's trait id
+    """
+    reactions = session.query(tables.Reaction).filter_by(NPC_ID=npc_id.NPC_ID).all()
     reaction = random.choice(reactions)
     return reaction.TRAIT_ID
 
-def get_npc_random_answer(npc, qa_type) -> tables.Answer :
+def get_npc_random_answer(npc_id:int, qa_type:int) -> tables.Answer :
-    answers = session.query(tables.Answer).filter_by(QA_TYPE=qa_type,NPC_ID=npc.NPC_ID).all()
+    """
+    Returns a random answser from a given npc and question type
+
+    :param npc_id: the npc to get the answer from
+    :param qa_type: the type of the question
+    :return: an Answer object
+    """
+    answers = session.query(tables.Answer).filter_by(QA_TYPE=qa_type,NPC_ID=npc_id.NPC_ID).all()
     return random.choice(answers)
 
-def get_random_question(qa_type) -> tables.Answer :
+def get_random_question(qa_type: int) -> tables.Question :
+    """
+    Returns a random inspector question from a question type
+
+    :param qa_type: the type of the question
+    :return: a Question object
+    """
     answers = session.query(tables.Question).filter_by(QUESTION_TYPE=qa_type).all()
     return random.choice(answers)
 
-def get_trait_from_text(text):
+def get_trait_from_text(text: str) -> int:
+    """
+    Returns the trait_id from its text value
+
+    :param text: the text representation of the trait in any lang
+    :return: the trait_id linked to this text
+    """
     trait_lid = session.query(tables.Locale).filter_by(TEXT=text).one().TEXT_ID
     return session.query(tables.Trait).filter_by(NAME_LID=trait_lid).one().TRAIT_ID
 
-def get_trait_from_trait_id(trait_id):
+def get_trait_from_trait_id(trait_id: int) -> tables.Trait:
+    """
+    Gets a Trait object from a trait_id
+
+    :param trait_id: the id of the trait to search for
+    :return: a Trait object
+    """
     trait = session.query(tables.Trait).filter_by(TRAIT_ID=trait_id).one()
     return trait
 
-def get_reaction_description(lang,npc_id,trait_id):
+def get_reaction_description(lang,npc_id,trait_id) -> str:
+    """
+    Returns the description of the reaction of a given npc in the language specified by the parametter lang
+
+    :param lang: the language to return the description in
+    :param npc_id: the id of the npc to get the reaction description from
+    :trait_id: the trait associated to the reaction to get the description from
+    :return: the description in the given language
+    """
     desc_lid = session.query(tables.Reaction).filter_by(NPC_ID=npc_id,TRAIT_ID=trait_id).one().DESC_LID
     return get_text_from_lid(lang,desc_lid)
 
-def get_traits(lang):
+def get_traits(lang: str) -> list:
+    """
+    Returns the list of all possible reactions trait in the given language
+
+    :param lang: the lang to return the reactions traits in
+    :return: a list of string reprensentation of the reactions traits
+    """
     traits = []
     for trait in session.query(tables.Trait).all():
         traits.append(get_text_from_lid(lang,trait.NAME_LID))

truthseeker/logic/game_logic.py

@@ -42,12 +42,12 @@ class Game:
     """
     The game info class stores all information linked to a active game
 
-    :attr str game_id: str, the game identifier of the game
+    :attr str game_id: the game identifier of the game
     :attr owner  Member: the player start created the game. It is also stored in self.members
     :attr Member[] members: the members of the game
-    :attr bool has_started: TODO
+    :attr bool has_started: status of the current game
-    :attr TODO gamedata: TODO
+    :attr dict gamedata: data of the game (npcs, their text, their reactions and rooms placement)
-    :attr TODO reaction_table: TODO
+    :attr dict reaction_table: mapping of the npc_ids in the game to their reactions id
     """
 
     def __init__(self):
@@ -69,9 +69,11 @@ class Game:
         self.members.append(self.owner)
         return self.owner
 
-    def generate_game_results(self) -> None:
+    def generate_game_results(self) -> dict:
         """
-        TODO + TODO RET TYPE
+        Create the final leaderboard of the game, containing all members score.
+
+        :return: a dictionnary representation of the leaderboard
         """
         data = {}
         npcs = data["npcs"] = {}
@@ -89,7 +91,7 @@ class Game:
 
     def generate_data(self) -> None:
         """
-        TODO
+        Creates and sets the game's data (npcs, their text, their reactions and rooms placement)
         """
 #       TODO Get language from player
         self.gamedata, self.reaction_table = generate_game_data("FR")
@@ -100,7 +102,7 @@ class Game:
         Get a Member object from a username
 
         :param username: the username of the member to search for
-        :return the member corresponding to the username, or None if none if found:
+        :return: the member corresponding to the username, or None if none if found:
         """
         for member in self.members:
             if member.username == username:
@@ -119,18 +121,25 @@ class Game:
         self.members.append(member)
         return member
 
-    def get_npc_reaction(self, npc_id) -> None:
+    def get_npc_reaction(self, npc_id) -> bytes:
         """
-        TODO + TODO TYPES
+        Returns the reaction image of a npc, if found in the reaction table
+
+        :param npc_id: the id of the npc, to get the reactions from, must be in the current game
+        :return: the reaction image as bytes
         """
         if npc_id not in self.reaction_table:
             return 0
         reaction_id = self.reaction_table[npc_id]
         return read_image(f"./truthseeker/static/images/npc/{npc_id}/{reaction_id}.png")
 
-    def get_player_results(self, responses: dict) -> None:
+    def get_player_results(self, responses: dict) -> Union[dict, False]:
         """
-        TODO + TODO RETTYPE
+        Checks the player's answers againts the reaction map.
+        Return None when a npc is not found in the reaction table, meaning an invalid npc was sent
+
+        :param responses: the player anwsers, a dictionnary of npc_id to the string representation of the npc's reaction
+        :return: a dictionnary of npc_id to a boolean, true if they got the correct answer, false if not.
         """
         results = {}
         try:
@@ -208,6 +217,14 @@ def check_username(username: str) -> bool:
 
 
 def generate_npc_text(npc: tables.Npc, lang: str) -> dict:
+    """
+    Creates the dictionnary of a npc names and dialogs, it searches the npc's pool of answser for both question
+    types
+
+    :param npc: a Npc object
+    :param lang: the lang to get the text in
+    :return: a dictionnary object containing the npc's name and both answers
+    """
     data = {}
     data["name"] = get_text_from_lid(lang, npc.NAME_LID)
     data["QA_0"] = get_text_from_lid(lang, get_npc_random_answer(npc, 0).TEXT_LID)
@@ -215,25 +232,38 @@ def generate_npc_text(npc: tables.Npc, lang: str) -> dict:
     return data
 
 
-def generate_npc_reactions(npc: tables.Npc) -> list:
+def generate_place_data(npc_list: list, places: list, lang: str) -> dict:
-    return get_npc_random_trait_id(npc)
+    """
+    Create the place dictionnary for a game, assigns two npc for each room given in the place_list
+    except the last one who will be alone :(
 
-
+    :param npcs_list: the list of all npcs in the game
-def generate_place_data(npcs: list, places: list, lang: str) -> dict:
+    :param place_list: the list of the given rooms
+    :param lang: the language to seach the name of the room in
+    :return: a dictionnary of place_id to an array of npc_id and a string of the room name
+    """
     data = {}
-    random.shuffle(npcs)
+    random.shuffle(npc_list)
     for place in places:
         placedata = data[str(place.PLACE_ID)] = {}
         placedata["name"] = get_text_from_lid(lang, place.NAME_LID)
         placedata["npcs"] = []
-        for _ in npcs:
+        for _ in npc_list:
-            placedata["npcs"].append(npcs.pop().NPC_ID)
+            placedata["npcs"].append(npc_list.pop().NPC_ID)
             if len(placedata["npcs"]) == 2:
                 break
     return data
 
 
-def generate_game_data(lang):
+def generate_game_data(lang: str) -> tuple[dict, dict]:
+    """
+    Create the gamedata of a game for a given language, chooses 5 random npcs, generate their texts and reactions,
+    chooses 3 random rooms and places the npcs in them and chooses an inspector question for each type of question
+    availible in the Question Table.
+
+    :param lang: the lang to generate all the texts in
+    :return: two dictionnaries, one containing the game data, the second containing the reaction table
+    """
     data = {}
     data["npcs"] = {}
     reactions_table = {}
@@ -244,7 +274,7 @@ def generate_game_data(lang):
             npcs.append(npc)
     for npc in npcs:
         data["npcs"][str(npc.NPC_ID)] = generate_npc_text(npc, lang)
-        reactions_table[str(npc.NPC_ID)] = generate_npc_reactions(npc)
+        reactions_table[str(npc.NPC_ID)] = get_npc_random_trait_id(npc)
 
     places = []
     while len(places) != 3:
@@ -261,6 +291,12 @@ def generate_game_data(lang):
 
 
 def read_image(path: str) -> bytes:
+    """
+    Returns the byte representation of an image given its path
+
+    :param path: the path to the image
+    :return: the byte representation of the image, none if its not found or not readable
+    """
     try:
         with open(path, "rb") as file:
             return file.read()
@@ -269,8 +305,20 @@ def read_image(path: str) -> bytes:
 
 
 def get_trait_id_from_string(trait: str) -> int:
+    """
+    Returns the trait_id from its text value
+
+    :param text: the text representation of the trait in any lang
+    :return: the trait_id linked to this text
+    """
     return get_trait_from_text(trait)
 
 
-def get_npc_image(npc_id):
+def get_npc_image(npc_id: int):
+    """
+    Returns the byte representation of the neutral image for an npc
+
+    :param npc_id: npc to get the neutral image from
+    :return: the byte representation of the image, none if its not found or not readable
+    """
     return read_image(f"./truthseeker/static/images/npc/{npc_id}/0.png")