From 326e27543a856dc3fd5fd6c4b339813e6c3389e0 Mon Sep 17 00:00:00 2001 From: Guilherme Costa Date: Fri, 28 Aug 2026 09:27:09 +0100 Subject: [PATCH] docs(network): add module docstrings and compress comment style --- BlocksScreen/lib/network/manager.py | 26 +++++++++++++----------- BlocksScreen/lib/network/models.py | 6 +++--- BlocksScreen/lib/network/worker.py | 2 ++ BlocksScreen/lib/panels/networkWindow.py | 2 ++ 4 files changed, 21 insertions(+), 15 deletions(-) diff --git a/BlocksScreen/lib/network/manager.py b/BlocksScreen/lib/network/manager.py index 1ef6cd82..08b2af58 100644 --- a/BlocksScreen/lib/network/manager.py +++ b/BlocksScreen/lib/network/manager.py @@ -1,3 +1,5 @@ +"""Qt-facing NetworkManager facade: owns the worker thread and its signals.""" + # pylint: disable=protected-access import asyncio @@ -17,7 +19,7 @@ logger = logging.getLogger(__name__) -_KEEPALIVE_POLL_MS: int = 300_000 # 5 minutes — safety net for missed signals +_KEEPALIVE_POLL_MS: int = 300_000 # 5 minutes: safety net for missed signals class NetworkManager(QObject): @@ -27,9 +29,9 @@ class NetworkManager(QObject): a ``NetworkManagerWorker`` that runs all D-Bus coroutines on its dedicated asyncio thread. - Coroutines are submitted to ``worker._asyncio_loop`` — the same loop - on which the D-Bus file-descriptor was registered — so signal delivery - and async I/O always occur on the correct selector. + Coroutines are submitted to ``worker._asyncio_loop`` (the same loop the + D-Bus file-descriptor was registered on), so signal delivery and async + I/O always occur on the correct selector. """ @@ -72,7 +74,7 @@ def __init__(self, parent: QObject | None = None) -> None: self._worker.reconnect_complete.connect(self.reconnect_complete) self._worker.initialized.connect(self._on_worker_initialized) - # Keepalive timer — safety net for any missed D-Bus signals. + # Keepalive timer: safety net for any missed D-Bus signals. self._keepalive_timer = QTimer(self) self._keepalive_timer.setInterval(_KEEPALIVE_POLL_MS) self._keepalive_timer.timeout.connect(self._on_keepalive_tick) @@ -96,7 +98,7 @@ def _schedule(self, coro: "asyncio.Coroutine") -> None: future.add_done_callback(self._pending_futures.discard) else: logger.debug( - "Dropping early coroutine — loop not yet running: %s", + "Dropping early coroutine, loop not yet running: %s", coro.__qualname__, ) coro.close() @@ -114,7 +116,7 @@ def _on_worker_initialized(self) -> None: return self._worker_ready = True logger.info( - "Worker initialised — starting keepalive (every %d ms)", + "Worker initialised: starting keepalive (every %d ms)", _KEEPALIVE_POLL_MS, ) self._keepalive_timer.start() @@ -185,7 +187,7 @@ def _on_hotspot_info_ready(self, ssid: str, password: str, security: str) -> Non @pyqtSlot() def _on_keepalive_tick(self) -> None: - """Safety-net refresh — runs every 5 min to catch any missed signals.""" + """Safety-net refresh: runs every 5 min to catch any missed signals.""" if self._shutting_down: return self._schedule(self._worker._async_get_current_state()) @@ -273,7 +275,7 @@ def update_hotspot_config( new_password: str, security: str = "wpa-psk", ) -> None: - """Change hotspot name/password/security — cleans up old profiles.""" + """Change hotspot name/password/security: cleans up old profiles.""" self._schedule( self._worker._async_update_hotspot_config( old_ssid, new_ssid, new_password, security @@ -346,17 +348,17 @@ def saved_networks(self) -> list[SavedNetwork]: @property def hotspot_ssid(self) -> str: - """Hotspot SSID — read from main-thread cache (thread-safe).""" + """Hotspot SSID: read from main-thread cache (thread-safe).""" return self._cached_hotspot_ssid @property def hotspot_password(self) -> str: - """Hotspot password — read from main-thread cache (thread-safe).""" + """Hotspot password: read from main-thread cache (thread-safe).""" return self._cached_hotspot_password @property def hotspot_security(self) -> str: - """Hotspot security type — always 'wpa-psk' (WPA2-PSK, thread-safe).""" + """Hotspot security type: always 'wpa-psk' (WPA2-PSK, thread-safe).""" return self._cached_hotspot_security def get_network_info(self, ssid: str) -> NetworkInfo | None: diff --git a/BlocksScreen/lib/network/models.py b/BlocksScreen/lib/network/models.py index 6b5f68d5..acf9c79a 100644 --- a/BlocksScreen/lib/network/models.py +++ b/BlocksScreen/lib/network/models.py @@ -82,8 +82,8 @@ class NetworkStatus(IntEnum): ``NetworkInfo.is_open`` (derived from ``security_type``) instead. """ - DISCOVERED = 0 # Seen in scan, not saved — protected security - OPEN = 1 # Seen in scan, not saved — open (no passphrase) + DISCOVERED = 0 # Seen in scan, not saved: protected security + OPEN = 1 # Seen in scan, not saved: open (no passphrase) SAVED = 2 # Profile saved on this device ACTIVE = 3 # Currently connected HIDDEN = 4 # Hidden-network placeholder @@ -287,7 +287,7 @@ class HotspotSecurity(str, Enum): """ WPA1 = "wpa1" - WPA2_PSK = "wpa-psk" # WPA2-PSK (CCMP) — default + WPA2_PSK = "wpa-psk" # WPA2-PSK (CCMP): default @classmethod def is_valid(cls, value: str) -> bool: diff --git a/BlocksScreen/lib/network/worker.py b/BlocksScreen/lib/network/worker.py index a1e971ae..9a32a251 100644 --- a/BlocksScreen/lib/network/worker.py +++ b/BlocksScreen/lib/network/worker.py @@ -1,3 +1,5 @@ +"""Async D-Bus NetworkManager worker: signal watching, link control, state snapshots.""" + import asyncio import fcntl import ipaddress diff --git a/BlocksScreen/lib/panels/networkWindow.py b/BlocksScreen/lib/panels/networkWindow.py index 09e2649f..7e5b44ff 100644 --- a/BlocksScreen/lib/panels/networkWindow.py +++ b/BlocksScreen/lib/panels/networkWindow.py @@ -1,3 +1,5 @@ +"""Network settings UI: Wi-Fi, ethernet and hotspot panels backed by the NM manager.""" + import fcntl import ipaddress as _ipaddress import logging