Get result

src/wordguess/get_n_guesses.py

@@ -1,5 +1,6 @@
 from ._internals import minidict
 
+
 def get_n_guesses(result_hist: dict, n: int = None, corpus: list = minidict) -> list:
     """
     Return all possible target words consistent with the result history.
@@ -16,23 +17,33 @@ def get_n_guesses(result_hist: dict, n: int = None, corpus: list = minidict) ->
     valid guesses. If the parameter n is provided, n random words from the valid
     guesses are returned. If n is None, all valid guesses are returned.
 
-    Parameters:
-    result_hist (dict): A dictionary mapping previously guessed words to their
-                        corresponding result strings composed of '0', '1', and '2'.
-    n (int): The number of valid guesses to return. If None, all valid guesses
-             are returned.
-    corpus (list): A list of all allowed words to consider as possible targets.
+    Parameters
+    ----------
+    result_hist : dict
+        A dictionary mapping previously guessed words to their
+        corresponding result strings composed of '0', '1', and '2'.
+    n : int (optional)
+        The number of valid guesses to return.
+        If None, all valid guesses are returned.
+    corpus : list (optional)
+        A list of all allowed words to consider as possible targets.
 
-    Returns:
+    Returns
+    -------
     list: A list of words from the corpus that are consistent with the result history.
 
-    Example:
+    See Also
+    --------
+    get_result : A function that generate the result string for a given guess against a target word.
+
+    Examples
+    --------
     >>> result_hist = {"crane": "01200", "sloth": "10020"}
     >>> get_n_guesses(result_hist, corpus=corpus)
-    Output: ['about', 'shout', 'mount']
+    ['about', 'shout', 'mount']
 
     >>> get_n_guesses(result_hist, n=2, corpus=corpus)
-    Output: ['shout', 'mount']
+    ['shout', 'mount']
     """
     # TODO: write checks for input
     # TODO: write the function body

src/wordguess/get_result.py

@@ -0,0 +1,36 @@
+from _internals import minidict
+
+
+def get_result(target: str, guess: str, corpus: list = minidict) -> str:
+    """
+    Generate a guess feedback for a given guess against a target word.
+
+    Parameters
+    ----------
+    target : str
+        The secret word that needs to be guessed.
+    guess : str
+        The word provided by the player to be compared against the target.
+    corpus : list (optional)
+        A collection of valid words used for validation.
+        Defaults to `minidict`.
+
+    Returns
+    -------
+    str
+        A string of digits representing the result for each letter:
+        - '0' : The letter does not exist in the target.
+        - '1' : The letter exists in the target but in a different position.
+        - '2' : The letter is in the correct position.
+
+    Examples
+    --------
+    >>> get_result("apple", "apply")
+    '22220'
+    >>> get_result("stare", "tears")
+    '11211'
+    >>> get_result("books", "slope")
+    '00201'
+    """
+
+    pass

src/wordguess/result_to_pattern.py

@@ -1,28 +1,34 @@
 def result_to_pattern(result: str) -> str:
     """
     Convert a result string to a human-readable pattern of symbols.
-    
+
     This function maps each character in a result string to a corresponding colored square
     symbol.
     - The character '0' maps to a dark grey square symbol,
     - The character '1' maps to a yellow square symbol and,
     - The character '2' maps to a green square symbol.
     The output is a string composed of UTF-8 colored square symbols.
-
-    Parameters:
-    result (str): a string consisting only of the '0', '1' or '2' characters.
-
-    Returns:
+
+    Parameters
+    ----------
+    result : str
+        A string consisting only of the '0', '1' or '2' characters.
+
+    Returns
+    -------
     str: The corresponding human-readable string pattern composed of UTF-8 colored symbols.
-
+
+    See Also
+    --------
+    get_result : A function that generate the result string for a given guess against a target word.
+
     Example:
     >>> result_to_pattern("01102")
-    Output: "⬛🟨🟨⬛🟩"
+    "⬛🟨🟨⬛🟩"
     >>> result_to_pattern("0001221")
-    Output: "⬛⬛⬛🟨🟩🟩🟨"
-
+    "⬛⬛⬛🟨🟩🟩🟨"
     """
-    
+
     # print("\u2B1B") # ⬛ grey square
     # print("\U0001F7E8") # 🟨 yellow square
-    # print("\U0001F7E9") # 🟩 green square
+    # print("\U0001F7E9") # 🟩 green square