Let's get some real documentation started.

3 files changed, 75 insertions, 2 deletions

diff --git a/sandboxlib/__init__.py b/sandboxlib/__init__.py
index 04ae353..c17a12b 100644
--- a/sandboxlib/__init__.py
+++ b/sandboxlib/__init__.py
@@ -13,7 +13,62 @@
 # with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
-'''sandboxlib module.'''
+'''sandboxlib module.
+
+This module contains multiple 'executor' backends, which must all provide
+the same API. A stub version of the API is defined in this file, with
+docstrings that describe the different parameters.
+
+'''
+
+
+def maximum_possible_isolation():
+    '''Describe the 'tightest' isolation possible with a specific backend.
+
+    This function returns a dict, with the following keys:
+
+      - network
+
+    Each key maps to a parameter of the run_sandbox() function, and each
+    value is a valid value for that parameter.
+
+    Example result:
+
+        {
+            'network': 'isolated'
+        }
+
+    You can pass the result directly to a run_sandbox() function directly,
+    using the `**` operator to turn it into keyword arguments as in the
+    following example:
+
+        isolation_settings = maximum_possible_isolation()
+        run_sandbox(root_path, ['echo', 'hello'], **isolation_settings)
+
+    '''
+    raise NotImplementedError()
+
+
+def run_sandbox(rootfs_path, command, cwd=None, extra_env=None,
+                network='undefined'):
+    '''Run 'command' in a sandboxed environment.
+
+    Parameters:
+      - rootfs_path: the path to the root of the sandbox. Can be '/', if you
+            don't want to isolate the command from the host filesystem at all.
+      - command: the command to run. Pass a list of parameters rather than
+            using spaces to separate them, e.g. ['echo', '"Hello world"'].
+      - cwd: the working directory of 'command', relative to 'rootfs_path'.
+            Defaults to '/' if "rootfs_path" is specified, and the current
+            directory of the calling process otherwise.
+      - extra_env: environment variables to set in addition to
+            BASE_ENVIRONMENT.
+      - network: configures network sharing. Defaults to 'undefined', where
+            case no attempt is made to either prevent or provide networking
+            inside the sandbox. Backends may support 'isolated' and/or other
+            values as well.
+
+    '''
 
 
 BASE_ENVIRONMENT = {
diff --git a/sandboxlib/chroot.py b/sandboxlib/chroot.py
index 7c79f5c..8862b13 100644
--- a/sandboxlib/chroot.py
+++ b/sandboxlib/chroot.py
@@ -15,6 +15,14 @@
 
 '''Execute command in a sandbox, using os.chroot().
 
+This implements an API defined in sandboxlib/__init__.py.
+
+This backend should work on any POSIX-compliant operating system. It has been
+tested on Linux only. The calling process must be able to use the chroot()
+syscall, which is likely to require 'root' priviliges.
+
+Supported network settings: 'undefined'.
+
 The code would be simpler if we just used the 'chroot' program, but it's not
 always practical to do that. First, it may not be installed. Second, we can't
 set the working directory of the program inside the chroot, unless we assume
diff --git a/sandboxlib/linux_user_chroot.py b/sandboxlib/linux_user_chroot.py
index cbd15d3..0a65f5d 100644
--- a/sandboxlib/linux_user_chroot.py
+++ b/sandboxlib/linux_user_chroot.py
@@ -13,7 +13,17 @@
 # with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
-'''Execute command in a sandbox, using 'linux-user-chroot'.'''
+'''Execute command in a sandbox, using 'linux-user-chroot'.
+
+This implements an API defined in sandboxlib/__init__.py.
+
+This backend requires the `linux-user-chroot` program. This program is
+Linux-only. It is intended to be a 'setuid', and thus usable by non-'root'
+users that have explicitly been given permission to use it.
+
+Supported network settings: 'undefined', 'isolated'.
+
+'''
 
 
 import subprocess