| |
- createEnv(packages, parentDirectory=None, stdout=<open file '<stdout>', mode 'w'>, stderr=<open file '<stderr>', mode 'w'>, deleteOnClose=True)
- 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=<open file '<stdout>', mode 'w'>, stderr=<open file '<stderr>', mode 'w'>, 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, deferSetup=True, noRetryFailedPackages=True)
- 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 tempfile.gettempdir()
@param deferSetup <bool> - If True (default), defers setup (which can take a couple seconds) until the first failed import or attempted install.
Setup takes a couple seconds. Use this to always enable on-demand importer, but give advantage if all modules are present.
If False, the ondemand virtualenv will be setup right-away. If you are using this in a multi-threaded environment, this should be set to False.
@param noRetryFailedPackages <bool> - If True (default), a package which fails to download will not be retried. This is a performance savings. This should generally always be True,
unless you are using VirtualEnvOnDemand to have a running process written to work with an unreleased module to prevent a restart or something similar.
- 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=<open file '<stdout>', mode 'w'>, stderr=<open file '<stderr>', mode 'w'>)
- 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
VirtualEnvOnDemand.exceptions.VirtualEnvDoesNotExist - If given venvDir does not exist
Others (Exception, etc) - If permissions problem to write to specified directory, etc
- toggleOnDemandImporter(isActive)
- toggleOnDemandImporter - Toggle whether the on demand importer (import hook) is active.
If enableOnDemandImporter was not ever called, this has no effect. Otherwise, calling toggleOnDemandImporter(False) will temporarily disable the import hook, until toggleOnDemandImporter(True) is called.
@param isActive <bool> - To temporarily enable/disable the on-demand importer.
@return <bool> - True if a toggle occured, False if the global env has not been setup (by calling enableOnDemandImporter)
|