Рефакторинг. docstring

SRV/storage/json_storage.py

@@ -1,4 +1,3 @@
-# storage/json_storage.py
 import json
 import os
 import logging
@@ -9,22 +8,40 @@ from models.auth import UserCreate, UserResponse
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
-
 class JsonStorage:
-    """Хранилище пользователей в JSON-файле"""
+    """Хранилище пользователей в JSON-файле.
+
+    Предоставляет методы для создания, чтения и проверки данных пользователей,
+    используя шифрование паролей с помощью bcrypt.
+    """
 
     def __init__(self, file_path: str = "/etc/gonets/users.json"):
+        """Инициализирует хранилище пользователей.
+
+        Args:
+            file_path (str, optional): Путь к JSON-файлу для хранения данных.
+                По умолчанию "/etc/gonets/users.json".
+
+        Создаёт объект CryptContext для хеширования паролей и проверяет/создаёт
+        файл, если он отсутствует.
+        """
         self.file_path = file_path
         self.pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
         self._ensure_file_exists()
 
     def _ensure_file_exists(self):
-        """Создаёт JSON-файл, если он не существует"""
+        """Создаёт JSON-файл, если он не существует.
+
+        Создаёт родительские директории и файл с начальной структурой данных,
+        устанавливая права доступа 600.
+
+        Raises:
+            Exception: Если произошла ошибка при создании файла или директории.
+        """
         try:
             logger.info(f"Проверка существования файла {self.file_path}")
             if not os.path.exists(self.file_path):
-                logger.info(
-                    f"Создание директории {os.path.dirname(self.file_path)}")
+                logger.info(f"Создание директории {os.path.dirname(self.file_path)}")
                 os.makedirs(os.path.dirname(self.file_path), exist_ok=True)
                 logger.info(f"Создание файла {self.file_path}")
                 with open(self.file_path, "w") as f:
@@ -40,7 +57,15 @@ class JsonStorage:
             raise
 
     def _read_data(self) -> dict:
-        """Читает данные из JSON-файла"""
+        """Читает данные из JSON-файла.
+
+        Returns:
+            dict: Словарь с данными пользователей и следующим ID.
+
+        Raises:
+            FileNotFoundError: Если файл отсутствует (возвращает пустую структуру).
+            Exception: Если произошла ошибка при чтении файла.
+        """
         try:
             with open(self.file_path, "r") as f:
                 return json.load(f)
@@ -56,7 +81,14 @@ class JsonStorage:
             raise
 
     def _write_data(self, data: dict):
-        """Записывает данные в JSON файл"""
+        """Записывает данные в JSON-файл.
+
+        Args:
+            data (dict): Словарь с данными для записи (пользователи и next_id).
+
+        Raises:
+            Exception: Если произошла ошибка при записи в файл.
+        """
         try:
             with open(self.file_path, "w") as f:
                 json.dump(data, f, indent=2)
@@ -67,7 +99,18 @@ class JsonStorage:
             raise
 
     def create_user(self, user: UserCreate) -> UserResponse:
-        """Создаёт нового пользователя"""
+        """Создаёт нового пользователя с хешированием пароля.
+
+        Args:
+            user (UserCreate): Объект с данными нового пользователя (username, password, is_admin).
+
+        Returns:
+            UserResponse: Объект с данными созданного пользователя (id, username, is_admin).
+
+        Raises:
+            ValueError: Если пользователь с таким именем уже существует.
+            Exception: Если произошла ошибка при записи данных.
+        """
         try:
             data = self._read_data()
             users = data["users"]
@@ -99,7 +142,17 @@ class JsonStorage:
             raise
 
     def get_user_by_username(self, username: str) -> Optional[dict]:
-        """Получает пользователя по имени"""
+        """Получает данные пользователя по имени.
+
+        Args:
+            username (str): Имя пользователя для поиска.
+
+        Returns:
+            Optional[dict]: Словарь с данными пользователя или None, если пользователь не найден.
+
+        Raises:
+            Exception: Если произошла ошибка при чтении файла.
+        """
         try:
             if not os.path.exists(self.file_path):
                 logger.info(
@@ -117,7 +170,14 @@ class JsonStorage:
             )
             raise
 
-    def verify_password(self, plain_password: str,
-                        hashed_password: str) -> bool:
-        """Проверяет пароль"""
-        return self.pwd_context.verify(plain_password, hashed_password)
+    def verify_password(self, plain_password: str, hashed_password: str) -> bool:
+        """Проверяет соответствие введённого пароля хэшированному.
+
+        Args:
+            plain_password (str): Введённый пользователем пароль.
+            hashed_password (str): Хэшированный пароль из хранилища.
+
+        Returns:
+            bool: True, если пароль верен, False в противном случае.
+        """
+        return self.pwd_context.verify(plain_password, hashed_password)