Commits

James Tocknell committed 4465012

Improved docs and usage of TemporaryVenv

  • Participants
  • Parent commits edb38cc

Comments (0)

Files changed (2)

File doc/index.rst

 
 .. code-block :: python
 
-    with venv_tools.TemporaryVenv(path_to_venv):
-        subprocess.call(["pip", "install", "-r", "requirements.txt"])
-        subprocess.call(["python", "-m", "profile", "project"])
+    from venv_tools import TemporaryVenv, Venv
+    from subprocess import call # or similar
+
+    with TemporaryVenv() as env_dir, Venv(env_dir):
+        call(["pip", "install", "-r", "requirements.txt"])
+        call(["python", "-m", "profile", "project"])
 
 Contents:
 

File venv_tools/__init__.py

 
 class Venv(object):
     """
+    Context manager around activating and deactivating a venv.
 
+    `Venv` sets a number of environment variables which are equivalent to
+    running `bin/activate`. It can create a venv if `venv_builder` is given.
+
+    .. warning::
+        Creating or activating a venv inside a venv can be "interesting", with
+        the results varying between different python versions (and different
+        venv tools). The safest method appears to be using virtualenv, however
+        this should not be relied upon. A warning will be raised if it is
+        detected that this is running inside a venv.
+
+    :param str env_dir: The absolute path to the venv.
+    :param venv_builder: An object which creates a venv. It must define a method
+        `create` which takes one argument, `env_dir`, and creates a venv at that
+        path. Any additional keywords passed to `Venv` will be passed to the
+        object.
+
+    :type venv_builder: `venv.EnvBuilder or similar`
     """
     def __init__(self, env_dir, venv_builder=None, **kwargs):
         self.env_dir = env_dir
 
 class TemporaryVenv(object):
     """
+    Context manager around creating a temporary venv.
+
+    `TemporaryVenv` handles the creation and removal of a temporary venv. By
+    default it will try to use the venv tools in the standard library, and fall
+    back to using `virtualenv <http://www.virtualenv.org/>`_.
+
+    .. note::
+        The tool used to create the venv depends on the arguments given.
+        `venv_builder` overrules `use_virtualenv` which overrules the defaults.
+        If `path_to_python_exe` is given, then it is passed to the venv builder,
+        which is chosen as above with the addition that the default will be a
+        tool that supports using a specific python executable (most likely
+        virtualenv).
+
+    .. warning::
+        Creating or activating a venv inside a venv can be "interesting", with
+        the results varying between different python versions (and different
+        venv tools). The safest method appears to be using virtualenv, however
+        this should not be relied upon. A warning will be raised if it is
+        detected that this is running inside a venv.
+
+    :param str env_dir: The absolute path to the venv.
+    :param venv_builder: An object which creates a venv. It must define a method
+        `create` which takes one argument, `env_dir`, and creates a venv at that
+        path. Any additional keywords passed to `Venv` will be passed to the
+        object.
+
+    :type venv_builder: `venv.EnvBuilder or similar`
     """
     def __init__(
             self,
             self._kwargs["path_to_python_exe"] = self._path_to_python_exe
         venv = self._venv_builder(**self._kwargs)
         venv.create(self.env_dir)
-        self._opened_venv = Venv(self.env_dir)
-        self._opened_venv.__enter__()
-        return self
+        return self.env_dir
 
     def __exit__(self, exc_type, exc_value, traceback):
-        self._opened_venv.__exit__(exc_type, exc_value, traceback)
         shutil.rmtree(self.env_dir)
 
-__all__ = [Venv, TemporaryVenv]