Утилита для упрощения генерации доков

SRV/docs/_build/html/_modules/api/v1/subnet.html

@@ -589,7 +589,7 @@
 <span class="sd">        HTTPException: Если подключение не удалось (status_code=400).</span>
 <span class="sd">    &quot;&quot;&quot;</span>
     <span class="k">try</span><span class="p">:</span>
-        <span class="n">wifi_service</span> <span class="o">=</span> <span class="n">WifiConnectionService</span><span class="p">()</span>
+        <span class="n">wifi_service</span> <span class="o">=</span> <span class="n">WifiConnectionService</span><span class="p">(</span><span class="n">translations</span><span class="p">)</span>
         <span class="n">success</span><span class="p">,</span> <span class="n">message</span> <span class="o">=</span> <span class="n">wifi_service</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">ssid</span><span class="p">,</span> <span class="n">request</span><span class="o">.</span><span class="n">password</span><span class="p">)</span>
         <span class="k">if</span> <span class="ow">not</span> <span class="n">success</span><span class="p">:</span>
             <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="n">message</span><span class="p">))</span>
@@ -619,7 +619,7 @@
 <span class="sd">        HTTPException: Если отключение не удалось (status_code=400).</span>
 <span class="sd">    &quot;&quot;&quot;</span>
     <span class="k">try</span><span class="p">:</span>
-        <span class="n">wifi_service</span> <span class="o">=</span> <span class="n">WifiConnectionService</span><span class="p">()</span>
+        <span class="n">wifi_service</span> <span class="o">=</span> <span class="n">WifiConnectionService</span><span class="p">(</span><span class="n">translations</span><span class="p">)</span>
         <span class="n">success</span><span class="p">,</span> <span class="n">message</span> <span class="o">=</span> <span class="n">wifi_service</span><span class="o">.</span><span class="n">disconnect</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">ssid</span><span class="p">)</span>
         <span class="k">if</span> <span class="ow">not</span> <span class="n">success</span><span class="p">:</span>
             <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="n">message</span><span class="p">))</span>
@@ -650,7 +650,7 @@
 <span class="sd">        HTTPException: Если проверка статуса не удалась (status_code=400).</span>
 <span class="sd">    &quot;&quot;&quot;</span>
     <span class="k">try</span><span class="p">:</span>
-        <span class="n">wifi_service</span> <span class="o">=</span> <span class="n">WifiConnectionService</span><span class="p">()</span>
+        <span class="n">wifi_service</span> <span class="o">=</span> <span class="n">WifiConnectionService</span><span class="p">(</span><span class="n">translations</span><span class="p">)</span>
         <span class="n">success</span><span class="p">,</span> <span class="n">message</span> <span class="o">=</span> <span class="n">wifi_service</span><span class="o">.</span><span class="n">get_status</span><span class="p">()</span>
         <span class="k">if</span> <span class="ow">not</span> <span class="n">success</span><span class="p">:</span>
             <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="n">message</span><span class="p">))</span>

SRV/docs/_build/html/_modules/services/arp_service.html

@@ -301,6 +301,8 @@
 <span class="kn">from</span><span class="w"> </span><span class="nn">utils.i18n</span><span class="w"> </span><span class="kn">import</span> <span class="n">get_translations</span><span class="p">,</span> <span class="n">_</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">babel.support</span><span class="w"> </span><span class="kn">import</span> <span class="n">Translations</span>
 
+<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>
+
 <span class="k">try</span><span class="p">:</span>
     <span class="kn">from</span><span class="w"> </span><span class="nn">scapy.layers.l2</span><span class="w"> </span><span class="kn">import</span> <span class="n">ARP</span><span class="p">,</span> <span class="n">Ether</span>
     <span class="kn">from</span><span class="w"> </span><span class="nn">scapy.sendrecv</span><span class="w"> </span><span class="kn">import</span> <span class="n">srp</span>
@@ -332,35 +334,57 @@
 
 <span class="sd">        Инициализирует интерфейс, информацию об IP-адресах и локальный MAC-адрес.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
-        <span class="k">try</span><span class="p">:</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">translations</span> <span class="o">=</span> <span class="n">translations</span>
-            <span class="k">if</span> <span class="n">interface</span><span class="p">:</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">interface</span> <span class="o">=</span> <span class="kc">None</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">interface</span> <span class="o">=</span> <span class="n">interface</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span> <span class="o">=</span> <span class="p">[]</span>
-            <span class="k">else</span><span class="p">:</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">networks</span> <span class="o">=</span> <span class="p">[]</span>
-                <span class="n">default_gateway</span> <span class="o">=</span> <span class="n">netifaces</span><span class="o">.</span><span class="n">gateways</span><span class="p">()</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;default&quot;</span><span class="p">,</span> <span class="p">{})</span><span class="o">.</span><span class="n">get</span><span class="p">(</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">local_mac</span> <span class="o">=</span> <span class="kc">None</span>
-                    <span class="n">netifaces</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">)</span>
-                <span class="k">if</span> <span class="n">default_gateway</span><span class="p">:</span>
-                    <span class="bp">self</span><span class="o">.</span><span class="n">interface</span> <span class="o">=</span> <span class="n">default_gateway</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
-                <span class="k">else</span><span class="p">:</span>
-                    <span class="k">raise</span> <span class="ne">KeyError</span><span class="p">(</span><span class="s2">&quot;Default gateway not found&quot;</span><span class="p">)</span>
 
-            <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span> <span class="o">=</span> <span class="n">netifaces</span><span class="o">.</span><span class="n">ifaddresses</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">interface</span><span class="p">)</span><span class="o">.</span><span class="n">get</span><span class="p">(</span>
+        <span class="k">try</span><span class="p">:</span>
-                <span class="n">netifaces</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">,</span> <span class="p">[])</span>
+            <span class="n">candidate_interface</span> <span class="o">=</span> <span class="n">interface</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">networks</span> <span class="o">=</span> <span class="p">[</span>
+            <span class="k">if</span> <span class="ow">not</span> <span class="n">candidate_interface</span><span class="p">:</span>
-                <span class="n">IPNetwork</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">ip</span><span class="p">[</span><span class="s1">&#39;addr&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">/</span><span class="si">{</span><span class="n">ip</span><span class="p">[</span><span class="s1">&#39;netmask&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span> <span class="k">for</span> <span class="n">ip</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span>
+                <span class="n">gateways</span> <span class="o">=</span> <span class="n">netifaces</span><span class="o">.</span><span class="n">gateways</span><span class="p">()</span>
-            <span class="p">]</span>
+                <span class="n">default_gateway</span> <span class="o">=</span> <span class="n">gateways</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;default&quot;</span><span class="p">,</span> <span class="p">{})</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">netifaces</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">)</span>
-            <span class="bp">self</span><span class="o">.</span><span class="n">local_mac</span> <span class="o">=</span> <span class="n">netifaces</span><span class="o">.</span><span class="n">ifaddresses</span><span class="p">(</span>
+                <span class="k">if</span> <span class="n">default_gateway</span><span class="p">:</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">interface</span><span class="p">)[</span><span class="n">netifaces</span><span class="o">.</span><span class="n">AF_LINK</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s2">&quot;addr&quot;</span><span class="p">]</span>
+                    <span class="n">candidate_interface</span> <span class="o">=</span> <span class="n">default_gateway</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
+                <span class="k">else</span><span class="p">:</span>
+                    <span class="k">for</span> <span class="n">iface</span> <span class="ow">in</span> <span class="n">netifaces</span><span class="o">.</span><span class="n">interfaces</span><span class="p">():</span>
+                        <span class="k">if</span> <span class="n">iface</span> <span class="o">==</span> <span class="s2">&quot;lo&quot;</span><span class="p">:</span>
+                            <span class="k">continue</span>
+                        <span class="n">addrs</span> <span class="o">=</span> <span class="n">netifaces</span><span class="o">.</span><span class="n">ifaddresses</span><span class="p">(</span><span class="n">iface</span><span class="p">)</span>
+                        <span class="k">if</span> <span class="n">netifaces</span><span class="o">.</span><span class="n">AF_INET</span> <span class="ow">in</span> <span class="n">addrs</span> <span class="ow">and</span> <span class="n">addrs</span><span class="p">[</span><span class="n">netifaces</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">]:</span>
+                            <span class="n">candidate_interface</span> <span class="o">=</span> <span class="n">iface</span>
+                            <span class="k">break</span>
+
+            <span class="k">if</span> <span class="n">candidate_interface</span><span class="p">:</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">interface</span> <span class="o">=</span> <span class="n">candidate_interface</span>
+                <span class="n">addresses</span> <span class="o">=</span> <span class="n">netifaces</span><span class="o">.</span><span class="n">ifaddresses</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">interface</span><span class="p">)</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span> <span class="o">=</span> <span class="n">addresses</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">netifaces</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">,</span> <span class="p">[])</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">networks</span> <span class="o">=</span> <span class="p">[</span>
+                    <span class="n">IPNetwork</span><span class="p">(</span>
+                        <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">ip</span><span class="p">[</span><span class="s1">&#39;addr&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">/</span><span class="si">{</span><span class="n">ip</span><span class="p">[</span><span class="s1">&#39;netmask&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span>
+                    <span class="p">)</span> <span class="k">for</span> <span class="n">ip</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span> <span class="k">if</span> <span class="n">ip</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;addr&quot;</span><span class="p">)</span> <span class="ow">and</span> <span class="n">ip</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;netmask&quot;</span><span class="p">)</span>
+                <span class="p">]</span>
+                <span class="n">link_info</span> <span class="o">=</span> <span class="n">addresses</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">netifaces</span><span class="o">.</span><span class="n">AF_LINK</span><span class="p">,</span> <span class="p">[])</span>
+                <span class="k">if</span> <span class="n">link_info</span><span class="p">:</span>
+                    <span class="bp">self</span><span class="o">.</span><span class="n">local_mac</span> <span class="o">=</span> <span class="n">link_info</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;addr&quot;</span><span class="p">)</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span>
+                    <span class="s2">&quot;NetworkScanner: IPv4 интерфейс не найден, сканирование будет недоступно&quot;</span>
+                <span class="p">)</span>
         <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
             <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&quot;SPHINX_BUILD&quot;</span><span class="p">):</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">interface</span> <span class="o">=</span> <span class="n">interface</span> <span class="ow">or</span> <span class="s2">&quot;eth0&quot;</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span> <span class="o">=</span> <span class="p">[]</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">networks</span> <span class="o">=</span> <span class="p">[]</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">local_mac</span> <span class="o">=</span> <span class="s2">&quot;00:00:00:00:00:00&quot;</span>
-                <span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span>
-                <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s2">&quot;NetworkScanner falling back to mocked interface during documentation build: </span><span class="si">%s</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">exc</span><span class="p">)</span>
+                    <span class="s2">&quot;NetworkScanner falling back to mocked interface during documentation build: </span><span class="si">%s</span><span class="s2">&quot;</span><span class="p">,</span>
+                    <span class="n">exc</span><span class="p">,</span>
+                <span class="p">)</span>
             <span class="k">else</span><span class="p">:</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s2">&quot;NetworkScanner инициализация завершилась ошибкой: </span><span class="si">%s</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">exc</span><span class="p">)</span>
                 <span class="k">raise</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">translations</span> <span class="o">=</span> <span class="n">translations</span>
 
     <span class="k">def</span><span class="w"> </span><span class="nf">_create_arp_packet</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">target_ip</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;Создаёт ARP-пакет для отправки на указанный IP-адрес.</span>
@@ -393,6 +417,16 @@
 <span class="sd">        Note:</span>
 <span class="sd">            Учитывает локальные IP-адреса интерфейса и удаляет дубликаты.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">interface</span> <span class="ow">or</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">networks</span> <span class="ow">or</span> <span class="n">ARP</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="n">Ether</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="n">fallback_clients</span> <span class="o">=</span> <span class="p">[]</span>
+            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span><span class="p">:</span>
+                <span class="k">for</span> <span class="n">ip_info</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span><span class="p">:</span>
+                    <span class="n">fallback_clients</span><span class="o">.</span><span class="n">append</span><span class="p">({</span>
+                        <span class="s2">&quot;ip&quot;</span><span class="p">:</span> <span class="n">ip_info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;addr&quot;</span><span class="p">),</span>
+                        <span class="s2">&quot;mac&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">local_mac</span><span class="p">,</span>
+                    <span class="p">})</span>
+            <span class="k">return</span> <span class="p">[</span><span class="n">client</span> <span class="k">for</span> <span class="n">client</span> <span class="ow">in</span> <span class="n">fallback_clients</span> <span class="k">if</span> <span class="n">client</span><span class="p">[</span><span class="s2">&quot;ip&quot;</span><span class="p">]]</span>
+
         <span class="n">all_clients</span> <span class="o">=</span> <span class="p">[]</span>
 
         <span class="k">for</span> <span class="n">network</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">networks</span><span class="p">:</span>
@@ -413,7 +447,12 @@
             <span class="n">all_clients</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">clients</span><span class="p">)</span>
 
         <span class="k">for</span> <span class="n">ip_info</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">ip_info</span><span class="p">:</span>
-            <span class="n">local_client</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;ip&quot;</span><span class="p">:</span> <span class="n">ip_info</span><span class="p">[</span><span class="s2">&quot;addr&quot;</span><span class="p">],</span> <span class="s2">&quot;mac&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">local_mac</span><span class="p">}</span>
+            <span class="k">if</span> <span class="ow">not</span> <span class="n">ip_info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;addr&quot;</span><span class="p">):</span>
+                <span class="k">continue</span>
+            <span class="n">local_client</span> <span class="o">=</span> <span class="p">{</span>
+                <span class="s2">&quot;ip&quot;</span><span class="p">:</span> <span class="n">ip_info</span><span class="p">[</span><span class="s2">&quot;addr&quot;</span><span class="p">],</span>
+                <span class="s2">&quot;mac&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">local_mac</span><span class="p">,</span>
+            <span class="p">}</span>
             <span class="k">if</span> <span class="n">local_client</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">all_clients</span><span class="p">:</span>
                 <span class="n">all_clients</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">local_client</span><span class="p">)</span>
 

SRV/docs/_build/html/_modules/services/connect_service.html

@@ -310,13 +310,19 @@
 <span class="sd">    Предоставляет методы для подключения, отключения и проверки статуса Wi-Fi соединений.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
-    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">translations</span><span class="p">:</span> <span class="n">Translations</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_translations</span><span class="p">())):</span>
+    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">translations</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Translations</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;Инициализирует сервис Wi-Fi.</span>
 
 <span class="sd">        Автоматически определяет доступный Wi-Fi-интерфейс и сохраняет его имя.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">interface</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_wifi_interface</span><span class="p">()</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">translations</span> <span class="o">=</span> <span class="n">translations</span>
+        <span class="k">if</span> <span class="n">translations</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="k">try</span><span class="p">:</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">translations</span> <span class="o">=</span> <span class="n">Translations</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="s2">&quot;locales&quot;</span><span class="p">,</span> <span class="p">[</span><span class="s2">&quot;ru&quot;</span><span class="p">],</span> <span class="s2">&quot;messages&quot;</span><span class="p">)</span>
+            <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">translations</span> <span class="o">=</span> <span class="n">Translations</span><span class="p">()</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">translations</span> <span class="o">=</span> <span class="n">translations</span>
 
     <span class="k">def</span><span class="w"> </span><span class="nf">_get_wifi_interface</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;Автоматически определяет Wi-Fi-интерфейс.</span>
@@ -329,17 +335,27 @@
 <span class="sd">            Exception: Если произошла ошибка при выполнении команд nmcli.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">try</span><span class="p">:</span>
-            <span class="n">result</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">([</span><span class="s2">&quot;nmcli&quot;</span><span class="p">,</span> <span class="s2">&quot;radio&quot;</span><span class="p">,</span> <span class="s2">&quot;wifi&quot;</span><span class="p">],</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+            <span class="n">result</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
-            <span class="k">if</span> <span class="s2">&quot;enabled&quot;</span> <span class="ow">in</span> <span class="n">result</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">lower</span><span class="p">():</span>
+                <span class="p">[</span><span class="s2">&quot;nmcli&quot;</span><span class="p">,</span> <span class="s2">&quot;radio&quot;</span><span class="p">,</span> <span class="s2">&quot;wifi&quot;</span><span class="p">],</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="kc">True</span>
-                <span class="n">interfaces</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">([</span><span class="s2">&quot;nmcli&quot;</span><span class="p">,</span> <span class="s2">&quot;device&quot;</span><span class="p">,</span> <span class="s2">&quot;status&quot;</span><span class="p">],</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span><span class="n">stdout</span>
+            <span class="p">)</span>
-                <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">interfaces</span><span class="o">.</span><span class="n">splitlines</span><span class="p">():</span>
+            <span class="k">if</span> <span class="s2">&quot;enabled&quot;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">result</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">lower</span><span class="p">():</span>
-                    <span class="k">if</span> <span class="s2">&quot;wifi&quot;</span> <span class="ow">in</span> <span class="n">line</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="ow">and</span> <span class="s2">&quot;connected&quot;</span> <span class="ow">in</span> <span class="n">line</span><span class="o">.</span><span class="n">lower</span><span class="p">():</span>
+                <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s2">&quot;Wi-Fi radio is disabled&quot;</span><span class="p">)</span>
-                        <span class="n">iface</span> <span class="o">=</span> <span class="n">line</span><span class="o">.</span><span class="n">split</span><span class="p">()[</span><span class="mi">0</span><span class="p">]</span>
+                <span class="k">return</span> <span class="s2">&quot;&quot;</span>
-                        <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Using Wi-Fi interface: </span><span class="si">{</span><span class="n">iface</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+
-                        <span class="k">return</span> <span class="n">iface</span>
+            <span class="n">interfaces_output</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
-                <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s2">&quot;Wi-Fi interface not found or not connected&quot;</span><span class="p">)</span>
+                <span class="p">[</span><span class="s2">&quot;nmcli&quot;</span><span class="p">,</span> <span class="s2">&quot;device&quot;</span><span class="p">,</span> <span class="s2">&quot;status&quot;</span><span class="p">],</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="kc">True</span>
-                <span class="k">return</span> <span class="s2">&quot;wlan0&quot;</span>
+            <span class="p">)</span><span class="o">.</span><span class="n">stdout</span>
-            <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s2">&quot;Wi-Fi radio is disabled&quot;</span><span class="p">)</span>
+
+            <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">interfaces_output</span><span class="o">.</span><span class="n">splitlines</span><span class="p">():</span>
+                <span class="n">parts</span> <span class="o">=</span> <span class="n">line</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
+                <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">parts</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">2</span><span class="p">:</span>
+                    <span class="k">continue</span>
+                <span class="n">device_name</span><span class="p">,</span> <span class="n">device_type</span> <span class="o">=</span> <span class="n">parts</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">parts</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
+                <span class="k">if</span> <span class="n">device_type</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">==</span> <span class="s2">&quot;wifi&quot;</span><span class="p">:</span>
+                    <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Using Wi-Fi interface: </span><span class="si">{</span><span class="n">device_name</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+                    <span class="k">return</span> <span class="n">device_name</span>
+
+            <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s2">&quot;Wi-Fi interface not found in `nmcli device status` output&quot;</span><span class="p">)</span>
             <span class="k">return</span> <span class="s2">&quot;&quot;</span>
         <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
             <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Error detecting Wi-Fi interface: </span><span class="si">{</span><span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
@@ -367,20 +383,64 @@
             <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">interface</span><span class="p">:</span>
                 <span class="k">return</span> <span class="kc">False</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="s2">&quot;Wi-Fi-интерфейс не доступен&quot;</span><span class="p">)</span>
 
-            <span class="n">result</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">([</span><span class="s2">&quot;nmcli&quot;</span><span class="p">,</span> <span class="s2">&quot;-f&quot;</span><span class="p">,</span> <span class="s2">&quot;SSID&quot;</span><span class="p">,</span> <span class="s2">&quot;device&quot;</span><span class="p">,</span> <span class="s2">&quot;wifi&quot;</span><span class="p">,</span> <span class="s2">&quot;list&quot;</span><span class="p">],</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+            <span class="n">result</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
+                <span class="p">[</span><span class="s2">&quot;nmcli&quot;</span><span class="p">,</span> <span class="s2">&quot;-f&quot;</span><span class="p">,</span> <span class="s2">&quot;SSID&quot;</span><span class="p">,</span> <span class="s2">&quot;device&quot;</span><span class="p">,</span> <span class="s2">&quot;wifi&quot;</span><span class="p">,</span> <span class="s2">&quot;list&quot;</span><span class="p">],</span>
+                <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
+                <span class="n">text</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
+            <span class="p">)</span>
             <span class="k">if</span> <span class="n">ssid</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">result</span><span class="o">.</span><span class="n">stdout</span><span class="p">:</span>
                 <span class="k">return</span> <span class="kc">False</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="s2">&quot;Сеть с SSID </span><span class="si">{ssid}</span><span class="s2"> не найдена в списке доступных сетей&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">ssid</span><span class="o">=</span><span class="n">ssid</span><span class="p">)</span>
 
-            <span class="n">cmd</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;nmcli&quot;</span><span class="p">,</span> <span class="s2">&quot;device&quot;</span><span class="p">,</span> <span class="s2">&quot;wifi&quot;</span><span class="p">,</span> <span class="s2">&quot;connect&quot;</span><span class="p">,</span> <span class="n">ssid</span><span class="p">,</span> <span class="s2">&quot;password&quot;</span><span class="p">,</span> <span class="n">password</span><span class="p">]</span>
+            <span class="k">def</span><span class="w"> </span><span class="nf">run_connect</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">CompletedProcess</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
-            <span class="n">process</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">check</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
+                <span class="n">cmd</span> <span class="o">=</span> <span class="p">[</span>
+                    <span class="s2">&quot;nmcli&quot;</span><span class="p">,</span>
+                    <span class="s2">&quot;device&quot;</span><span class="p">,</span>
+                    <span class="s2">&quot;wifi&quot;</span><span class="p">,</span>
+                    <span class="s2">&quot;connect&quot;</span><span class="p">,</span>
+                    <span class="n">ssid</span><span class="p">,</span>
+                    <span class="s2">&quot;ifname&quot;</span><span class="p">,</span>
+                    <span class="bp">self</span><span class="o">.</span><span class="n">interface</span><span class="p">,</span>
+                <span class="p">]</span>
+                <span class="k">if</span> <span class="n">password</span><span class="p">:</span>
+                    <span class="n">cmd</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="s2">&quot;password&quot;</span><span class="p">,</span> <span class="n">password</span><span class="p">])</span>
+                <span class="k">return</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">check</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
+
+            <span class="n">process</span> <span class="o">=</span> <span class="n">run_connect</span><span class="p">()</span>
             <span class="k">if</span> <span class="n">process</span><span class="o">.</span><span class="n">returncode</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">:</span>
                 <span class="n">error_msg</span> <span class="o">=</span> <span class="n">process</span><span class="o">.</span><span class="n">stderr</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
-                <span class="k">if</span> <span class="s2">&quot;secrets were required&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span> <span class="ow">or</span> <span class="s2">&quot;authentication failed&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span> <span class="ow">or</span> <span class="s2">&quot;802-11-wireless-security.psk: недействительное свойство&quot;</span> <span class="ow">in</span> <span class="n">process</span><span class="o">.</span><span class="n">stderr</span><span class="p">:</span>
+                <span class="n">key_mgmt_error</span> <span class="o">=</span> <span class="p">(</span>
-                    <span class="k">return</span> <span class="kc">False</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="s2">&quot;Ошибка подключения к </span><span class="si">{ssid}</span><span class="s2">: Неверный пароль&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">ssid</span><span class="o">=</span><span class="n">ssid</span><span class="p">)</span>
+                    <span class="s2">&quot;secrets were required&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span>
+                    <span class="ow">or</span> <span class="s2">&quot;authentication failed&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span>
+                    <span class="ow">or</span> <span class="s2">&quot;802-11-wireless-security.psk&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span>
+                    <span class="ow">or</span> <span class="s2">&quot;key-mgmt&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span>
+                <span class="p">)</span>
+                <span class="k">if</span> <span class="n">key_mgmt_error</span><span class="p">:</span>
+                    <span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
+                        <span class="p">[</span><span class="s2">&quot;nmcli&quot;</span><span class="p">,</span> <span class="s2">&quot;connection&quot;</span><span class="p">,</span> <span class="s2">&quot;delete&quot;</span><span class="p">,</span> <span class="s2">&quot;id&quot;</span><span class="p">,</span> <span class="n">ssid</span><span class="p">],</span>
+                        <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
+                        <span class="n">text</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
+                    <span class="p">)</span>
+                    <span class="n">retry_process</span> <span class="o">=</span> <span class="n">run_connect</span><span class="p">()</span>
+                    <span class="k">if</span> <span class="n">retry_process</span><span class="o">.</span><span class="n">returncode</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+                        <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Successfully connected to network </span><span class="si">{</span><span class="n">ssid</span><span class="si">}</span><span class="s2"> after profile reset&quot;</span><span class="p">)</span>
+                        <span class="k">return</span> <span class="kc">True</span><span class="p">,</span> <span class="kc">None</span>
+                    <span class="n">error_msg</span> <span class="o">=</span> <span class="n">retry_process</span><span class="o">.</span><span class="n">stderr</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
+                    <span class="k">if</span> <span class="p">(</span>
+                        <span class="s2">&quot;secrets were required&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span>
+                        <span class="ow">or</span> <span class="s2">&quot;authentication failed&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span>
+                        <span class="ow">or</span> <span class="s2">&quot;802-11-wireless-security.psk&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span>
+                        <span class="ow">or</span> <span class="s2">&quot;key-mgmt&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span>
+                    <span class="p">):</span>
+                        <span class="k">return</span> <span class="kc">False</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="s2">&quot;Ошибка подключения к </span><span class="si">{ssid}</span><span class="s2">: Неверный пароль или тип безопасности&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">ssid</span><span class="o">=</span><span class="n">ssid</span><span class="p">)</span>
+                    <span class="k">elif</span> <span class="s2">&quot;no network with ssid&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span><span class="p">:</span>
+                        <span class="k">return</span> <span class="kc">False</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="s2">&quot;Ошибка подключения к </span><span class="si">{ssid}</span><span class="s2">: Сеть с SSID </span><span class="si">{ssid}</span><span class="s2"> недоступна или неверно указана&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">ssid</span><span class="o">=</span><span class="n">ssid</span><span class="p">)</span>
+                    <span class="k">else</span><span class="p">:</span>
+                        <span class="k">return</span> <span class="kc">False</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="s2">&quot;Ошибка подключения к </span><span class="si">{ssid}</span><span class="s2">: </span><span class="si">{error}</span><span class="s2">&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">ssid</span><span class="o">=</span><span class="n">ssid</span><span class="p">,</span> <span class="n">error</span><span class="o">=</span><span class="n">retry_process</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>
                 <span class="k">elif</span> <span class="s2">&quot;no network with ssid&quot;</span> <span class="ow">in</span> <span class="n">error_msg</span><span class="p">:</span>
                     <span class="k">return</span> <span class="kc">False</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="s2">&quot;Ошибка подключения к </span><span class="si">{ssid}</span><span class="s2">: Сеть с SSID </span><span class="si">{ssid}</span><span class="s2"> недоступна или неверно указана&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">ssid</span><span class="o">=</span><span class="n">ssid</span><span class="p">)</span>
                 <span class="k">else</span><span class="p">:</span>
                     <span class="k">return</span> <span class="kc">False</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">translations</span><span class="o">.</span><span class="n">gettext</span><span class="p">(</span><span class="s2">&quot;Ошибка подключения к </span><span class="si">{ssid}</span><span class="s2">: </span><span class="si">{error}</span><span class="s2">&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">ssid</span><span class="o">=</span><span class="n">ssid</span><span class="p">,</span> <span class="n">error</span><span class="o">=</span><span class="n">process</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>
+
             <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Successfully connected to network </span><span class="si">{</span><span class="n">ssid</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
             <span class="k">return</span> <span class="kc">True</span><span class="p">,</span> <span class="kc">None</span>
         <span class="k">except</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">CalledProcessError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>

SRV/docs/_build/html/api/services/connect_service.html

@@ -300,7 +300,7 @@
 </ul>
 <dl class="py class">
 <dt class="sig sig-object py">
-<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">services.connect_service.</span></span><span class="sig-name descname"><span class="pre">WifiConnectionService</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">translations</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Translations</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">Depends(translations_dependency)</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../../_modules/services/connect_service.html#WifiConnectionService"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
+<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">services.connect_service.</span></span><span class="sig-name descname"><span class="pre">WifiConnectionService</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">translations</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Translations</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../../_modules/services/connect_service.html#WifiConnectionService"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
 <dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
 <p>Сервис для управления подключением к Wi-Fi сетям с использованием nmcli.</p>
 <p>Предоставляет методы для подключения, отключения и проверки статуса Wi-Fi соединений.</p>

SRV/docs/_build/markdown/api/services/connect_service.md

@@ -16,7 +16,7 @@
 - Требуются права для управления сетевыми соединениями в системе.
 - В окружениях без NetworkManager команды nmcli будут недоступны.
 
-### *class* services.connect_service.WifiConnectionService(translations: Translations = Depends(translations_dependency))
+### *class* services.connect_service.WifiConnectionService(translations: Translations | None = None)
 
 Bases: `object`
 

SRV/utils/build_docs.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+Утилита для сборки Sphinx-документации проекта GONETS.
+
+Позволяет из корня каталога `SRV/` одним запуском пересобрать HTML и Markdown
+версии документации. Пример использования:
+
+    poetry run python utils/build_docs.py
+
+По умолчанию собираются оба билда (`html` и `markdown`). Повторные вызовы
+перезаписывают существующий вывод Sphinx.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Iterable, List
+
+from sphinx.cmd.build import build_main
+
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+DOCS_DIR = ROOT_DIR / "docs"
+BUILD_ROOT = DOCS_DIR / "_build"
+
+
+def build_docs(builders: Iterable[str]) -> None:
+    """
+    Вызывает Sphinx для каждого указанного билдера.
+
+    Args:
+        builders: последовательность имён билдов Sphinx (например, ["html"]).
+
+    Raises:
+        RuntimeError: если сборка для какого-либо билдера завершилась с ошибкой.
+    """
+    for builder in builders:
+        output_dir = BUILD_ROOT / builder
+        output_dir.parent.mkdir(parents=True, exist_ok=True)
+
+        args: List[str] = [
+            "-b",
+            builder,
+            str(DOCS_DIR),
+            str(output_dir),
+        ]
+        print(f"[build-docs] sphinx-build {' '.join(args)}")
+
+        exit_code = build_main(args)
+        if exit_code != 0:
+            raise RuntimeError(
+                f"Sphinx build failed for builder '{builder}' with exit code {exit_code}"
+            )
+
+
+def parse_args(argv: Iterable[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Сборка документации проекта GONETS (Sphinx)."
+    )
+    parser.add_argument(
+        "-b",
+        "--builder",
+        action="append",
+        choices=("html", "markdown"),
+        help="Ограничить сборку указанными билдерами (по умолчанию html и markdown).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    args = parse_args(argv or sys.argv[1:])
+    builders = args.builder or ["html", "markdown"]
+
+    if not DOCS_DIR.exists():
+        print(f"[build-docs] docs directory not found: {DOCS_DIR}", file=sys.stderr)
+        return 1
+
+    try:
+        build_docs(builders)
+    except RuntimeError as exc:
+        print(f"[build-docs] {exc}", file=sys.stderr)
+        return 1
+
+    print("[build-docs] Documentation build completed successfully")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())