1""" 2Virtual environment (venv) package for Python. Based on PEP 405. 3 4Copyright (C) 2011-2014 Vinay Sajip. 5Licensed to the PSF under a contributor agreement. 6""" 7import logging 8import os 9import shutil 10import subprocess 11import sys 12import sysconfig 13import types 14 15 16CORE_VENV_DEPS = ('pip', 'setuptools') 17logger = logging.getLogger(__name__) 18 19 20class EnvBuilder: 21 """ 22 This class exists to allow virtual environment creation to be 23 customized. The constructor parameters determine the builder's 24 behaviour when called upon to create a virtual environment. 25 26 By default, the builder makes the system (global) site-packages dir 27 *un*available to the created environment. 28 29 If invoked using the Python -m option, the default is to use copying 30 on Windows platforms but symlinks elsewhere. If instantiated some 31 other way, the default is to *not* use symlinks. 32 33 :param system_site_packages: If True, the system (global) site-packages 34 dir is available to created environments. 35 :param clear: If True, delete the contents of the environment directory if 36 it already exists, before environment creation. 37 :param symlinks: If True, attempt to symlink rather than copy files into 38 virtual environment. 39 :param upgrade: If True, upgrade an existing virtual environment. 40 :param with_pip: If True, ensure pip is installed in the virtual 41 environment 42 :param prompt: Alternative terminal prefix for the environment. 43 :param upgrade_deps: Update the base venv modules to the latest on PyPI 44 """ 45 46 def __init__(self, system_site_packages=False, clear=False, 47 symlinks=False, upgrade=False, with_pip=False, prompt=None, 48 upgrade_deps=False): 49 self.system_site_packages = system_site_packages 50 self.clear = clear 51 self.symlinks = symlinks 52 self.upgrade = upgrade 53 self.with_pip = with_pip 54 if prompt == '.': # see bpo-38901 55 prompt = os.path.basename(os.getcwd()) 56 self.prompt = prompt 57 self.upgrade_deps = upgrade_deps 58 59 def create(self, env_dir): 60 """ 61 Create a virtual environment in a directory. 62 63 :param env_dir: The target directory to create an environment in. 64 65 """ 66 env_dir = os.path.abspath(env_dir) 67 context = self.ensure_directories(env_dir) 68 # See issue 24875. We need system_site_packages to be False 69 # until after pip is installed. 70 true_system_site_packages = self.system_site_packages 71 self.system_site_packages = False 72 self.create_configuration(context) 73 self.setup_python(context) 74 if self.with_pip: 75 self._setup_pip(context) 76 if not self.upgrade: 77 self.setup_scripts(context) 78 self.post_setup(context) 79 if true_system_site_packages: 80 # We had set it to False before, now 81 # restore it and rewrite the configuration 82 self.system_site_packages = True 83 self.create_configuration(context) 84 if self.upgrade_deps: 85 self.upgrade_dependencies(context) 86 87 def clear_directory(self, path): 88 for fn in os.listdir(path): 89 fn = os.path.join(path, fn) 90 if os.path.islink(fn) or os.path.isfile(fn): 91 os.remove(fn) 92 elif os.path.isdir(fn): 93 shutil.rmtree(fn) 94 95 def ensure_directories(self, env_dir): 96 """ 97 Create the directories for the environment. 98 99 Returns a context object which holds paths in the environment, 100 for use by subsequent logic. 101 """ 102 103 def create_if_needed(d): 104 if not os.path.exists(d): 105 os.makedirs(d) 106 elif os.path.islink(d) or os.path.isfile(d): 107 raise ValueError('Unable to create directory %r' % d) 108 109 if os.path.exists(env_dir) and self.clear: 110 self.clear_directory(env_dir) 111 context = types.SimpleNamespace() 112 context.env_dir = env_dir 113 context.env_name = os.path.split(env_dir)[1] 114 prompt = self.prompt if self.prompt is not None else context.env_name 115 context.prompt = '(%s) ' % prompt 116 create_if_needed(env_dir) 117 executable = sys._base_executable 118 dirname, exename = os.path.split(os.path.abspath(executable)) 119 context.executable = executable 120 context.python_dir = dirname 121 context.python_exe = exename 122 if sys.platform == 'win32': 123 binname = 'Scripts' 124 incpath = 'Include' 125 libpath = os.path.join(env_dir, 'Lib', 'site-packages') 126 else: 127 binname = 'bin' 128 incpath = 'include' 129 libpath = os.path.join(env_dir, 'lib', 130 'python%d.%d' % sys.version_info[:2], 131 'site-packages') 132 context.inc_path = path = os.path.join(env_dir, incpath) 133 create_if_needed(path) 134 create_if_needed(libpath) 135 # Issue 21197: create lib64 as a symlink to lib on 64-bit non-OS X POSIX 136 if ((sys.maxsize > 2**32) and (os.name == 'posix') and 137 (sys.platform != 'darwin')): 138 link_path = os.path.join(env_dir, 'lib64') 139 if not os.path.exists(link_path): # Issue #21643 140 os.symlink('lib', link_path) 141 context.bin_path = binpath = os.path.join(env_dir, binname) 142 context.bin_name = binname 143 context.env_exe = os.path.join(binpath, exename) 144 create_if_needed(binpath) 145 return context 146 147 def create_configuration(self, context): 148 """ 149 Create a configuration file indicating where the environment's Python 150 was copied from, and whether the system site-packages should be made 151 available in the environment. 152 153 :param context: The information for the environment creation request 154 being processed. 155 """ 156 context.cfg_path = path = os.path.join(context.env_dir, 'pyvenv.cfg') 157 with open(path, 'w', encoding='utf-8') as f: 158 f.write('home = %s\n' % context.python_dir) 159 if self.system_site_packages: 160 incl = 'true' 161 else: 162 incl = 'false' 163 f.write('include-system-site-packages = %s\n' % incl) 164 f.write('version = %d.%d.%d\n' % sys.version_info[:3]) 165 if self.prompt is not None: 166 f.write(f'prompt = {self.prompt!r}\n') 167 168 if os.name != 'nt': 169 def symlink_or_copy(self, src, dst, relative_symlinks_ok=False): 170 """ 171 Try symlinking a file, and if that fails, fall back to copying. 172 """ 173 force_copy = not self.symlinks 174 if not force_copy: 175 try: 176 if not os.path.islink(dst): # can't link to itself! 177 if relative_symlinks_ok: 178 assert os.path.dirname(src) == os.path.dirname(dst) 179 os.symlink(os.path.basename(src), dst) 180 else: 181 os.symlink(src, dst) 182 except Exception: # may need to use a more specific exception 183 logger.warning('Unable to symlink %r to %r', src, dst) 184 force_copy = True 185 if force_copy: 186 shutil.copyfile(src, dst) 187 else: 188 def symlink_or_copy(self, src, dst, relative_symlinks_ok=False): 189 """ 190 Try symlinking a file, and if that fails, fall back to copying. 191 """ 192 bad_src = os.path.lexists(src) and not os.path.exists(src) 193 if self.symlinks and not bad_src and not os.path.islink(dst): 194 try: 195 if relative_symlinks_ok: 196 assert os.path.dirname(src) == os.path.dirname(dst) 197 os.symlink(os.path.basename(src), dst) 198 else: 199 os.symlink(src, dst) 200 return 201 except Exception: # may need to use a more specific exception 202 logger.warning('Unable to symlink %r to %r', src, dst) 203 204 # On Windows, we rewrite symlinks to our base python.exe into 205 # copies of venvlauncher.exe 206 basename, ext = os.path.splitext(os.path.basename(src)) 207 srcfn = os.path.join(os.path.dirname(__file__), 208 "scripts", 209 "nt", 210 basename + ext) 211 # Builds or venv's from builds need to remap source file 212 # locations, as we do not put them into Lib/venv/scripts 213 if sysconfig.is_python_build(True) or not os.path.isfile(srcfn): 214 if basename.endswith('_d'): 215 ext = '_d' + ext 216 basename = basename[:-2] 217 if basename == 'python': 218 basename = 'venvlauncher' 219 elif basename == 'pythonw': 220 basename = 'venvwlauncher' 221 src = os.path.join(os.path.dirname(src), basename + ext) 222 else: 223 src = srcfn 224 if not os.path.exists(src): 225 if not bad_src: 226 logger.warning('Unable to copy %r', src) 227 return 228 229 shutil.copyfile(src, dst) 230 231 def setup_python(self, context): 232 """ 233 Set up a Python executable in the environment. 234 235 :param context: The information for the environment creation request 236 being processed. 237 """ 238 binpath = context.bin_path 239 path = context.env_exe 240 copier = self.symlink_or_copy 241 dirname = context.python_dir 242 if os.name != 'nt': 243 copier(context.executable, path) 244 if not os.path.islink(path): 245 os.chmod(path, 0o755) 246 for suffix in ('python', 'python3', f'python3.{sys.version_info[1]}'): 247 path = os.path.join(binpath, suffix) 248 if not os.path.exists(path): 249 # Issue 18807: make copies if 250 # symlinks are not wanted 251 copier(context.env_exe, path, relative_symlinks_ok=True) 252 if not os.path.islink(path): 253 os.chmod(path, 0o755) 254 else: 255 if self.symlinks: 256 # For symlinking, we need a complete copy of the root directory 257 # If symlinks fail, you'll get unnecessary copies of files, but 258 # we assume that if you've opted into symlinks on Windows then 259 # you know what you're doing. 260 suffixes = [ 261 f for f in os.listdir(dirname) if 262 os.path.normcase(os.path.splitext(f)[1]) in ('.exe', '.dll') 263 ] 264 if sysconfig.is_python_build(True): 265 suffixes = [ 266 f for f in suffixes if 267 os.path.normcase(f).startswith(('python', 'vcruntime')) 268 ] 269 else: 270 suffixes = ['python.exe', 'python_d.exe', 'pythonw.exe', 271 'pythonw_d.exe'] 272 273 for suffix in suffixes: 274 src = os.path.join(dirname, suffix) 275 if os.path.lexists(src): 276 copier(src, os.path.join(binpath, suffix)) 277 278 if sysconfig.is_python_build(True): 279 # copy init.tcl 280 for root, dirs, files in os.walk(context.python_dir): 281 if 'init.tcl' in files: 282 tcldir = os.path.basename(root) 283 tcldir = os.path.join(context.env_dir, 'Lib', tcldir) 284 if not os.path.exists(tcldir): 285 os.makedirs(tcldir) 286 src = os.path.join(root, 'init.tcl') 287 dst = os.path.join(tcldir, 'init.tcl') 288 shutil.copyfile(src, dst) 289 break 290 291 def _setup_pip(self, context): 292 """Installs or upgrades pip in a virtual environment""" 293 # We run ensurepip in isolated mode to avoid side effects from 294 # environment vars, the current directory and anything else 295 # intended for the global Python environment 296 cmd = [context.env_exe, '-Im', 'ensurepip', '--upgrade', 297 '--default-pip'] 298 subprocess.check_output(cmd, stderr=subprocess.STDOUT) 299 300 def setup_scripts(self, context): 301 """ 302 Set up scripts into the created environment from a directory. 303 304 This method installs the default scripts into the environment 305 being created. You can prevent the default installation by overriding 306 this method if you really need to, or if you need to specify 307 a different location for the scripts to install. By default, the 308 'scripts' directory in the venv package is used as the source of 309 scripts to install. 310 """ 311 path = os.path.abspath(os.path.dirname(__file__)) 312 path = os.path.join(path, 'scripts') 313 self.install_scripts(context, path) 314 315 def post_setup(self, context): 316 """ 317 Hook for post-setup modification of the venv. Subclasses may install 318 additional packages or scripts here, add activation shell scripts, etc. 319 320 :param context: The information for the environment creation request 321 being processed. 322 """ 323 pass 324 325 def replace_variables(self, text, context): 326 """ 327 Replace variable placeholders in script text with context-specific 328 variables. 329 330 Return the text passed in , but with variables replaced. 331 332 :param text: The text in which to replace placeholder variables. 333 :param context: The information for the environment creation request 334 being processed. 335 """ 336 text = text.replace('__VENV_DIR__', context.env_dir) 337 text = text.replace('__VENV_NAME__', context.env_name) 338 text = text.replace('__VENV_PROMPT__', context.prompt) 339 text = text.replace('__VENV_BIN_NAME__', context.bin_name) 340 text = text.replace('__VENV_PYTHON__', context.env_exe) 341 return text 342 343 def install_scripts(self, context, path): 344 """ 345 Install scripts into the created environment from a directory. 346 347 :param context: The information for the environment creation request 348 being processed. 349 :param path: Absolute pathname of a directory containing script. 350 Scripts in the 'common' subdirectory of this directory, 351 and those in the directory named for the platform 352 being run on, are installed in the created environment. 353 Placeholder variables are replaced with environment- 354 specific values. 355 """ 356 binpath = context.bin_path 357 plen = len(path) 358 for root, dirs, files in os.walk(path): 359 if root == path: # at top-level, remove irrelevant dirs 360 for d in dirs[:]: 361 if d not in ('common', os.name): 362 dirs.remove(d) 363 continue # ignore files in top level 364 for f in files: 365 if (os.name == 'nt' and f.startswith('python') 366 and f.endswith(('.exe', '.pdb'))): 367 continue 368 srcfile = os.path.join(root, f) 369 suffix = root[plen:].split(os.sep)[2:] 370 if not suffix: 371 dstdir = binpath 372 else: 373 dstdir = os.path.join(binpath, *suffix) 374 if not os.path.exists(dstdir): 375 os.makedirs(dstdir) 376 dstfile = os.path.join(dstdir, f) 377 with open(srcfile, 'rb') as f: 378 data = f.read() 379 if not srcfile.endswith(('.exe', '.pdb')): 380 try: 381 data = data.decode('utf-8') 382 data = self.replace_variables(data, context) 383 data = data.encode('utf-8') 384 except UnicodeError as e: 385 data = None 386 logger.warning('unable to copy script %r, ' 387 'may be binary: %s', srcfile, e) 388 if data is not None: 389 with open(dstfile, 'wb') as f: 390 f.write(data) 391 shutil.copymode(srcfile, dstfile) 392 393 def upgrade_dependencies(self, context): 394 logger.debug( 395 f'Upgrading {CORE_VENV_DEPS} packages in {context.bin_path}' 396 ) 397 if sys.platform == 'win32': 398 python_exe = os.path.join(context.bin_path, 'python.exe') 399 else: 400 python_exe = os.path.join(context.bin_path, 'python') 401 cmd = [python_exe, '-m', 'pip', 'install', '--upgrade'] 402 cmd.extend(CORE_VENV_DEPS) 403 subprocess.check_call(cmd) 404 405 406def create(env_dir, system_site_packages=False, clear=False, 407 symlinks=False, with_pip=False, prompt=None, upgrade_deps=False): 408 """Create a virtual environment in a directory.""" 409 builder = EnvBuilder(system_site_packages=system_site_packages, 410 clear=clear, symlinks=symlinks, with_pip=with_pip, 411 prompt=prompt, upgrade_deps=upgrade_deps) 412 builder.create(env_dir) 413 414def main(args=None): 415 compatible = True 416 if sys.version_info < (3, 3): 417 compatible = False 418 elif not hasattr(sys, 'base_prefix'): 419 compatible = False 420 if not compatible: 421 raise ValueError('This script is only for use with Python >= 3.3') 422 else: 423 import argparse 424 425 parser = argparse.ArgumentParser(prog=__name__, 426 description='Creates virtual Python ' 427 'environments in one or ' 428 'more target ' 429 'directories.', 430 epilog='Once an environment has been ' 431 'created, you may wish to ' 432 'activate it, e.g. by ' 433 'sourcing an activate script ' 434 'in its bin directory.') 435 parser.add_argument('dirs', metavar='ENV_DIR', nargs='+', 436 help='A directory to create the environment in.') 437 parser.add_argument('--system-site-packages', default=False, 438 action='store_true', dest='system_site', 439 help='Give the virtual environment access to the ' 440 'system site-packages dir.') 441 if os.name == 'nt': 442 use_symlinks = False 443 else: 444 use_symlinks = True 445 group = parser.add_mutually_exclusive_group() 446 group.add_argument('--symlinks', default=use_symlinks, 447 action='store_true', dest='symlinks', 448 help='Try to use symlinks rather than copies, ' 449 'when symlinks are not the default for ' 450 'the platform.') 451 group.add_argument('--copies', default=not use_symlinks, 452 action='store_false', dest='symlinks', 453 help='Try to use copies rather than symlinks, ' 454 'even when symlinks are the default for ' 455 'the platform.') 456 parser.add_argument('--clear', default=False, action='store_true', 457 dest='clear', help='Delete the contents of the ' 458 'environment directory if it ' 459 'already exists, before ' 460 'environment creation.') 461 parser.add_argument('--upgrade', default=False, action='store_true', 462 dest='upgrade', help='Upgrade the environment ' 463 'directory to use this version ' 464 'of Python, assuming Python ' 465 'has been upgraded in-place.') 466 parser.add_argument('--without-pip', dest='with_pip', 467 default=True, action='store_false', 468 help='Skips installing or upgrading pip in the ' 469 'virtual environment (pip is bootstrapped ' 470 'by default)') 471 parser.add_argument('--prompt', 472 help='Provides an alternative prompt prefix for ' 473 'this environment.') 474 parser.add_argument('--upgrade-deps', default=False, action='store_true', 475 dest='upgrade_deps', 476 help='Upgrade core dependencies: {} to the latest ' 477 'version in PyPI'.format( 478 ' '.join(CORE_VENV_DEPS))) 479 options = parser.parse_args(args) 480 if options.upgrade and options.clear: 481 raise ValueError('you cannot supply --upgrade and --clear together.') 482 builder = EnvBuilder(system_site_packages=options.system_site, 483 clear=options.clear, 484 symlinks=options.symlinks, 485 upgrade=options.upgrade, 486 with_pip=options.with_pip, 487 prompt=options.prompt, 488 upgrade_deps=options.upgrade_deps) 489 for d in options.dirs: 490 builder.create(d) 491 492if __name__ == '__main__': 493 rc = 1 494 try: 495 main() 496 rc = 0 497 except Exception as e: 498 print('Error: %s' % e, file=sys.stderr) 499 sys.exit(rc) 500