Покрытие кода docstrings

SRV/services/arp_service.py

@@ -1,3 +1,22 @@
+"""
+Сервис низкоуровневого ARP-сканирования локальной сети.
+
+Назначение:
+- Обнаружение активных узлов в пределах сетей хоста путём широковещательных
+  ARP‑запросов от имени выбранного интерфейса.
+- Помощь сервисам более высокого уровня (например, IPService) при проверке
+  занятости адресов перед применением конфигураций.
+
+Особенности реализации:
+- Определяет подключённые сети интерфейса через `netifaces` и строит CIDR для
+  сканирования.
+- Формирует ARP‑пакеты с помощью `scapy` (Ether/ARP) и отправляет их с таймаутом.
+- Добавляет локальный адрес интерфейса в результирующий список клиентов.
+
+Требования/ограничения:
+- Для отправки ARP‑кадров могут потребоваться повышенные привилегии или
+  capability на сырой сокет.
+"""
 from fastapi import Depends
 from scapy.layers.l2 import ARP, Ether
 from scapy.sendrecv import srp

SRV/services/connect_service.py

@@ -1,3 +1,19 @@
+"""
+Сервис управления подключениями Wi‑Fi через `nmcli`.
+
+Назначение:
+- Предоставляет операции подключения/отключения к точкам доступа и проверки
+  текущего статуса, ориентируясь на системный NetworkManager.
+
+Поведение:
+- Автоматически определяет активный Wi‑Fi‑интерфейс.
+- Валидирует наличие SSID в листинге перед подключением и интерпретирует
+  частые ошибки `nmcli` (неверный пароль, отсутствующая сеть и т.п.).
+
+Ограничения:
+- Требуются права для управления сетевыми соединениями в системе.
+- В окружениях без NetworkManager команды `nmcli` будут недоступны.
+"""
 import subprocess
 import logging
 from typing import Tuple, Optional

SRV/services/firewalld_service.py

@@ -1,3 +1,16 @@
+"""
+Сервис для управления firewalld через D‑Bus.
+
+Назначение:
+- Обёртка над интерфейсами `org.fedoraproject.FirewallD1` для выполнения
+  типовых операций по зонам: просмотр/изменение дефолтной зоны, добавление и
+  удаление сервисов, портов, источников, перезагрузка конфигурации.
+
+Примечания:
+- Используется `pydbus.SystemBus` для доступа к системной шине.
+- Методы генерируют дружелюбные исключения при ошибках, содержащие контекст
+  операции.
+"""
 from re import DEBUG
 from typing import Dict, List, Optional
 

SRV/services/ip_service.py

@@ -1,3 +1,17 @@
+"""
+Сервис проверки и применения IP‑настроек через NetworkManager (D‑Bus).
+
+Назначение:
+- Перед применением конфигурации проверяет занятость IP адреса, сканируя сегмент
+  сети средствами ARP (через `NetworkScanner`).
+- Применяет изменения профиля подключения через `sdbus_async.networkmanager` и
+  выполняет переподключение интерфейса.
+
+Требования/ограничения:
+- Доступ к системной шине D‑Bus и права на изменения сетевых профилей.
+- Структура входных данных должна соответствовать схеме `ipv4_updates` для
+  корректного обновления вложенных полей у профиля.
+"""
 from typing import Dict, Any
 from sdbus_async.networkmanager import (
     NetworkManager,

SRV/services/network_service.py

@@ -1,3 +1,16 @@
+"""
+Сервис чтения сетевого состояния через NetworkManager (D‑Bus).
+
+Назначение:
+- Предоставляет асинхронные методы для сборки унифицированных моделей
+  сетевых интерфейсов (Ethernet/Wi‑Fi), их IP‑конфигураций, а также получения
+  имени хоста. Используется API‑слоем для визуализации и управления.
+
+Особенности:
+- Фильтрация loopback и явно неактивных интерфейсов.
+- Адаптация данных D‑Bus в pydantic‑модели (`NetworkInterface`, `WiFiDevice`,
+  `NetworkInterfacesContainer`).
+"""
 from typing import List, Dict, Tuple, Union, Optional
 from sdbus_async.networkmanager import (
     NetworkManager,

SRV/services/subnet_service.py

@@ -44,7 +44,20 @@ def get_subnet_service(translations: Translations = Depends(get_translations()))
 class NetworkScanner:
     """Класс для сканирования подсети с использованием ARP-запросов.
 
-    Выполняет отправку ARP-запросов для обнаружения устройств в указанной подсети.
+    Назначение:
+        Обнаруживает активные устройства в локальной сети, отправляя широковещательные
+        ARP‑запросы по указанной подсети и собирая ответы (IP, MAC).
+
+    Детали реализации:
+        - Использует `scapy` (`Ether` + `ARP`) для генерации пакетов и `srp` для
+          отправки/получения на канальном уровне от имени заданного интерфейса.
+        - Таймаут ожидания ответа короткий (2 секунды), ориентирован на интерактивные
+          сценарии UI.
+
+    Ограничения и замечания:
+        - Требуются права для отправки низкоуровневых пакетов (capabilities/root).
+        - В сетях с фильтрацией широковещания количество обнаруженных устройств
+          может быть ограничено.
     """
     def __init__(self, interface: str, translations: Translations):
         """Инициализирует сканер сети.
@@ -74,6 +87,10 @@ class NetworkScanner:
         Raises:
             Exception: Если произошла ошибка сканирования.
         """
+        try:
+            arp = ARP(pdst=subnet)
+        except Exception as e:
+            logger.error(f"Error checking status: {str(e)}")
         try:
             arp = ARP(pdst=subnet)
             ether = Ether(dst="ff:ff:ff:ff:ff:ff")
@@ -87,7 +104,14 @@ class NetworkScanner:
 class PortScanner:
     """Класс для сканирования открытых портов на устройствах.
 
-    Предоставляет функциональность для проверки доступности портов, пока не реализована.
+    Назначение:
+        Плейсхолдер для будущего функционала активного сканирования TCP/UDP‑портов
+        у обнаруженных узлов. В текущей версии возвращает пустой список.
+
+    План развития:
+        - Добавить неблокирующее сканирование наиболее распространённых портов
+          (22, 80, 443 и т.д.) с ограничением по времени.
+        - Настраиваемые профили глубины и скорости сканирования.
     """
     def __init__(self, interface: str, translations: Translations):
         """Инициализирует сканер портов.
@@ -117,7 +141,15 @@ class PortScanner:
 class DeviceInfoCollector:
     """Класс для сбора информации об устройствах, включая вендоров и хостнеймы.
 
-    Использует внешние сервисы (MacLookup, NBTSCAN, DNS) для получения данных.
+    Источники данных:
+        - MacLookup: сопоставление префикса MAC (OUI) с названием производителя.
+        - DNS: `gethostbyaddr` с малым таймаутом для обратного разрешения имени.
+        - NetBIOS (nbtscan): опрос сегмента сети для извлечения NetBIOS‑имён.
+
+    Политика кэширования:
+        - Результаты `get_vendor` кэшируются с помощью `functools.lru_cache`.
+        - Результаты `nbtscan` аккумулируются в словарях `nbtscan_cache`/`nbtscan_results`
+          на время жизни экземпляра.
     """
     def __init__(self, translations: Translations):
         """Инициализирует коллектор информации об устройствах.
@@ -213,7 +245,15 @@ class DeviceInfoCollector:
 class DeviceStorage:
     """Класс для хранения и управления данными об устройствах.
 
-    Обеспечивает загрузку и сохранение данных в JSON-файлы.
+    Формат файла подсети:
+        JSON‑структура вида
+        {
+          "devices": [Device, ...]
+        }
+
+    Политика очистки:
+        - Метод `_clean_old_devices` удаляет оффлайн‑устройства, не наблюдавшиеся
+          более 7 дней, чтобы поддерживать актуальность списка.
     """
     def __init__(self, base_path: str = "storage/subnets", translations: Translations = None):
         """Инициализирует хранилище устройств.
@@ -331,7 +371,19 @@ class DeviceStorage:
 class SubnetService:
     """Сервис для сканирования подсетей и управления устройствами.
 
-    Объединяет функциональность сканирования, сбора информации и хранения данных.
+    Роль сервиса:
+        Объединяет сетевое сканирование (ARP), сбор дополнительной информации
+        (вендор, хостнейм), слияние с кэшем предыдущих результатов и персистентное
+        хранение данных по подсетям. Предоставляет вспомогательные операции для
+        локального узла и работы с заметками устройств.
+
+    Поток выполнения скана (`scan_subnet`):
+        1) Определение подсети (вручную или авто по интерфейсу).
+        2) Загрузка ранее сохранённых устройств подсети.
+        3) Добавление локального устройства (если принадлежит подсети).
+        4) ARP‑сканирование и параллельная обработка узлов (обогащение данных).
+        5) Маркировка оффлайн‑узлов из кэша, не встреченных в текущем скане.
+        6) Сортировка по IP и сохранение объединённого списка в JSON.
     """
     def __init__(self, translations: Translations):
         """Инициализирует сервис подсети.

SRV/services/ufw_service.py

@@ -8,9 +8,16 @@ DEBUG = True
 
 
 class UFWService:
-    """
-    Сервис для взаимодействия с утилитой UFW (Uncomplicated Firewall) в Linux.
-    Позволяет получить список правил UFW и управлять ими.
+    """Сервис взаимодействия с UFW (Uncomplicated Firewall).
+
+    Назначение:
+        - Чтение статуса и списка правил брандмауэра.
+        - Добавление, удаление и массовая обработка правил с поддержкой диапазонов портов,
+          комментариев и выбором протоколов.
+
+    Детали реализации:
+        - Команды выполняются через `sudo ufw ...`; вывод парсится в модели pydantic.
+        - Для операций удаления соблюдается порядок с конца, чтобы не нарушать нумерацию.
     """
 
     def _run_command(self, command: str) -> str:

SRV/services/wifi_service.py

@@ -21,7 +21,17 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 class WifiStorage:
-    """Класс для хранения данных о Wi-Fi сетях и их заметках по SSID."""
+    """Класс для хранения данных о Wi‑Fi сетях и их заметках по SSID.
+
+    Формат:
+        {
+          "networks": [{"ssid": str, "note": Optional[str]}]
+        }
+
+    Поведение:
+        - Создаёт директорию хранения при инициализации, ведёт логирование путей.
+        - Валидация структуры при чтении, безопасная запись с Unicode и отступами.
+    """
     def __init__(self, storage_path: str = "storage/wifi/wifi.json", translations: Translations = Depends(get_translations())):
         self.storage_file = Path(storage_path)
         self.storage_file.parent.mkdir(parents=True, exist_ok=True)
@@ -61,7 +71,18 @@ class WifiStorage:
             raise Exception(self.translations.gettext("Ошибка при сохранении заметок: {error}").format(error=str(e)))
 
 class WifiService:
-    """Сервис для сканирования текущих Wi-Fi точек доступа."""
+    """Сервис для сканирования текущих Wi‑Fi точек доступа и заметок.
+
+    Источники данных:
+        - `pywifi` для базового сканирования и получения списка AP.
+        - `iw dev <iface> scan` для уточнения частоты, сигнала и безопасности.
+        - `MacLookup` для определения вендора по BSSID.
+
+    Политики:
+        - Выбор лучшего AP по SSID по уровню сигнала.
+        - Кэширование определения вендора.
+        - Сохранение SSID даже без заметок для будущих операций.
+    """
     def __init__(self, translations: Translations = Depends(get_translations())):
         self.mac_lookup = MacLookup()
         self.wifi = pywifi.PyWiFi()