pylib/fstools
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
fstools/_docs_/index.html

624 lines
38 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Welcome to cachings’s documentation! &#8212; fstools documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/classic.css?v=67a6116b" />
<link rel="stylesheet" type="text/css" href="_static/pydoctheme.css?v=5ff89526" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="_static/pygments_dark.css?v=5349f25f" />
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /><link rel="stylesheet" href="_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="_static/py.svg">
<script type="text/javascript" src="_static/copybutton.js"></script>
<script type="text/javascript" src="_static/menu.js"></script>
<script type="text/javascript" src="_static/search-focus.js"></script>
<script type="text/javascript" src="_static/themetoggle.js"></script>
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="#">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Welcome to cachings’s documentation!</a><ul>
<li><a class="reference internal" href="#fstools-filesystem-tools">fstools (Filesystem Tools)</a></li>
<li><a class="reference internal" href="#fstools.dirlist"><code class="docutils literal notranslate"><span class="pre">dirlist()</span></code></a></li>
<li><a class="reference internal" href="#fstools.filelist"><code class="docutils literal notranslate"><span class="pre">filelist()</span></code></a></li>
<li><a class="reference internal" href="#fstools.is_writeable"><code class="docutils literal notranslate"><span class="pre">is_writeable()</span></code></a></li>
<li><a class="reference internal" href="#fstools.mkdir"><code class="docutils literal notranslate"><span class="pre">mkdir()</span></code></a></li>
<li><a class="reference internal" href="#fstools.open_locked_blocking"><code class="docutils literal notranslate"><span class="pre">open_locked_blocking()</span></code></a></li>
<li><a class="reference internal" href="#fstools.open_locked_non_blocking"><code class="docutils literal notranslate"><span class="pre">open_locked_non_blocking()</span></code></a></li>
<li><a class="reference internal" href="#fstools.uid"><code class="docutils literal notranslate"><span class="pre">uid()</span></code></a></li>
<li><a class="reference internal" href="#fstools.uid_filelist"><code class="docutils literal notranslate"><span class="pre">uid_filelist()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/index.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li><img src="_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
<a href="#">fstools documentation</a> &#187;
</li>
<li class="nav-item nav-item-this"><a href="">Welcome to cachings’s documentation!</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-fstools">
<span id="welcome-to-cachings-s-documentation"></span><h1>Welcome to cachings’s documentation!<a class="headerlink" href="#module-fstools" title="Link to this heading"></a></h1>
<section id="fstools-filesystem-tools">
<h2>fstools (Filesystem Tools)<a class="headerlink" href="#fstools-filesystem-tools" title="Link to this heading"></a></h2>
<p><strong>Author:</strong></p>
<ul class="simple">
<li><p>Dirk Alders &lt;<a class="reference external" href="mailto:sudo-dirk&#37;&#52;&#48;mount-mockery&#46;de">sudo-dirk<span>&#64;</span>mount-mockery<span>&#46;</span>de</a>&gt;</p></li>
</ul>
<p><strong>Description:</strong></p>
<blockquote>
<div><p>This module supports functions and classes to handle files and paths</p>
</div></blockquote>
<p><strong>Submodules:</strong></p>
<ul class="simple">
<li><p><a class="reference internal" href="#fstools.dirlist" title="fstools.dirlist"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstools.dirlist()</span></code></a></p></li>
<li><p><a class="reference internal" href="#fstools.filelist" title="fstools.filelist"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstools.filelist()</span></code></a></p></li>
<li><p><a class="reference internal" href="#fstools.is_writeable" title="fstools.is_writeable"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstools.is_writeable()</span></code></a></p></li>
<li><p><a class="reference internal" href="#fstools.mkdir" title="fstools.mkdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstools.mkdir()</span></code></a></p></li>
<li><p><a class="reference internal" href="#fstools.open_locked_blocking" title="fstools.open_locked_blocking"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstools.open_locked_blocking()</span></code></a></p></li>
<li><p><a class="reference internal" href="#fstools.open_locked_non_blocking" title="fstools.open_locked_non_blocking"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstools.open_locked_non_blocking()</span></code></a></p></li>
<li><p><a class="reference internal" href="#fstools.uid" title="fstools.uid"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstools.uid()</span></code></a></p></li>
</ul>
<p><strong>Unittest:</strong></p>
<blockquote>
<div><p>See also the <a class="reference download internal" download="" href="_downloads/c68c8cb37d326ff4fa7a0781182bc493/unittest.pdf"><code class="xref download docutils literal notranslate"><span class="pre">unittest</span></code></a> documentation.</p>
</div></blockquote>
<p><strong>Module Documentation:</strong></p>
</section>
<dl class="py function">
<dt class="sig sig-object py" id="fstools.dirlist">
<span class="sig-prename descclassname"><span class="pre">fstools.</span></span><span class="sig-name descname"><span class="pre">dirlist</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">expression</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'*'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rekursive</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#fstools.dirlist" title="Link to this definition"></a></dt>
<dd><p>Function returning a list of directories below a given path.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> (<em>str</em>) – folder which is the basepath for searching files.</p></li>
<li><p><strong>expression</strong> (<em>str</em>) – expression to fit including shell-style wildcards. It is only used for the first directory level, if rekursive is set to True.</p></li>
<li><p><strong>rekursive</strong> (<em>bool</em>) – search all subfolders if True.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>list of filenames including the pathe</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>list</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The returned filenames could be relative pathes depending on argument path.</p>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
<span class="c1"># -*- coding: UTF-8 -*-</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;../..&#39;</span><span class="p">)</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">fstools</span>
<span class="k">for</span> <span class="n">dirname</span> <span class="ow">in</span> <span class="n">fstools</span><span class="o">.</span><span class="n">dirlist</span><span class="p">(</span><span class="n">path</span><span class="o">=</span><span class="s1">&#39;..&#39;</span><span class="p">,</span> <span class="n">rekursive</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="n">dirname</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">../</span><span class="n">_examples_</span>
<span class="o">../</span><span class="n">__pycache__</span>
<span class="o">../</span><span class="n">_docs_</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_sources</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_static</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_static</span><span class="o">/</span><span class="n">css</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_static</span><span class="o">/</span><span class="n">css</span><span class="o">/</span><span class="n">fonts</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_static</span><span class="o">/</span><span class="n">js</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_static</span><span class="o">/</span><span class="n">fonts</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_static</span><span class="o">/</span><span class="n">fonts</span><span class="o">/</span><span class="n">RobotoSlab</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_static</span><span class="o">/</span><span class="n">fonts</span><span class="o">/</span><span class="n">Lato</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_downloads</span>
<span class="o">../</span><span class="n">_docs_</span><span class="o">/</span><span class="n">_downloads</span><span class="o">/</span><span class="mi">7</span><span class="n">bf10188aa659556c284b4a8298dba8d</span>
<span class="o">../</span><span class="n">_testresults_</span>
</pre></div>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="fstools.filelist">
<span class="sig-prename descclassname"><span class="pre">fstools.</span></span><span class="sig-name descname"><span class="pre">filelist</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">expression</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'*'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rekursive</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#fstools.filelist" title="Link to this definition"></a></dt>
<dd><p>Function returning a list of files below a given path.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> (<em>str</em>) – folder which is the basepath for searching files.</p></li>
<li><p><strong>expression</strong> (<em>str</em>) – expression to fit including shell-style wildcards.</p></li>
<li><p><strong>rekursive</strong> (<em>bool</em>) – search all subfolders if True.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>list of filenames including the pathe</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>list</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The returned filenames could be relative pathes depending on argument path.</p>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
<span class="c1"># -*- coding: UTF-8 -*-</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;../..&#39;</span><span class="p">)</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">fstools</span>
<span class="k">for</span> <span class="n">filename</span> <span class="ow">in</span> <span class="n">fstools</span><span class="o">.</span><span class="n">filelist</span><span class="p">(</span><span class="n">path</span><span class="o">=</span><span class="s1">&#39;..&#39;</span><span class="p">,</span> <span class="n">expression</span><span class="o">=</span><span class="s1">&#39;*.py&#39;</span><span class="p">,</span> <span class="n">rekursive</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">../</span><span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="o">../</span><span class="n">_examples_</span><span class="o">/</span><span class="n">dirlist</span><span class="o">.</span><span class="n">py</span>
<span class="o">../</span><span class="n">_examples_</span><span class="o">/</span><span class="n">uid</span><span class="o">.</span><span class="n">py</span>
<span class="o">../</span><span class="n">_examples_</span><span class="o">/</span><span class="n">uid_filelist</span><span class="o">.</span><span class="n">py</span>
<span class="o">../</span><span class="n">_examples_</span><span class="o">/</span><span class="n">filelist</span><span class="o">.</span><span class="n">py</span>
<span class="o">../</span><span class="n">_examples_</span><span class="o">/</span><span class="n">is_writeable</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="fstools.is_writeable">
<span class="sig-prename descclassname"><span class="pre">fstools.</span></span><span class="sig-name descname"><span class="pre">is_writeable</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#fstools.is_writeable" title="Link to this definition"></a></dt>
<dd><p>Method to get the Information, if a file or folder is writable.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>path</strong> (<em>str</em>) – file or folder to check.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Whether path is writable or not.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>bool</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If path does not exist, the return Value is <code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code>.</p>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
<span class="c1"># -*- coding: UTF-8 -*-</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;../..&#39;</span><span class="p">)</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">fstools</span>
<span class="nb">print</span><span class="p">(</span><span class="n">fstools</span><span class="o">.</span><span class="n">is_writeable</span><span class="p">(</span><span class="s1">&#39;..&#39;</span><span class="p">))</span>
<span class="nb">print</span><span class="p">(</span><span class="n">fstools</span><span class="o">.</span><span class="n">is_writeable</span><span class="p">(</span><span class="s1">&#39;../__init__.py&#39;</span><span class="p">))</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kc">True</span>
<span class="kc">True</span>
</pre></div>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="fstools.mkdir">
<span class="sig-prename descclassname"><span class="pre">fstools.</span></span><span class="sig-name descname"><span class="pre">mkdir</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#fstools.mkdir" title="Link to this definition"></a></dt>
<dd><p>Method to create a folder.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>All needed subfoilders will also be created (rekursive mkdir).</p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>path</strong> (<em>str</em>) – folder to be created.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True, if folder exists after creation commands, otherwise False.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>bool</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="fstools.open_locked_blocking">
<span class="sig-prename descclassname"><span class="pre">fstools.</span></span><span class="sig-name descname"><span class="pre">open_locked_blocking</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#fstools.open_locked_blocking" title="Link to this definition"></a></dt>
<dd><p>Method to get exclusive access to a file.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>args</strong> – Arguments for a standard file open call.</p></li>
<li><p><strong>kwargs</strong> – Keyword arguments for a standard file open call.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A file descriptor.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>file handle</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The call blocks until file is able to be used. This can cause a deadlock, if the file release es done after trying to open the file!</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="fstools.open_locked_non_blocking">
<span class="sig-prename descclassname"><span class="pre">fstools.</span></span><span class="sig-name descname"><span class="pre">open_locked_non_blocking</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#fstools.open_locked_non_blocking" title="Link to this definition"></a></dt>
<dd><p>Method to get exclusive access to a file.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>args</strong> – Arguments for a standard file open call.</p></li>
<li><p><strong>kwargs</strong> – Keyword arguments for a standard file open call.</p></li>
</ul>
</dd>
<dt class="field-even">Raises<span class="colon">:</span></dt>
<dd class="field-even"><p>OSError, if the file is already blocked.</p>
</dd>
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>A file descriptor.</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>file handle</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The call blocks until file is able to be used. This can cause a deadlock, if the file release es done after trying to open the file!</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="fstools.uid">
<span class="sig-prename descclassname"><span class="pre">fstools.</span></span><span class="sig-name descname"><span class="pre">uid</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_staleness</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">3600</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#fstools.uid" title="Link to this definition"></a></dt>
<dd><p>Function returning a “unique” id for a given file or path.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> (<em>str</em>) – File or folder to generate a uid for.</p></li>
<li><p><strong>max_staleness</strong> (<em>int</em>) – If a file or folder is older than that, we may consider
it stale and return a different uid - this is a
dirty trick to work around changes never being
detected. Default is 3600 seconds, use None to
disable this trickery. See below for more details.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>An object that changes value if the file changed,
None is returned if there were problems accessing the file
or folder.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Depending on the operating system capabilities and the way the
file update is done, this function might return the same value
even if the file has changed. It should be better than just
using file’s mtime though.
max_staleness tries to avoid the worst for these cases.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If this function is used for a path, it will stat all pathes and files rekursively.</p>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
<span class="c1"># -*- coding: UTF-8 -*-</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;../..&#39;</span><span class="p">)</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">fstools</span>
<span class="nb">print</span><span class="p">(</span><span class="n">fstools</span><span class="o">.</span><span class="n">uid</span><span class="p">(</span><span class="s1">&#39;../__init__.py&#39;</span><span class="p">))</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">2</span><span class="n">de37f8d3569d049e82932f8293c402d59e8bda8</span>
</pre></div>
</div>
<p>Using just the file’s mtime to determine if the file has changed is
not reliable - if file updates happen faster than the file system’s
mtime granularity, then the modification is not detectable because
the mtime is still the same.</p>
<p>This function tries to improve by using not only the mtime, but also
other metadata values like file size and inode to improve reliability.</p>
<p>For the calculation of this value, we of course only want to use data
that we can get rather fast, thus we use file metadata, not file data
(file content).</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="fstools.uid_filelist">
<span class="sig-prename descclassname"><span class="pre">fstools.</span></span><span class="sig-name descname"><span class="pre">uid_filelist</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">expression</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'*'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rekursive</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#fstools.uid_filelist" title="Link to this definition"></a></dt>
<dd><p>Function returning a unique id for a given file or path.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> (<em>str</em>) – folder which is the basepath for searching files.</p></li>
<li><p><strong>expression</strong> (<em>str</em>) – expression to fit including shell-style wildcards.</p></li>
<li><p><strong>rekursive</strong> (<em>bool</em>) – search all subfolders if True.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>An object that changes value if one of the files change.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This UID is created out of the file content. Therefore it is more
reliable then <a class="reference internal" href="#fstools.uid" title="fstools.uid"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstools.uid()</span></code></a>, but also much slower.</p>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
<span class="c1"># -*- coding: UTF-8 -*-</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;../..&#39;</span><span class="p">)</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">fstools</span>
<span class="nb">print</span><span class="p">(</span><span class="n">fstools</span><span class="o">.</span><span class="n">uid_filelist</span><span class="p">(</span><span class="s1">&#39;..&#39;</span><span class="p">,</span> <span class="s1">&#39;*.py&#39;</span><span class="p">,</span> <span class="n">rekursive</span><span class="o">=</span><span class="kc">True</span><span class="p">))</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">92</span><span class="n">a26594015be798c2a5b438595067e9</span>
</pre></div>
</div>
</dd></dl>
<div class="toctree-wrapper compound">
</div>
</section>
<section id="indices-and-tables">
<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Link to this heading"></a></h1>
<ul class="simple">
<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li>
<li><p><a class="reference internal" href="py-modindex.html"><span class="std std-ref">Module Index</span></a></p></li>
<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li>
</ul>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="#">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Welcome to cachings’s documentation!</a><ul>
<li><a class="reference internal" href="#fstools-filesystem-tools">fstools (Filesystem Tools)</a></li>
<li><a class="reference internal" href="#fstools.dirlist"><code class="docutils literal notranslate"><span class="pre">dirlist()</span></code></a></li>
<li><a class="reference internal" href="#fstools.filelist"><code class="docutils literal notranslate"><span class="pre">filelist()</span></code></a></li>
<li><a class="reference internal" href="#fstools.is_writeable"><code class="docutils literal notranslate"><span class="pre">is_writeable()</span></code></a></li>
<li><a class="reference internal" href="#fstools.mkdir"><code class="docutils literal notranslate"><span class="pre">mkdir()</span></code></a></li>
<li><a class="reference internal" href="#fstools.open_locked_blocking"><code class="docutils literal notranslate"><span class="pre">open_locked_blocking()</span></code></a></li>
<li><a class="reference internal" href="#fstools.open_locked_non_blocking"><code class="docutils literal notranslate"><span class="pre">open_locked_non_blocking()</span></code></a></li>
<li><a class="reference internal" href="#fstools.uid"><code class="docutils literal notranslate"><span class="pre">uid()</span></code></a></li>
<li><a class="reference internal" href="#fstools.uid_filelist"><code class="docutils literal notranslate"><span class="pre">uid_filelist()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/index.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li><img src="_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
<a href="#">fstools documentation</a> &#187;
</li>
<li class="nav-item nav-item-this"><a href="">Welcome to cachings’s documentation!</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy;
Copyright
2025, Dirk Alders.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink