refactor: remove singleton pattern in storage and separate a pickle_io module

- Replaced singleton implementation in user_data with a shared data reference approach.
- Moved pickling functionality to a new module pickle_io for better separation of concerns.
- Reduced the complexity of error handling for pickle issue
- Updated `UserDataManager` to accept a custom save function for greater flexibility.
- Enhanced documentation for clarity on functionality and usage.
- Modified persistent_cache to utilize the pickle_io module

Author: FlysonBot

src/mastermind/main/game_controller.py

@@ -2,7 +2,7 @@
 
 from mastermind.game.game import Game
 from mastermind.main.game_history import GameHistoryManager
-from mastermind.storage.user_data import UserDataManager
+from mastermind.storage import userdata
 from mastermind.validation import (
     MaximumAttempts,
     NumberOfColors,
@@ -57,15 +57,15 @@ def start_new_game(cls, game_mode: str) -> None:
     def resume_game(cls, game_index: int) -> None:
         """Resume a saved game."""
         # Retrieve game
-        game = UserDataManager().saved_games[game_index]["game"]
+        game = userdata.saved_games[game_index]["game"]
 
         # Resume game and retrieve exit state
         exit_state = game.resume_game()
 
         # Update saved games if not game discarded
         if exit_state == "d":  # or delete it if discarded
-            UserDataManager().saved_games.pop(game_index)
+            userdata.saved_games.pop(game_index)
         else:
-            UserDataManager().saved_games[game_index] = (
-                GameHistoryManager().generate_meta_data(game)
+            userdata.saved_games[game_index] = GameHistoryManager().generate_meta_data(
+                game
             )

src/mastermind/main/game_history.py

@@ -4,7 +4,7 @@
 
 from mastermind.game.game import Game
 from mastermind.main.game_storage import list_continuable_games, retrieve_stored_games
-from mastermind.storage.user_data import UserDataManager
+from mastermind.storage import userdata
 
 
 def game_list_to_pandas(games: List[dict]) -> Optional[pd.DataFrame]:
@@ -57,10 +57,10 @@ def generate_meta_data(game: Game) -> dict:
     @staticmethod
     def save_game(game: Game) -> None:
         """Save the game to a file."""
-        if "saved_games" not in UserDataManager():  # if the list is empty
-            UserDataManager().saved_games = []  # initialize the list
+        if "saved_games" not in userdata:  # if the list is empty
+            userdata.saved_games = []  # initialize the list
 
-        UserDataManager().saved_games.append(
+        userdata.saved_games.append(
             GameHistoryManager.generate_meta_data(game)
         )  # store the meta data
 

src/mastermind/main/game_storage.py

@@ -1,9 +1,9 @@
-from mastermind.storage.user_data import UserDataManager
+from mastermind.storage import userdata
 
 
 def retrieve_stored_games():
     """Retrieve all stored games"""
-    saved_games = UserDataManager().saved_games
+    saved_games = userdata.saved_games
     return saved_games or []
 
 

src/mastermind/main/main.py

@@ -3,7 +3,7 @@
     list_continuable_games_index,
     retrieve_stored_games,
 )
-from mastermind.storage import UserDataManager
+from mastermind.storage import userdata
 from mastermind.ui.menu import (
     GameHistoryMenu,
     MainMenu,
@@ -83,7 +83,7 @@ def run(self):
         while self.main_menu():
             pass  # keep calling self.main_menu() until it return False
         print("Thank you for playing!")
-        UserDataManager().save_data()
+        userdata.save_data()
 
 
 def main():

src/mastermind/storage/__init__.py

@@ -1,4 +1,6 @@
 from mastermind.storage.persistent_cache import PersistentCacheManager
-from mastermind.storage.user_data import UserDataManager
+from mastermind.storage.user_data import get_user_data_manager
 
-__all__ = ["PersistentCacheManager", "UserDataManager"]
+userdata = get_user_data_manager()
+
+__all__ = ["PersistentCacheManager", "get_user_data_manager"]

src/mastermind/storage/persistent_cache.py

@@ -1,14 +1,19 @@
 import glob
 import os
-import pickle
 from typing import Any
 
+from mastermind.storage.pickle_io import (
+    read_pickled_data,
+    write_pickled_data,
+)
+
 
 class PersistentCacheManager:
     """
     Manages a persistent cache of Python objects on the file system.
 
-    The PersistentCacheManager class provides a simple interface for caching and retrieving data, using the pickle module to serialize and deserialize the objects.
+    The PersistentCacheManager class provides a simple interface for caching and retrieving data,
+    using the pickle_io module for pickling to serialize and deserialize the objects.
 
     The cache files are stored in the "data" directory, which is created automatically if it does not exist.
     """
@@ -32,11 +37,10 @@ def _get_cache_file_path(cls, key: str) -> str:
         Returns:
             str: The file path for the cache file.
         """
-
         return os.path.join(cls._cache_directory, f"{key}.cache")
 
     @classmethod
-    def clear_cache(cls) -> None:
+    def clear_all_cache(cls) -> None:
         """Clears the entire cache by deleting all cache files."""
         for cache_file in glob.glob(os.path.join(cls._cache_directory, "*.cache")):
             os.remove(cache_file)
@@ -52,25 +56,15 @@ def __getattr__(cls, key: str) -> Any:
         Returns:
             Any: The cached value, or None if the key does not exist.
         """
-
-        file_path = cls._get_cache_file_path(key)
-        if os.path.exists(file_path):
-            with open(file_path, "rb") as file:
-                return pickle.load(file)
-        return None
+        return read_pickled_data(cls._get_cache_file_path(key))
 
     @classmethod
-    def set(cls, key: str, value: Any) -> Any:
+    def set(cls, key: str, value: Any) -> None:
         """
         Sets the cached value for the given key.
 
         Args:
             key (str): The key associated with the cached value.
             value (Any): The value to be cached.
-
-        Returns:
-            Any: The cached value.
         """
-
-        with open(cls._get_cache_file_path(key), "wb") as file:
-            pickle.dump(value, file)
+        write_pickled_data(cls._get_cache_file_path(key), value)

src/mastermind/storage/pickle_io.py

@@ -0,0 +1,57 @@
+import os
+import pickle
+from typing import Any
+
+
+def read_pickled_data(filepath: str) -> Any:
+    """Read pickled data from a file and return it.
+
+    Args:
+        filepath (str): The path to the file to read from.
+
+    Returns:
+        Any: The pickled data being read, or None if the file does not exist.
+    """
+
+    ensure_parent_directory_exists(filepath)
+    try:
+        with open(filepath, "rb") as file:
+            return pickle.load(file)
+
+    except FileNotFoundError:
+        return None
+
+
+def ensure_parent_directory_exists(filepath: str) -> None:
+    """Create the parent directory of a file if it doesn't exist.
+
+    Args:
+        filepath (str): The path to the file.
+    """
+    if directory := os.path.dirname(filepath):
+        os.makedirs(directory, exist_ok=True)
+
+    else:
+        raise ValueError("filepath must include a directory component")
+
+
+def write_pickled_data(filepath: str, data: dict) -> None:
+    """Write pickled data to a file.
+
+    Args:
+        filepath (str): The path to the file to write to.
+        data (dict): The data to be pickled and written to the file.
+    """
+
+    ensure_parent_directory_exists(filepath)
+    with open(filepath, "wb") as file:
+        pickle.dump(data, file)
+
+
+def delete_pickled_data(filepath: str) -> None:
+    """Delete a pickled file.
+
+    Args:
+        filepath (str): The path to the file to delete.
+    """
+    os.remove(filepath)