deploy: 7eab08f

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 59019626143a9c4366e42f081552b287
+config: fbe1c305c728165eeb7e3592d2b10efa
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/api/ds_pycontain.rst.txt

@@ -4,10 +4,10 @@ ds_pycontain code documentation
 Submodules
 ----------
 
-ds_pycontain.hello module
+ds_pycontain.docker_containers module
 ----------------------------------------------------
 
-.. automodule:: ds_pycontain.hello
+.. automodule:: ds_pycontain.docker_containers
    :members:
    :undoc-members:
    :show-inheritance:

_sources/code_documentation.md.txt

@@ -1,16 +1,28 @@
 # Code documentation
 
-```{hint}
+**ds_pycontain** is a python package which provides an abstraction over the docker API.
 
-  To add your code use sphinx tool in project root directory:
+Supported functionality covers:
+- Building docker images from Dockerfiles
+- Pulling docker images from dockerhub (or similar)
+- Running docker containers to execute a one-off command
+- Running docker containers to execute a long-running process and communicate with it
 
-    $ sphinx-apidoc -o docs/api/ src/ds_pycontain
-
-  and add reference from any page which is reachable from the index page.
-```
 
 ```python
-    import ds_pycontain
+  from ds_pycontain import DockerContainer, DockerImage, get_docker_client
+
+  client = get_docker_client()
+
+  # This will fetch the image from dockerhub if it is not already present
+  # with the "latest" tag. Then container is started and commands are run
+  with DockerContainer(DockerImage.from_tag("alpine")) as container:
+      ret_code, output = container.run("touch /animal.txt")
+      assert ret_code == 0
+
+      ret_code, output = container.run("ls /")
+      assert ret_code == 0
+      assert cast(bytes, output).find(b"animal.txt") >= 0
 ```
 
 ```{toctree}

_sources/index.rst.txt

@@ -2,10 +2,19 @@
    You can adapt this file completely to your preferences, but it should at least
    contain the root `toctree` directive.
 
-ds - pycontain
+`deepsense.ai <https://deepsense.ai>`_  - pycontain
 ====================================================================================================================
 
-Documentation for `ds_pycontain` python package.
+Documentation for **ds_pycontain** python package to work with docker containers and images.
+
+Example use case you might consider is to isolate python code execution generated by untrusted LLM by running it in a docker container.
+
+This package makes it a bit easier to:
+
+* Build docker images from Dockerfiles or in-memory string.
+* Pull docker images from dockerhub (or similar).
+* Run docker container to execute a one-off command.
+* Run docker container to execute a long-running process and communicate with it.
 
 
 .. toctree::

_sources/project_overview.md.txt

@@ -1,14 +1,6 @@
 # Project overview
 
-This is introduction to the project.
+The docker API is quite complicated and not well documented or typed.
+This project aims to provide a higher level abstraction over the docker API.
 
-Write here what this project is about, what problems does it solves on high level.
-
-You can also use [mermaid](https://mermaid.js.org/) - read more on [extension page](https://github.com/mgaitan/sphinxcontrib-mermaid):
-
-```{mermaid}
-  graph TD;
-      ds_pycontain --> B;
-      ds_pycontain --> C;
-      B --> D;
-```
+Main motivation is to allow to orchestrate running unsafe code or commands in isolated environment.

api/modules.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>ds_pycontain modules &mdash; pycontain  documentation</title>
+  <title>ds_pycontain modules &mdash; ds_pycontain  documentation</title>
       <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
   <!--[if lt IE 9]>
@@ -33,7 +33,7 @@
 
 
           <a href="../index.html" class="icon icon-home">
-            pycontain
+            ds_pycontain
           </a>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
@@ -63,7 +63,7 @@
 
     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
-          <a href="../index.html">pycontain</a>
+          <a href="../index.html">ds_pycontain</a>
       </nav>
 
       <div class="wy-nav-content">
@@ -88,7 +88,31 @@ <h1>ds_pycontain modules<a class="headerlink" href="#ds-pycontain-modules" title
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="ds_pycontain.html">ds_pycontain code documentation</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="ds_pycontain.html#submodules">Submodules</a></li>
-<li class="toctree-l2"><a class="reference internal" href="ds_pycontain.html#ds-pycontain-hello-module">ds_pycontain.hello module</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ds_pycontain.html#module-ds_pycontain.docker_containers">ds_pycontain.docker_containers module</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer"><code class="docutils literal notranslate"><span class="pre">DockerContainer</span></code></a><ul>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer.__enter__"><code class="docutils literal notranslate"><span class="pre">DockerContainer.__enter__()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer.__exit__"><code class="docutils literal notranslate"><span class="pre">DockerContainer.__exit__()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer.docker_container"><code class="docutils literal notranslate"><span class="pre">DockerContainer.docker_container</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer.name"><code class="docutils literal notranslate"><span class="pre">DockerContainer.name</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer.run"><code class="docutils literal notranslate"><span class="pre">DockerContainer.run()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer.spawn_run"><code class="docutils literal notranslate"><span class="pre">DockerContainer.spawn_run()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer.unsafe_exit"><code class="docutils literal notranslate"><span class="pre">DockerContainer.unsafe_exit()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer.unsafe_start"><code class="docutils literal notranslate"><span class="pre">DockerContainer.unsafe_start()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerImage"><code class="docutils literal notranslate"><span class="pre">DockerImage</span></code></a><ul>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerImage.__repr__"><code class="docutils literal notranslate"><span class="pre">DockerImage.__repr__()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerImage.exists"><code class="docutils literal notranslate"><span class="pre">DockerImage.exists()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerImage.from_dockerfile"><code class="docutils literal notranslate"><span class="pre">DockerImage.from_dockerfile()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerImage.from_dockerfile_content"><code class="docutils literal notranslate"><span class="pre">DockerImage.from_dockerfile_content()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerImage.from_tag"><code class="docutils literal notranslate"><span class="pre">DockerImage.from_tag()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.DockerImage.remove"><code class="docutils literal notranslate"><span class="pre">DockerImage.remove()</span></code></a></li>
+</ul>
+</li>
+<li class="toctree-l3"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.generate_random_container_tag"><code class="docutils literal notranslate"><span class="pre">generate_random_container_tag()</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.docker_containers.get_docker_client"><code class="docutils literal notranslate"><span class="pre">get_docker_client()</span></code></a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="ds_pycontain.html#module-ds_pycontain">Module contents</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.DockerContainer"><code class="docutils literal notranslate"><span class="pre">DockerContainer</span></code></a><ul>
 <li class="toctree-l4"><a class="reference internal" href="ds_pycontain.html#ds_pycontain.DockerContainer.__enter__"><code class="docutils literal notranslate"><span class="pre">DockerContainer.__enter__()</span></code></a></li>
@@ -131,7 +155,7 @@ <h1>ds_pycontain modules<a class="headerlink" href="#ds-pycontain-modules" title
   <hr/>
 
   <div role="contentinfo">
-    <p>&#169; Copyright 2023, ds.</p>
+    <p>&#169; Copyright 2023, deepsense.ai.</p>
   </div>
 
   Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a

code_documentation.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Code documentation &mdash; pycontain  documentation</title>
+  <title>Code documentation &mdash; ds_pycontain  documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
   <!--[if lt IE 9]>
@@ -33,7 +33,7 @@
 
 
           <a href="index.html" class="icon icon-home">
-            pycontain
+            ds_pycontain
           </a>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
@@ -60,7 +60,7 @@
 
     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
-          <a href="index.html">pycontain</a>
+          <a href="index.html">ds_pycontain</a>
       </nav>
 
       <div class="wy-nav-content">
@@ -80,23 +80,41 @@
 
   <section id="code-documentation">
 <h1>Code documentation<a class="headerlink" href="#code-documentation" title="Permalink to this heading"></a></h1>
-<div class="admonition hint">
-<p class="admonition-title">Hint</p>
-<p>To add your code use sphinx tool in project root directory:</p>
-<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ sphinx-apidoc -o docs/api/ src/ds_pycontain
-</pre></div>
-</div>
-<p>and add reference from any page which is reachable from the index page.</p>
-</div>
-<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>    <span class="kn">import</span> <span class="nn">ds_pycontain</span>
+<p><strong>ds_pycontain</strong> is a python package which provides an abstraction over the docker API.</p>
+<p>Supported functionality covers:</p>
+<ul class="simple">
+<li><p>Building docker images from Dockerfiles</p></li>
+<li><p>Pulling docker images from dockerhub (or similar)</p></li>
+<li><p>Running docker containers to execute a one-off command</p></li>
+<li><p>Running docker containers to execute a long-running process and communicate with it</p></li>
+</ul>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span>  <span class="kn">from</span> <span class="nn">ds_pycontain</span> <span class="kn">import</span> <span class="n">DockerContainer</span><span class="p">,</span> <span class="n">DockerImage</span><span class="p">,</span> <span class="n">get_docker_client</span>
+
+  <span class="n">client</span> <span class="o">=</span> <span class="n">get_docker_client</span><span class="p">()</span>
+
+  <span class="c1"># This will fetch the image from dockerhub if it is not already present</span>
+  <span class="c1"># with the &quot;latest&quot; tag. Then container is started and commands are run</span>
+  <span class="k">with</span> <span class="n">DockerContainer</span><span class="p">(</span><span class="n">DockerImage</span><span class="o">.</span><span class="n">from_tag</span><span class="p">(</span><span class="s2">&quot;alpine&quot;</span><span class="p">))</span> <span class="k">as</span> <span class="n">container</span><span class="p">:</span>
+      <span class="n">ret_code</span><span class="p">,</span> <span class="n">output</span> <span class="o">=</span> <span class="n">container</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">&quot;touch /animal.txt&quot;</span><span class="p">)</span>
+      <span class="k">assert</span> <span class="n">ret_code</span> <span class="o">==</span> <span class="mi">0</span>
+
+      <span class="n">ret_code</span><span class="p">,</span> <span class="n">output</span> <span class="o">=</span> <span class="n">container</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">&quot;ls /&quot;</span><span class="p">)</span>
+      <span class="k">assert</span> <span class="n">ret_code</span> <span class="o">==</span> <span class="mi">0</span>
+      <span class="k">assert</span> <span class="n">cast</span><span class="p">(</span><span class="nb">bytes</span><span class="p">,</span> <span class="n">output</span><span class="p">)</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="sa">b</span><span class="s2">&quot;animal.txt&quot;</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="mi">0</span>
 </pre></div>
 </div>
 <div class="toctree-wrapper compound">
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="api/modules.html">ds_pycontain modules</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="api/ds_pycontain.html">ds_pycontain code documentation</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="api/ds_pycontain.html#submodules">Submodules</a></li>
-<li class="toctree-l3"><a class="reference internal" href="api/ds_pycontain.html#ds-pycontain-hello-module">ds_pycontain.hello module</a></li>
+<li class="toctree-l3"><a class="reference internal" href="api/ds_pycontain.html#module-ds_pycontain.docker_containers">ds_pycontain.docker_containers module</a><ul>
+<li class="toctree-l4"><a class="reference internal" href="api/ds_pycontain.html#ds_pycontain.docker_containers.DockerContainer"><code class="docutils literal notranslate"><span class="pre">DockerContainer</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api/ds_pycontain.html#ds_pycontain.docker_containers.DockerImage"><code class="docutils literal notranslate"><span class="pre">DockerImage</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api/ds_pycontain.html#ds_pycontain.docker_containers.generate_random_container_tag"><code class="docutils literal notranslate"><span class="pre">generate_random_container_tag()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="api/ds_pycontain.html#ds_pycontain.docker_containers.get_docker_client"><code class="docutils literal notranslate"><span class="pre">get_docker_client()</span></code></a></li>
+</ul>
+</li>
 <li class="toctree-l3"><a class="reference internal" href="api/ds_pycontain.html#module-ds_pycontain">Module contents</a><ul>
 <li class="toctree-l4"><a class="reference internal" href="api/ds_pycontain.html#ds_pycontain.DockerContainer"><code class="docutils literal notranslate"><span class="pre">DockerContainer</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="api/ds_pycontain.html#ds_pycontain.DockerImage"><code class="docutils literal notranslate"><span class="pre">DockerImage</span></code></a></li>
@@ -123,7 +141,7 @@ <h1>Code documentation<a class="headerlink" href="#code-documentation" title="Pe
   <hr/>
 
   <div role="contentinfo">
-    <p>&#169; Copyright 2023, ds.</p>
+    <p>&#169; Copyright 2023, deepsense.ai.</p>
   </div>
 
   Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a