Update documentation

Author: github-actions[bot]

main/.doctrees/developers_guide/api.doctree

@@ -129,9 +129,9 @@ <h1>Source code for mache.permissions</h1><div class="highlight"><pre>
 <span class="sd">    &quot;&quot;&quot;</span>
 
     <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">base_paths</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>
-        <span class="n">directories</span> <span class="o">=</span> <span class="p">[</span><span class="n">base_paths</span><span class="p">]</span>
+        <span class="n">paths</span> <span class="o">=</span> <span class="p">[</span><span class="n">Path</span><span class="p">(</span><span class="n">base_paths</span><span class="p">)]</span>
     <span class="k">else</span><span class="p">:</span>
-        <span class="n">directories</span> <span class="o">=</span> <span class="n">base_paths</span>
+        <span class="n">paths</span> <span class="o">=</span> <span class="p">[</span><span class="n">Path</span><span class="p">(</span><span class="n">path</span><span class="p">)</span> <span class="k">for</span> <span class="n">path</span> <span class="ow">in</span> <span class="n">base_paths</span><span class="p">]</span>
 
     <span class="n">new_uid</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getuid</span><span class="p">()</span>
     <span class="n">new_gid</span> <span class="o">=</span> <span class="n">grp</span><span class="o">.</span><span class="n">getgrnam</span><span class="p">(</span><span class="n">group</span><span class="p">)</span><span class="o">.</span><span class="n">gr_gid</span>
@@ -154,33 +154,25 @@ <h1>Source code for mache.permissions</h1><div class="highlight"><pre>
 
     <span class="n">mask</span> <span class="o">=</span> <span class="n">stat</span><span class="o">.</span><span class="n">S_IRWXU</span> <span class="o">|</span> <span class="n">stat</span><span class="o">.</span><span class="n">S_IRWXG</span> <span class="o">|</span> <span class="n">stat</span><span class="o">.</span><span class="n">S_IRWXO</span>
 
-    <span class="c1"># first the base directories that don&#39;t seem to be included in</span>
-    <span class="c1"># os.walk()</span>
-    <span class="k">for</span> <span class="n">directory</span> <span class="ow">in</span> <span class="n">directories</span><span class="p">:</span>
-        <span class="k">try</span><span class="p">:</span>
-            <span class="n">dir_stat</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="n">directory</span><span class="p">)</span>
-        <span class="k">except</span> <span class="ne">OSError</span><span class="p">:</span>
-            <span class="k">continue</span>
-
-        <span class="n">perm</span> <span class="o">=</span> <span class="n">dir_stat</span><span class="o">.</span><span class="n">st_mode</span> <span class="o">&amp;</span> <span class="n">mask</span>
-
-        <span class="k">if</span> <span class="p">(</span>
-            <span class="n">perm</span> <span class="o">==</span> <span class="n">exec_perm</span>
-            <span class="ow">and</span> <span class="n">dir_stat</span><span class="o">.</span><span class="n">st_uid</span> <span class="o">==</span> <span class="n">new_uid</span>
-            <span class="ow">and</span> <span class="n">dir_stat</span><span class="o">.</span><span class="n">st_gid</span> <span class="o">==</span> <span class="n">new_gid</span>
-        <span class="p">):</span>
-            <span class="k">pass</span>
+    <span class="k">for</span> <span class="n">path</span> <span class="ow">in</span> <span class="n">paths</span><span class="p">:</span>
+        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Updating file permissions for: </span><span class="si">{</span><span class="n">path</span><span class="si">}</span><span class="s1">&#39;</span><span class="p">)</span>
 
-        <span class="k">try</span><span class="p">:</span>
-            <span class="n">os</span><span class="o">.</span><span class="n">chown</span><span class="p">(</span><span class="n">directory</span><span class="p">,</span> <span class="n">new_uid</span><span class="p">,</span> <span class="n">new_gid</span><span class="p">)</span>
-            <span class="n">os</span><span class="o">.</span><span class="n">chmod</span><span class="p">(</span><span class="n">directory</span><span class="p">,</span> <span class="n">exec_perm</span><span class="p">)</span>
-        <span class="k">except</span> <span class="ne">OSError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
-            <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s1"> – skipping </span><span class="si">{</span><span class="n">directory</span><span class="si">}</span><span class="s1">&#39;</span><span class="p">)</span>
+        <span class="c1"># start by updating the top level path (file or directory)</span>
+        <span class="n">_update</span><span class="p">(</span>
+            <span class="n">path</span><span class="p">,</span>
+            <span class="n">uid</span><span class="o">=</span><span class="n">new_uid</span><span class="p">,</span>
+            <span class="n">gid</span><span class="o">=</span><span class="n">new_gid</span><span class="p">,</span>
+            <span class="n">read_write_perm</span><span class="o">=</span><span class="n">read_write_perm</span><span class="p">,</span>
+            <span class="n">exec_perm</span><span class="o">=</span><span class="n">exec_perm</span><span class="p">,</span>
+            <span class="n">mask</span><span class="o">=</span><span class="n">mask</span><span class="p">,</span>
+        <span class="p">)</span>
 
-        <span class="n">paths_iter</span> <span class="o">=</span> <span class="p">(</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">Path</span><span class="p">(</span><span class="n">directory</span><span class="p">)</span><span class="o">.</span><span class="n">rglob</span><span class="p">(</span><span class="s1">&#39;*&#39;</span><span class="p">))</span>
-        <span class="n">n_files</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="mi">1</span> <span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="n">Path</span><span class="p">(</span><span class="n">directory</span><span class="p">)</span><span class="o">.</span><span class="n">rglob</span><span class="p">(</span><span class="s1">&#39;*&#39;</span><span class="p">))</span>
+        <span class="c1"># iterate over the path recursively, only if it&#39;s a direcotry</span>
+        <span class="k">if</span> <span class="n">path</span><span class="o">.</span><span class="n">is_file</span><span class="p">():</span>
+            <span class="k">continue</span>
 
-        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Updating file permissions for: </span><span class="si">{</span><span class="n">directory</span><span class="si">}</span><span class="s1">&#39;</span><span class="p">)</span>
+        <span class="n">paths_iter</span> <span class="o">=</span> <span class="p">(</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">Path</span><span class="p">(</span><span class="n">path</span><span class="p">)</span><span class="o">.</span><span class="n">rglob</span><span class="p">(</span><span class="s1">&#39;*&#39;</span><span class="p">))</span>
+        <span class="n">n_files</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="mi">1</span> <span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="n">Path</span><span class="p">(</span><span class="n">path</span><span class="p">)</span><span class="o">.</span><span class="n">rglob</span><span class="p">(</span><span class="s1">&#39;*&#39;</span><span class="p">))</span>
 
         <span class="k">with</span> <span class="p">(</span>
             <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="n">workers</span><span class="p">)</span> <span class="k">as</span> <span class="n">pool</span><span class="p">,</span>