Added basic dict operations

Included "swap keys-values" function.
Added dict filtering functions for the "students scores" challenge.
Changed existing functions signatures.
Added more explanations for the "filter_by_values" function.

Signed-off-by: Serhii Horodilov <sgorodil@gmail.com>

Author: shorodilov

src/datasets/__init__.py

@@ -2,16 +2,25 @@
 Dataset challenges
 ==================
 
+Swap dictionary keys and values
+-------------------------------
+
+.. autofunction:: swap_dict_loop
+
+.. autofunction:: swap_dict
+
 """
 
 __all__ = [
+    "swap_dict",
+    "get_low_student",
+    "get_top_student",
+    "get_both_top_low_students",
     "get_bricks_count",
     "get_position_frequency",
     "get_least_bricks_position",
     "get_least_bricks_count",
     "filter_by_values",
 ]
 
-from datasets.func import (filter_by_values, get_bricks_count,
-                           get_least_bricks_count, get_least_bricks_position,
-                           get_position_frequency)
+from datasets.func import *

src/datasets/func.py

@@ -3,11 +3,149 @@
 
 """
 
-from typing import Any, Dict, List, Optional, Set
+from typing import Any, Dict, Hashable, List, Optional, Set, Tuple, Union
+
+
+# BASIC OPERATIONS
+# ================
+
+def swap_dict_loop(origin: Dict[Hashable, Hashable]
+                   ) -> Dict[Hashable, Hashable]:
+    """
+    Return a new dictionary with swapped keys and values from the original
+
+    :param origin: the dictionary to swap the keys and values of
+    :type origin: dict
+    :return: a new dictionary with the swapped keys and values
+    :rtype: dict
+
+    The function iterates through the dictionary keys using a ``for`` loop.
+    On each iteration step the value assigned at the original dictionary key
+    is accessed. After that the values and key are written down to a new
+    dictionary, but not using the value as key and vice versa.
+
+    This is the most descriptive algorithm to solve the swap task.
+
+    Example usage:
+
+    >>> swap_dict_loop({1: "one", 2: "two", 3: "three"})
+    {"one": 1, "two": 2, "three": 3}
+
+    """
+
+    result = {}
+
+    for key in origin:
+        value = origin[key]
+        result[value] = key
+
+    return result
+
+
+def swap_dict(origin: Dict[Hashable, Hashable]) -> Dict[Hashable, Hashable]:
+    """
+    Return a new dictionary with swapped keys and values from the original
+
+    :param origin: the dictionary to swap the keys and values of
+    :type origin: dict
+    :return: a new dictionary with the swapped keys and values
+    :rtype: dict
+
+    Works similar to ``swap_dict_loop`` function, but uses dictionary
+    comprehension instead of the ``for`` loop.
+
+    Example usage:
+
+    >>> swap_dict({1: "one", 2: "two", 3: "three"})
+    {"one": 1, "two": 2, "three": 3}
+
+    """
+
+    return {value: key for key, value in origin.items()}
+
+
+# define typing hints aliases
+StudentData = Dict[str, Union[str, List[int]]]  # student data type alias
+StudentsList = List[StudentData]  # students data type alias
+
+
+def get_avg_score(student_data: StudentData) -> float:
+    """Return average score of a student"""
+
+    scores: List[int] = student_data["scores"]  # type: ignore
+
+    return round(sum(scores) / len(scores))
+
+
+def get_top_student(students_data: StudentsList) -> StudentData:
+    """
+    Return a student who has the highest average score
+
+    :param students_data: a list of students data (names and scores)
+    :type students_data: list
+
+    :return: student data entity
+    :rtype: dict
+
+    """
+
+    threshold = float("-inf")  # negative infinite, less that any number
+    result = {"name": "", "scores": []}
+
+    for student in students_data:
+        avg_score = get_avg_score(student)
+        if avg_score > threshold:
+            threshold = avg_score
+            result = student  # type: ignore
+
+    return result  # type: ignore
+
+
+def get_low_student(students_data: StudentsList) -> StudentData:
+    """
+    Return the student who has the lowest average score
+
+    :param students_data: a list of students data (names and scores)
+    :type students_data: list
+
+    :return: student data entity
+    :rtype: dict
+
+    """
+
+    threshold = float("+inf")  # positive infinite, bigger that any number
+    result = {"name": "", "scores": []}
+
+    for student in students_data:
+        avg_score = get_avg_score(student)
+        if avg_score < threshold:
+            threshold = avg_score
+            result = student  # type: ignore
+
+    return result  # type: ignore
+
+
+def get_both_top_low_students(students_data: StudentsList
+                              ) -> Tuple[StudentData, StudentData]:
+    min_score_threshold, max_score_threshold = float("+inf"), float("-inf")
+    top_student = {"name": "", "scores": []}
+    low_student = {"name": "", "scores": []}
+
+    for student in students_data:
+        avg_score = get_avg_score(student)
+        if avg_score > max_score_threshold:
+            max_score_threshold = avg_score
+            top_student = student  # type: ignore
+        if avg_score < min_score_threshold:
+            min_score_threshold = avg_score
+            low_student = student  # type: ignore
+
+    return top_student, low_student  # type: ignore
 
 
 # BRICK WALL CHALLENGE
 # ====================
+
 def get_bricks_count(structure: List[List[int]]) -> int:
     """Return number of bricks in the wall structure
 
@@ -17,11 +155,11 @@ def get_bricks_count(structure: List[List[int]]) -> int:
     :return: total number of bricks in the entire wall structure
     :rtype: int
 
-    Usage:
+    Usage examples:
 
-    >>> get_bricks_count([[1], [1], [1]]) == 3
-    >>> get_bricks_count([[1, 1, 1], [1, 1, 1]]) == 6
-    >>> get_bricks_count([[2, 1, 2], [1, 1, 1, 1, 1]]) == 8
+    >>> assert get_bricks_count([[1], [1], [1]]) == 3
+    >>> assert get_bricks_count([[1, 1, 1], [1, 1, 1]]) == 6
+    >>> assert get_bricks_count([[2, 1, 2], [1, 1, 1, 1, 1]]) == 8
 
     """
 
@@ -37,7 +175,7 @@ def get_position_frequency(structure: List[List[int]]) -> Dict[int, int]:
     :return: the position - frequency matrix
     :rtype: dict[int, int]
 
-    Usage:
+    Usage examples:
 
     >>> assert get_position_frequency([[1], [1], [1]]) == {}
     >>> assert get_position_frequency([[1, 2], [2, 1], [3]]) = {1: 1, 2: 1}
@@ -70,7 +208,7 @@ def get_least_bricks_position(structure: List[List[int]]) -> int:
     This function uses helper function ``get_structure_matrix`` to build
     the matrix of distances from the left edge of the "wall".
 
-    Usage:
+    Usage examples:
 
     >>> assert get_least_bricks_position([[1], [1], [1]]) == 0
     >>> assert get_least_bricks_position([[1, 1, 1], [1, 1, 1]]) == 1
@@ -93,7 +231,7 @@ def get_least_bricks_count(structure: List[List[int]]) -> int:
     :return: minimum number of bricks in a line
     :rtype: int
 
-    Usage:
+    Usage examples:
 
     >>> assert get_least_bricks_count([[1], [1], [1]]) == 3
     >>> assert get_least_bricks_count([[1, 2], [2, 1], [3], [1, 1, 1]]) == 2
@@ -112,8 +250,9 @@ def get_least_bricks_count(structure: List[List[int]]) -> int:
 # FILTER DATASET CHALLENGE
 # ========================
 
-def filter_by_values(origin: List[Dict[str, Any]],
-                     keys: Optional[List[str]] = None) -> List[Dict[str, Any]]:
+def filter_by_values(origin: List[Dict[str, Hashable]],
+                     keys: Optional[List[str]] = None
+                     ) -> List[Dict[str, Any]]:
     """Return a filtered datasets by unique values in a given keys sets
 
     :param origin: an original dataset with entries to filter
@@ -125,33 +264,52 @@ def filter_by_values(origin: List[Dict[str, Any]],
     :rtype: list
 
     The origin dataset is a list of dictionaries. All the dictionaries have
-    the same set of keys of a string type. At least one entry with at least
-    one key is granted.
+    the same set of keys of a string type. All dictionaries values are of
+    a hashable type.
+
+    In case no data provided (``origin`` is an empty list) the function will
+    return an empty list.
 
     The keys parameter is used to set the dictionary keys to filter unique
     values. Keys list is considered to be validated before passing to this
     function, all values (if any) are valid. In case this parameter is
     omitted - all available keys should be used.
 
-    Usage:
+    Inputs are considered to be pre-validated as described above,
+    no need for additional checks.
+
+    Usage examples:
 
     >>> ds = [{"x": 1, "y": 2, "z": 3}, {"x": 0, "y": 2, "z": 3}]
+    >>> assert filter_by_values([]) == []              # no data to filter
+    >>> assert filter_by_values(ds) == ds              # the same as origin
     >>> assert filter_by_values(ds, ["x"]) == ds       # the same as origin
     >>> assert filter_by_values(ds, ["x", "z"]) == ds  # the same as origin
     >>> assert filter_by_values(ds, ["y"]) == [{"x": 1, "y": 2, "z": 3}]
     >>> assert filter_by_values(ds, ["y", "z"]) == [{"x": 1, "y": 2, "z": 3}]
 
     """
 
-    filtered_dataset: List[Dict[str, Any]] = []
+    # check base cases
+    if not origin:
+        return []
+
+    # declare variables to store runtime data
+    filtered_dataset: List[Dict[str, Hashable]] = []
     filtered_values: Set[int] = set()
 
+    # in case no keys provided get all keys from the first one dictionary
     keys = keys or origin[0].keys()  # type: ignore
+
+    # iterate though the list and perform de-duplication task
     for entry in origin:
         entry_values = hash(tuple(map(entry.get, keys)))  # type: ignore
+        # in case the values has been filtered already
+        # proceed to the next iteration
         if entry_values in filtered_values:
             continue
 
+        # update filtered values
         filtered_values.add(entry_values)
         filtered_dataset.append(entry)