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

2025-06-23 12:47:05 +05:00 · 2025-06-23 12:47:05 +05:00 · 37f9e3abfb
commit 37f9e3abfb
parent 060f4de175
14 changed files with 1234 additions and 243 deletions
--- a/SRV/api/v1/auth.py
+++ b/SRV/api/v1/auth.py
@ -1,4 +1,3 @@
-# api/v1/auth.py
 from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.security import OAuth2PasswordBearer
 from services.auth_service import AuthService
@ -17,7 +16,21 @@ oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/login")

@router.post("/register", response_model=UserResponse)
 async def register(user: UserCreate):
-    """Регистрирует нового пользователя"""
+    """Регистрирует нового пользователя.
+
+    Создаёт нового пользователя на основе предоставленных данных и возвращает
+    информацию о зарегистрированном пользователе.
+
+    Args:
+        user (UserCreate): Объект с данными нового пользователя (username, password, is_admin).
+
+    Returns:
+        UserResponse: Объект с данными зарегистрированного пользователя (id, username, is_admin).
+
+    Raises:
+        HTTPException: Если пользователь уже существует (status_code=400) или произошла
+            внутренняя ошибка (status_code=500).
+    """
    try:
        db_user = auth_service.register(user)
        logger.info(f"Пользователь {user.username} успешно зарегистрирован")
@ -26,13 +39,27 @@ async def register(user: UserCreate):
        raise e
    except Exception as e:
        logger.error(f"Ошибка в register: {type(e).__name__} - {str(e)}")
-        raise HTTPException(status_code=500,
-                            detail="Не удалось зарегистрировать пользователя")
+        raise HTTPException(status_code=500, detail="Не удалось зарегистрировать пользователя")


@router.post("/login", response_model=Token)
 async def login(user: UserLogin, request: Request):
-    """Авторизует пользователя и создаёт сессию"""
+    """Авторизует пользователя и создаёт сессию.
+
+    Проверяет учетные данные пользователя и возвращает токен и session_id для
+    последующей авторизации.
+
+    Args:
+        user (UserLogin): Объект с данными для входа (username, password).
+        request (Request): Объект запроса для получения client_id (IP-адрес клиента).
+
+    Returns:
+        Token: Объект с access_token и session_id для авторизации.
+
+    Raises:
+        HTTPException: Если учетные данные неверны (status_code=401) или произошла
+            внутренняя ошибка (status_code=500).
+    """
    try:
        client_id = request.client.host
        logger.debug(f"Попытка авторизации для client_id {client_id}")
@ -45,13 +72,27 @@ async def login(user: UserLogin, request: Request):
        raise e
    except Exception as e:
        logger.error(f"Ошибка в login: {type(e).__name__} - {str(e)}")
-        raise HTTPException(status_code=500,
-                            detail="Не удалось авторизовать пользователя")
+        raise HTTPException(status_code=500, detail="Не удалось авторизовать пользователя")


@router.get("/me")
 async def get_current_user(request: Request):
-    """Возвращает данные текущего пользователя и токен"""
+    """Возвращает данные текущего пользователя и токен.
+
+    Проверяет активную сессию по client_id и возвращает информацию о пользователе
+    и токен для дальнейшего использования.
+
+    Args:
+        request (Request): Объект запроса для получения client_id (IP-адрес клиента).
+
+    Returns:
+        dict: Словарь с ключами "user" (UserResponse), "access_token" (str) и
+            "token_type" (str, всегда "bearer").
+
+    Raises:
+        HTTPException: Если сессия не найдена или истекла (status_code=401) или
+            произошла внутренняя ошибка (status_code=500).
+    """
    try:
        client_id = request.client.host
        logger.debug(f"Запрос /me для client_id {client_id}")
@ -66,13 +107,25 @@ async def get_current_user(request: Request):
    except Exception as e:
        logger.error(
            f"Ошибка в get_current_user: {type(e).__name__} - {str(e)}")
-        raise HTTPException(status_code=500,
-                            detail="Не удалось получить данные пользователя")
+        raise HTTPException(status_code=500, detail="Не удалось получить данные пользователя")


@router.get("/logout")
 async def logout(request: Request):
-    """Выход из системы, удаление сессии"""
+    """Выход из системы, удаление сессии.
+
+    Удаляет активную сессию пользователя по client_id.
+
+    Args:
+        request (Request): Объект запроса для получения client_id (IP-адрес клиента).
+
+    Returns:
+        dict: Пустой словарь или сообщение об успешном выходе.
+
+    Raises:
+        HTTPException: Если сессия не найдена (status_code=401) или произошла
+            внутренняя ошибка (status_code=500).
+    """
    try:
        client_id = request.client.host
        logger.debug(f"Запрос logout для client_id {client_id}")
@ -81,13 +134,24 @@ async def logout(request: Request):
        raise e
    except Exception as e:
        logger.error(f"Ошибка в logout: {type(e).__name__} - {str(e)}")
-        raise HTTPException(status_code=500,
-                            detail="Не удалось выйти из системы")
+        raise HTTPException(status_code=500, detail="Не удалось выйти из системы")


@router.get("/check_json")
 async def check_users_file():
-    """Проверяет, существует ли файл users.json и содержит ли он пользователей"""
+    """Проверяет, существует ли файл users.json и содержит ли он пользователей.
+
+    Возвращает информацию о состоянии файла и наличии пользователей.
+
+    Returns:
+        dict: Словарь с ключами:
+            - "exists" (bool): Существует ли файл.
+            - "has_users" (bool): Содержит ли файл пользователей.
+            - "message" (str): Сообщение с описанием результата.
+
+    Raises:
+        HTTPException: Если произошла ошибка при проверке файла (status_code=500).
+    """
    try:
        file_path = "/etc/gonets/users.json"
        storage = JsonStorage(file_path=file_path)
@ -104,27 +168,24 @@ async def check_users_file():
        has_users = len(data.get("users", [])) > 0
        if has_users:
            logger.info(
-                f"Файл {file_path} существует и содержит пользователей")
+                f"Файл {file_path} существует и содержит пользователей"
+            )
            return {
                "exists": True,
                "has_users": True,
-                "message":
-                "Файл users.json существует и содержит пользователей",
+                "message": "Файл users.json существует и содержит пользователей",
            }
        else:
            logger.info(
-                f"Файл {file_path} существует, но не содержит пользователей")
+                f"Файл {file_path} существует, но не содержит пользователей"
+            )
            return {
-                "exists":
-                True,
-                "has_users":
-                False,
-                "message":
-                "Файл users.json существует, но не содержит пользователей",
+                "exists": True,
+                "has_users": False,
+                "message": "Файл users.json существует, но не содержит пользователей",
            }
    except Exception as e:
        logger.error(
            f"Ошибка при проверке файла users.json: {type(e).__name__} - {str(e)}"
        )
-        raise HTTPException(status_code=500,
-                            detail="Ошибка при проверке файла")
+        raise HTTPException(status_code=500, detail="Ошибка при проверке файла")