Deploying to gh-pages from @ 631ed3f 🚀

_modules/exasol/bucketfs/_buckets.html

@@ -226,6 +226,7 @@ <h1>Source code for exasol.bucketfs._buckets</h1><div class="highlight"><pre>
     <span class="n">ByteString</span><span class="p">,</span>
     <span class="n">Iterable</span><span class="p">,</span>
     <span class="n">Iterator</span><span class="p">,</span>
+    <span class="n">Protocol</span><span class="p">,</span>
 <span class="p">)</span>
 
 <span class="kn">import</span> <span class="nn">requests</span>
@@ -241,7 +242,88 @@ <h1>Source code for exasol.bucketfs._buckets</h1><div class="highlight"><pre>
 <span class="p">)</span>
 
 
+<span class="k">class</span> <span class="nc">BucketLike</span><span class="p">(</span><span class="n">Protocol</span><span class="p">):</span>
+<span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Definition of the Bucket interface.</span>
+<span class="sd">    It is compatible with both on-premises an SaaS BucketFS systems.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+
+    <span class="nd">@property</span>
+    <span class="k">def</span> <span class="nf">files</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Iterable</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Returns an iterator over the bucket files.</span>
+
+<span class="sd">        A usage example:</span>
+<span class="sd">        print(list(bucket_api.files))</span>
+<span class="sd">        output:</span>
+<span class="sd">        [dir1/subdir1/file1.dat, dir1/subdir2/file2.txt, ....]</span>
+
+<span class="sd">        Note that the paths will look like in the example above, i.e. POSIX style,</span>
+<span class="sd">        no backslash at the start or at the end.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+
+    <span class="k">def</span> <span class="nf">delete</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Deletes a file in the bucket.</span>
+
+<span class="sd">        :param path:    Path of the file to be deleted.</span>
+
+<span class="sd">        Q. What happens if the path doesn&#39;t exist?</span>
+<span class="sd">        A. It does nothing, no error.</span>
+
+<span class="sd">        Q. What happens if the path points to a directory?</span>
+<span class="sd">        A. Same. There are no directories as such in the BucketFS, hence</span>
+<span class="sd">           a directory path is just a non-existent file.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+
+    <span class="k">def</span> <span class="nf">upload</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">data</span><span class="p">:</span> <span class="n">ByteString</span> <span class="o">|</span> <span class="n">BinaryIO</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Uploads a file to the bucket.</span>
+
+<span class="sd">        :param path:    Path in the bucket where the file should be uploaded.</span>
+<span class="sd">        :param data:    Either a binary array or a binary stream, e.g. a file opened in the binary mode.</span>
+
+<span class="sd">        Q. What happens if the parent is missing?</span>
+<span class="sd">        A. The bucket doesn&#39;t care about the structure of the file&#39;s path. Looking from the prospective</span>
+<span class="sd">           of a file system, the bucket will create the missing parent, but in reality it will just</span>
+<span class="sd">           store the data indexed by the provided path.</span>
+
+<span class="sd">        Q. What happens if the path points to an existing file?</span>
+<span class="sd">        A. That&#39;s fine, the file will be updated.</span>
+
+<span class="sd">        Q. What happens if the path points to an existing directory?</span>
+<span class="sd">        A. The bucket doesn&#39;t care about the structure of the file&#39;s path. Looking from the prospective</span>
+<span class="sd">           of a file system, there will exist a file and directory with the same name.</span>
+
+<span class="sd">        Q. How should the path look like?</span>
+<span class="sd">        A. It should look like a POSIX path, but it should not contain any of the NTFS invalid characters.</span>
+<span class="sd">           It can have the leading and/or ending backslashes, which will be subsequently removed.</span>
+<span class="sd">           If the path doesn&#39;t conform to this format an BucketFsError will be raised.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+
+    <span class="k">def</span> <span class="nf">download</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">path</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">chunk_size</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">8192</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">ByteString</span><span class="p">]:</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Downloads a file from the bucket. The content of the file will be provided</span>
+<span class="sd">        in chunks of the specified size. The full content of the file can be constructed using</span>
+<span class="sd">        code similar to the line below.</span>
+<span class="sd">        content = b&#39;&#39;.join(api.download_file(path))</span>
+
+<span class="sd">        :param path:        Path of the file in the bucket that should be downloaded.</span>
+<span class="sd">        :param chunk_size:  Size of the chunks the file content will be delivered in.</span>
+
+<span class="sd">        Q. What happens if the file specified by the path doesn&#39;t exist.</span>
+<span class="sd">        A. BucketFsError will be raised.</span>
+
+<span class="sd">        Q. What happens if the path points to a directory.</span>
+<span class="sd">        A. Same, since a &quot;directory&quot; in the BucketFS is just a non-existent file.</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+
+
 <div class="viewcode-block" id="Bucket"><a class="viewcode-back" href="../../../api.html#exasol.bucketfs.Bucket">[docs]</a><span class="k">class</span> <span class="nc">Bucket</span><span class="p">:</span>
+<span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Implementation of the On-Premises bucket.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+
 <div class="viewcode-block" id="Bucket.__init__"><a class="viewcode-back" href="../../../api.html#exasol.bucketfs.Bucket.__init__">[docs]</a>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span>
         <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>

_sources/changes/unreleased.md.txt

@@ -21,9 +21,11 @@
     logging.basicConfig(level=logging.INFO)
     ```
 
-- Support for viewing BucketFS as a directory
+  - Support for viewing BucketFS as a directory
 
-   Added the Pathlike protocol as described in the [design document](../design/bucketpath.rst).
+    Added the PathLike protocol as described in the [design document](../design/bucketpath.rst).
+    Extracted bucket interface into BucketLike protocol.
+    Implemented PathLike for buckets based on BucketLike protocol.
 
 
 ## Internal

api.html

@@ -268,6 +268,7 @@ <h2>exasol.bucketfs.Bucket<a class="headerlink" href="#exasol-bucketfs-bucket" t
 <dt class="sig sig-object py" id="exasol.bucketfs.Bucket">
 <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">exasol.bucketfs.</span></span><span class="sig-name descname"><span class="pre">Bucket</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">service</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">username</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">password</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">verify</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.12)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/exasol/bucketfs/_buckets.html#Bucket"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#exasol.bucketfs.Bucket" title="Permalink to this definition">#</a></dt>
 <dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.12)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>
+<p>Implementation of the On-Premises bucket.</p>
 <dl class="py method">
 <dt class="sig sig-object py" id="exasol.bucketfs.Bucket.__init__">
 <span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">service</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">username</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">password</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">verify</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.12)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.12)"><span class="pre">str</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/exasol/bucketfs/_buckets.html#Bucket.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#exasol.bucketfs.Bucket.__init__" title="Permalink to this definition">#</a></dt>

changes/unreleased.html

@@ -240,9 +240,13 @@ <h2>Added<a class="headerlink" href="#added" title="Permalink to this heading">#
 <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
 </pre></div>
 </div>
-</li>
+<ul>
 <li><p>Support for viewing BucketFS as a directory</p>
-<p>Added the Pathlike protocol as described in the <a class="reference internal" href="../design/bucketpath.html"><span class="doc std std-doc">design document</span></a>.</p>
+<p>Added the PathLike protocol as described in the <a class="reference internal" href="../design/bucketpath.html"><span class="doc std std-doc">design document</span></a>.
+Extracted bucket interface into BucketLike protocol.
+Implemented PathLike for buckets based on BucketLike protocol.</p>
+</li>
+</ul>
 </li>
 </ul>
 </section>