VirtualEnvOnDemand (version 3.0.0)
index

# Copyright (c) 2015 Timothy Savannah under terms of LGPLv3. You should have received a copy of this with this distribution as "LICENSE"
#
#  VirtualEnvOnDemand provides a simple means for an application, without restarting, to temporarily install and use its runtime requirements

 
Package Contents
       
CreateEnv
GlobalEnv
InstallPackages
VirtualEnvInfo
exceptions

 
Classes
       
builtins.Exception(builtins.BaseException)
VirtualEnvOnDemand.exceptions.PipInstallFailed
builtins.object
VirtualEnvOnDemand.VirtualEnvInfo.VirtualEnvInfo

 
class PipInstallFailed(builtins.Exception)
    PipInstallFailed - Exception raised when pip fails to install a list of packages
 
 
Method resolution order:
PipInstallFailed
builtins.Exception
builtins.BaseException
builtins.object

Methods defined here:
__init__(self, returnCode=None, reqFileContents='')
Create a PipInstallFailed exception, building a message from some pieces of information
 
    @param returnCode <int> - Return code of subprocess, or None if undetermined
    @param reqFileContents <str> - String of requirements file to reproduce error

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__repr__(self, /)
Return repr(self).
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
__str__(self, /)
Return str(self).
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class VirtualEnvInfo(builtins.object)
     Methods defined here:
__getitem__(self, name)
__init__(self, virtualenvDirectory='', sitePackagesDirectory='', requirementsTxt='')
__setitem__(self, name, value)

Data descriptors defined here:
requirementsTxt
sitePackagesDirectory
virtualenvDirectory

 
Functions
       
createEnv(packages, parentDirectory=None, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>, deleteOnClose=False)
createEnv - Creates a temporary virtual environment and installs the required modules for the current running application.
    You can use this, for example, to "recover" from a failed import by installing the software on demand.
 
    @param packages - Describes the required packages. Takes one of the following forms:
 
        String - Directly becomes contents of requirements.txt file to be ingested by pip
        List   - A list/tuple/set of package names (optionally including version requirements, e.x. MyPkg==1.2.3)
        Dict   - A dictionary of package names to versions. If no value is present, the latest will be fetched.
 
    @param parentDirectory <str> - Parent directory of the directory which will be created to hold the temporary environment and packages. Defaults to tempfile.tempdir
    @param stdout <iostream/None> - Stream to be used as stdout for installation. Default is sys.stdout. Use "None" to swallow output.
    @param stderr <iostream/None> - Stream to be used as stderr for installation. Default is sys.stderr. Use "None" to swallow output.
 
    @param deleteOnClose <bool> - If True (Default), this temporary environment and packages will be erased after program terminates. Note, this cannot trap everything (e.x. SIGKILL).
 
    @return - On success, returns a VirtualEnvInfo object, which can be used as a dict with the following fields:
        {
            'virtualenvDirectory'   : Absolute path to the root virtualenv directory
            'sitePackagesDirectory' : Absolute path to the site-packages directory within
            'requirements.txt'      : Full generated requirements.txt file used for pip installation
        }
 
@raises - 
    VirtualEnvOnDemand.exceptions.PipInstallFailed -  if cannot install packages
    Others (Exception, etc)                        -  If permissions problem to write to specified directory, etc
createEnvIfCannotImport(importName, packages, parentDirectory=None, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>, deleteOnClose=True)
createEnvIfCannotImport - Tries to import a given name, and if fails, creates a temporary env and installs given packages and tries again.
 
@see createEnv for most params.
 
@param importName - Name of module to import
 
@raises - 
    VirtualEnvOnDemand.exceptions.PipInstallFailed -  if cannot install packages
    ImportError                                    -  if cannot import even after successful installation of the packages.
    Others (Exception, etc)                        -  If permissions problem to write to specified directory, etc
 
@return - None if no env was created, otherwise the return VirtualEnvInfo object from the createEnv call. @see createEnv
enableOnDemandImporter(tmpDir=None)
enableOnDemandImporter - Calling this method turns on the "on demand" importer. A temporary global env is created, and all failed imports will attempt an installation.
 
   @param tmpDir <str/None> - Temporary directory to use. A subdirectory will be created within this. Defaults to tempdir.gettmpdir()
ensureImport(importName, venvDir, packageName=None, stdout=None, stderr=None)
ensureImport - Try to import a module, and upon failure to import try to install package into provided virtualenv
 
@param importName <str> - The name of the module to import
@param venvDir <str/VirtualEnvInfo> - The path to a virtualenv, likely created by createEnv or the global env (fetched via getGlobalVirtualEnvInfo()).
@param packageName <str/None> - If the package name differs from the import name (like biopython package provides "Bio" module), install this package if import fails. This may contain version info (like AdvancedHTMLParser>6.0)
@param stdout <stream/None> - Stream to use for stdout as package info, or None to silence. Default None. NOTE: This differs from elsewhere where sys.stdout is default.
@param stderr <stream/None> - Stream to use for stderr as package info, or None to silence. Default None. NOTE: This differs from elsewhere where sys.stderr is default.
 
@return - The imported module
 
@raises - ImportError if cannot import.
 
    NOTE: With this method, PipInstallFailed will be intercepted and ImportError thrown instead, as this is intended to be a drop-in replacement for "import" when the package name differs.
ensureImportGlobal(importName, packageName=None, stdout=None, stderr=None)
ensureImportGlobal - Try to import a module, and upon failure to import try to install package into global virtualenv. This assumes that enableOnDemandImporter has already been called.
 
@param importName <str> - The name of the module to import
@param packageName <str/None> - If the package name differs from the import name (like biopython package provides "Bio" module), install this package if import fails. This may contain version info (like AdvancedHTMLParser>6.0)
@param stdout <stream/None> - Stream to use for stdout as package info, or None to silence. Default None. NOTE: This differs from elsewhere where sys.stdout is default.
@param stderr <stream/None> - Stream to use for stderr as package info, or None to silence. Default None. NOTE: This differs from elsewhere where sys.stderr is default.
 
@return - The imported module
 
@raises - ImportError if cannot import.
 
    NOTE: With this method, PipInstallFailed will be intercepted and ImportError thrown instead, as this is intended to be a drop-in replacement for "import" when the package name differs.
getGlobalVirtualEnvInfo()
getGlobalVirtualEnvInfo - Returns the VirtualEnvInfo object representing the global environment, or None if not setup.
 
If not setup, call enableOnDemandImporter() to add the hook and create the "global" env.
 
@return VirtualEnvInfo representing global env, or None if enableOnDemandImporter has not been called.
installPackages(packages, venvDir, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>)
installPackages - Installs packages into a created virtual environment
 
    @param packages - Describes the required packages. Takes one of the following forms:
 
        String - Directly becomes contents of requirements.txt file to be ingested by pip
        List   - A list/tuple/set of package names (optionally including version requirements, e.x. MyPkg==1.2.3)
        Dict   - A dictionary of package names to versions. If no value is present, the latest will be fetched.
 
    @param venvDir <str/VirtualEnvInfo> - Path to a created virtualenv directory. This should be the 'virtualenvDirectory' key from the return of createEnv, or just the VirtualEnvInfo object itself will work.
    @param stdout <iostream/None> - Stream to be used as stdout for installation. Default is sys.stdout. Use "None" to swallow output.
    @param stderr <iostream/None> - Stream to be used as stderr for installation. Default is sys.stderr. Use "None" to swallow output.
 
    @return - The generated requirements.txt used to install packages.
 
    @raises - 
        VirtualEnvOnDemand.exceptions.PipInstallFailed -  if cannot install packages
        Others (Exception, etc)                        -  If permissions problem to write to specified directory, etc

 
Data
        __all__ = ('createEnv', 'createEnvIfCannotImport', 'enableOnDemandImporter', 'getGlobalVirtualEnvInfo', 'installPackages', 'ensureImport', 'ensureImportGlobal', 'PipInstallFailed', 'VirtualEnvInfo', '__version__', '__version_tuple__')
__version_tuple__ = (3, 0, 0)