| 1 |
""" |
| 2 |
Virtual environment (venv) package for Python. Based on PEP 405. |
| 3 |
|
| 4 |
Copyright (C) 2011-2014 Vinay Sajip. |
| 5 |
Licensed to the PSF under a contributor agreement. |
| 6 |
""" |
| 7 |
import logging |
| 8 |
import os |
| 9 |
import shutil |
| 10 |
import subprocess |
| 11 |
import sys |
| 12 |
import sysconfig |
| 13 |
import types |
| 14 |
import shlex |
| 15 |
|
| 16 |
|
| 17 |
CORE_VENV_DEPS = ('pip',) |
| 18 |
logger = logging.getLogger(__name__) |
| 19 |
|
| 20 |
|
| 21 |
class EnvBuilder: |
| 22 |
""" |
| 23 |
This class exists to allow virtual environment creation to be |
| 24 |
customized. The constructor parameters determine the builder's |
| 25 |
behaviour when called upon to create a virtual environment. |
| 26 |
|
| 27 |
By default, the builder makes the system (global) site-packages dir |
| 28 |
*un*available to the created environment. |
| 29 |
|
| 30 |
If invoked using the Python -m option, the default is to use copying |
| 31 |
on Windows platforms but symlinks elsewhere. If instantiated some |
| 32 |
other way, the default is to *not* use symlinks. |
| 33 |
|
| 34 |
:param system_site_packages: If True, the system (global) site-packages |
| 35 |
dir is available to created environments. |
| 36 |
:param clear: If True, delete the contents of the environment directory if |
| 37 |
it already exists, before environment creation. |
| 38 |
:param symlinks: If True, attempt to symlink rather than copy files into |
| 39 |
virtual environment. |
| 40 |
:param upgrade: If True, upgrade an existing virtual environment. |
| 41 |
:param with_pip: If True, ensure pip is installed in the virtual |
| 42 |
environment |
| 43 |
:param prompt: Alternative terminal prefix for the environment. |
| 44 |
:param upgrade_deps: Update the base venv modules to the latest on PyPI |
| 45 |
:param scm_ignore_files: Create ignore files for the SCMs specified by the |
| 46 |
iterable. |
| 47 |
""" |
| 48 |
|
| 49 |
def __init__(self, system_site_packages=False, clear=False, |
| 50 |
symlinks=False, upgrade=False, with_pip=False, prompt=None, |
| 51 |
upgrade_deps=False, *, scm_ignore_files=frozenset()): |
| 52 |
self.system_site_packages = system_site_packages |
| 53 |
self.clear = clear |
| 54 |
self.symlinks = symlinks |
| 55 |
self.upgrade = upgrade |
| 56 |
self.with_pip = with_pip |
| 57 |
self.orig_prompt = prompt |
| 58 |
if prompt == '.': # see bpo-38901 |
| 59 |
prompt = os.path.basename(os.getcwd()) |
| 60 |
self.prompt = prompt |
| 61 |
self.upgrade_deps = upgrade_deps |
| 62 |
self.scm_ignore_files = frozenset(map(str.lower, scm_ignore_files)) |
| 63 |
|
| 64 |
def create(self, env_dir): |
| 65 |
""" |
| 66 |
Create a virtual environment in a directory. |
| 67 |
|
| 68 |
:param env_dir: The target directory to create an environment in. |
| 69 |
|
| 70 |
""" |
| 71 |
env_dir = os.path.abspath(env_dir) |
| 72 |
context = self.ensure_directories(env_dir) |
| 73 |
for scm in self.scm_ignore_files: |
| 74 |
getattr(self, f"create_{scm}_ignore_file")(context) |
| 75 |
# See issue 24875. We need system_site_packages to be False |
| 76 |
# until after pip is installed. |
| 77 |
true_system_site_packages = self.system_site_packages |
| 78 |
self.system_site_packages = False |
| 79 |
self.create_configuration(context) |
| 80 |
self.setup_python(context) |
| 81 |
if self.with_pip: |
| 82 |
self._setup_pip(context) |
| 83 |
if not self.upgrade: |
| 84 |
self.setup_scripts(context) |
| 85 |
self.post_setup(context) |
| 86 |
if true_system_site_packages: |
| 87 |
# We had set it to False before, now |
| 88 |
# restore it and rewrite the configuration |
| 89 |
self.system_site_packages = True |
| 90 |
self.create_configuration(context) |
| 91 |
if self.upgrade_deps: |
| 92 |
self.upgrade_dependencies(context) |
| 93 |
|
| 94 |
def clear_directory(self, path): |
| 95 |
for fn in os.listdir(path): |
| 96 |
fn = os.path.join(path, fn) |
| 97 |
if os.path.islink(fn) or os.path.isfile(fn): |
| 98 |
os.remove(fn) |
| 99 |
elif os.path.isdir(fn): |
| 100 |
shutil.rmtree(fn) |
| 101 |
|
| 102 |
def _venv_path(self, env_dir, name): |
| 103 |
vars = { |
| 104 |
'base': env_dir, |
| 105 |
'platbase': env_dir, |
| 106 |
} |
| 107 |
return sysconfig.get_path(name, scheme='venv', vars=vars) |
| 108 |
|
| 109 |
@classmethod |
| 110 |
def _same_path(cls, path1, path2): |
| 111 |
"""Check whether two paths appear the same. |
| 112 |
|
| 113 |
Whether they refer to the same file is irrelevant; we're testing for |
| 114 |
whether a human reader would look at the path string and easily tell |
| 115 |
that they're the same file. |
| 116 |
""" |
| 117 |
if sys.platform == 'win32': |
| 118 |
if os.path.normcase(path1) == os.path.normcase(path2): |
| 119 |
return True |
| 120 |
# gh-90329: Don't display a warning for short/long names |
| 121 |
import _winapi |
| 122 |
try: |
| 123 |
path1 = _winapi.GetLongPathName(os.fsdecode(path1)) |
| 124 |
except OSError: |
| 125 |
pass |
| 126 |
try: |
| 127 |
path2 = _winapi.GetLongPathName(os.fsdecode(path2)) |
| 128 |
except OSError: |
| 129 |
pass |
| 130 |
if os.path.normcase(path1) == os.path.normcase(path2): |
| 131 |
return True |
| 132 |
return False |
| 133 |
else: |
| 134 |
return path1 == path2 |
| 135 |
|
| 136 |
def ensure_directories(self, env_dir): |
| 137 |
""" |
| 138 |
Create the directories for the environment. |
| 139 |
|
| 140 |
Returns a context object which holds paths in the environment, |
| 141 |
for use by subsequent logic. |
| 142 |
""" |
| 143 |
|
| 144 |
def create_if_needed(d): |
| 145 |
if not os.path.exists(d): |
| 146 |
os.makedirs(d) |
| 147 |
elif os.path.islink(d) or os.path.isfile(d): |
| 148 |
raise ValueError('Unable to create directory %r' % d) |
| 149 |
|
| 150 |
if os.pathsep in os.fspath(env_dir): |
| 151 |
raise ValueError(f'Refusing to create a venv in {env_dir} because ' |
| 152 |
f'it contains the PATH separator {os.pathsep}.') |
| 153 |
if os.path.exists(env_dir) and self.clear: |
| 154 |
self.clear_directory(env_dir) |
| 155 |
context = types.SimpleNamespace() |
| 156 |
context.env_dir = env_dir |
| 157 |
context.env_name = os.path.split(env_dir)[1] |
| 158 |
context.prompt = self.prompt if self.prompt is not None else context.env_name |
| 159 |
create_if_needed(env_dir) |
| 160 |
executable = sys._base_executable |
| 161 |
if not executable: # see gh-96861 |
| 162 |
raise ValueError('Unable to determine path to the running ' |
| 163 |
'Python interpreter. Provide an explicit path or ' |
| 164 |
'check that your PATH environment variable is ' |
| 165 |
'correctly set.') |
| 166 |
dirname, exename = os.path.split(os.path.abspath(executable)) |
| 167 |
if sys.platform == 'win32': |
| 168 |
# Always create the simplest name in the venv. It will either be a |
| 169 |
# link back to executable, or a copy of the appropriate launcher |
| 170 |
_d = '_d' if os.path.splitext(exename)[0].endswith('_d') else '' |
| 171 |
exename = f'python{_d}.exe' |
| 172 |
context.executable = executable |
| 173 |
context.python_dir = dirname |
| 174 |
context.python_exe = exename |
| 175 |
binpath = self._venv_path(env_dir, 'scripts') |
| 176 |
libpath = self._venv_path(env_dir, 'purelib') |
| 177 |
|
| 178 |
# PEP 405 says venvs should create a local include directory. |
| 179 |
# See https://peps.python.org/pep-0405/#include-files |
| 180 |
# XXX: This directory is not exposed in sysconfig or anywhere else, and |
| 181 |
# doesn't seem to be utilized by modern packaging tools. We keep it |
| 182 |
# for backwards-compatibility, and to follow the PEP, but I would |
| 183 |
# recommend against using it, as most tooling does not pass it to |
| 184 |
# compilers. Instead, until we standardize a site-specific include |
| 185 |
# directory, I would recommend installing headers as package data, |
| 186 |
# and providing some sort of API to get the include directories. |
| 187 |
# Example: https://numpy.org/doc/2.1/reference/generated/numpy.get_include.html |
| 188 |
incpath = os.path.join(env_dir, 'Include' if os.name == 'nt' else 'include') |
| 189 |
|
| 190 |
context.inc_path = incpath |
| 191 |
create_if_needed(incpath) |
| 192 |
context.lib_path = libpath |
| 193 |
create_if_needed(libpath) |
| 194 |
# Issue 21197: create lib64 as a symlink to lib on 64-bit non-OS X POSIX |
| 195 |
if ((sys.maxsize > 2**32) and (os.name == 'posix') and |
| 196 |
(sys.platform != 'darwin')): |
| 197 |
link_path = os.path.join(env_dir, 'lib64') |
| 198 |
if not os.path.exists(link_path): # Issue #21643 |
| 199 |
os.symlink('lib', link_path) |
| 200 |
context.bin_path = binpath |
| 201 |
context.bin_name = os.path.relpath(binpath, env_dir) |
| 202 |
context.env_exe = os.path.join(binpath, exename) |
| 203 |
create_if_needed(binpath) |
| 204 |
# Assign and update the command to use when launching the newly created |
| 205 |
# environment, in case it isn't simply the executable script (e.g. bpo-45337) |
| 206 |
context.env_exec_cmd = context.env_exe |
| 207 |
if sys.platform == 'win32': |
| 208 |
# bpo-45337: Fix up env_exec_cmd to account for file system redirections. |
| 209 |
# Some redirects only apply to CreateFile and not CreateProcess |
| 210 |
real_env_exe = os.path.realpath(context.env_exe) |
| 211 |
if not self._same_path(real_env_exe, context.env_exe): |
| 212 |
logger.warning('Actual environment location may have moved due to ' |
| 213 |
'redirects, links or junctions.\n' |
| 214 |
' Requested location: "%s"\n' |
| 215 |
' Actual location: "%s"', |
| 216 |
context.env_exe, real_env_exe) |
| 217 |
context.env_exec_cmd = real_env_exe |
| 218 |
return context |
| 219 |
|
| 220 |
def create_configuration(self, context): |
| 221 |
""" |
| 222 |
Create a configuration file indicating where the environment's Python |
| 223 |
was copied from, and whether the system site-packages should be made |
| 224 |
available in the environment. |
| 225 |
|
| 226 |
:param context: The information for the environment creation request |
| 227 |
being processed. |
| 228 |
""" |
| 229 |
context.cfg_path = path = os.path.join(context.env_dir, 'pyvenv.cfg') |
| 230 |
with open(path, 'w', encoding='utf-8') as f: |
| 231 |
f.write('home = %s\n' % context.python_dir) |
| 232 |
if self.system_site_packages: |
| 233 |
incl = 'true' |
| 234 |
else: |
| 235 |
incl = 'false' |
| 236 |
f.write('include-system-site-packages = %s\n' % incl) |
| 237 |
f.write('version = %d.%d.%d\n' % sys.version_info[:3]) |
| 238 |
if self.prompt is not None: |
| 239 |
f.write(f'prompt = {self.prompt!r}\n') |
| 240 |
f.write('executable = %s\n' % os.path.realpath(sys.executable)) |
| 241 |
args = [] |
| 242 |
nt = os.name == 'nt' |
| 243 |
if nt and self.symlinks: |
| 244 |
args.append('--symlinks') |
| 245 |
if not nt and not self.symlinks: |
| 246 |
args.append('--copies') |
| 247 |
if not self.with_pip: |
| 248 |
args.append('--without-pip') |
| 249 |
if self.system_site_packages: |
| 250 |
args.append('--system-site-packages') |
| 251 |
if self.clear: |
| 252 |
args.append('--clear') |
| 253 |
if self.upgrade: |
| 254 |
args.append('--upgrade') |
| 255 |
if self.upgrade_deps: |
| 256 |
args.append('--upgrade-deps') |
| 257 |
if self.orig_prompt is not None: |
| 258 |
args.append(f'--prompt="{self.orig_prompt}"') |
| 259 |
if not self.scm_ignore_files: |
| 260 |
args.append('--without-scm-ignore-files') |
| 261 |
|
| 262 |
args.append(context.env_dir) |
| 263 |
args = ' '.join(args) |
| 264 |
f.write(f'command = {sys.executable} -m venv {args}\n') |
| 265 |
|
| 266 |
def symlink_or_copy(self, src, dst, relative_symlinks_ok=False): |
| 267 |
""" |
| 268 |
Try symlinking a file, and if that fails, fall back to copying. |
| 269 |
(Unused on Windows, because we can't just copy a failed symlink file: we |
| 270 |
switch to a different set of files instead.) |
| 271 |
""" |
| 272 |
assert os.name != 'nt' |
| 273 |
force_copy = not self.symlinks |
| 274 |
if not force_copy: |
| 275 |
try: |
| 276 |
if not os.path.islink(dst): # can't link to itself! |
| 277 |
if relative_symlinks_ok: |
| 278 |
assert os.path.dirname(src) == os.path.dirname(dst) |
| 279 |
os.symlink(os.path.basename(src), dst) |
| 280 |
else: |
| 281 |
os.symlink(src, dst) |
| 282 |
except Exception: # may need to use a more specific exception |
| 283 |
logger.warning('Unable to symlink %r to %r', src, dst) |
| 284 |
force_copy = True |
| 285 |
if force_copy: |
| 286 |
shutil.copyfile(src, dst) |
| 287 |
|
| 288 |
def create_git_ignore_file(self, context): |
| 289 |
""" |
| 290 |
Create a .gitignore file in the environment directory. |
| 291 |
|
| 292 |
The contents of the file cause the entire environment directory to be |
| 293 |
ignored by git. |
| 294 |
""" |
| 295 |
gitignore_path = os.path.join(context.env_dir, '.gitignore') |
| 296 |
with open(gitignore_path, 'w', encoding='utf-8') as file: |
| 297 |
file.write('# Created by venv; ' |
| 298 |
'see https://docs.python.org/3/library/venv.html\n') |
| 299 |
file.write('*\n') |
| 300 |
|
| 301 |
if os.name != 'nt': |
| 302 |
def setup_python(self, context): |
| 303 |
""" |
| 304 |
Set up a Python executable in the environment. |
| 305 |
|
| 306 |
:param context: The information for the environment creation request |
| 307 |
being processed. |
| 308 |
""" |
| 309 |
binpath = context.bin_path |
| 310 |
path = context.env_exe |
| 311 |
copier = self.symlink_or_copy |
| 312 |
dirname = context.python_dir |
| 313 |
copier(context.executable, path) |
| 314 |
if not os.path.islink(path): |
| 315 |
os.chmod(path, 0o755) |
| 316 |
|
| 317 |
suffixes = ['python', 'python3', f'python3.{sys.version_info[1]}'] |
| 318 |
if sys.version_info[:2] == (3, 14) and sys.getfilesystemencoding() == 'utf-8': |
| 319 |
suffixes.append('𝜋thon') |
| 320 |
for suffix in suffixes: |
| 321 |
path = os.path.join(binpath, suffix) |
| 322 |
if not os.path.exists(path): |
| 323 |
# Issue 18807: make copies if |
| 324 |
# symlinks are not wanted |
| 325 |
copier(context.env_exe, path, relative_symlinks_ok=True) |
| 326 |
if not os.path.islink(path): |
| 327 |
os.chmod(path, 0o755) |
| 328 |
|
| 329 |
else: |
| 330 |
def setup_python(self, context): |
| 331 |
""" |
| 332 |
Set up a Python executable in the environment. |
| 333 |
|
| 334 |
:param context: The information for the environment creation request |
| 335 |
being processed. |
| 336 |
""" |
| 337 |
binpath = context.bin_path |
| 338 |
dirname = context.python_dir |
| 339 |
exename = os.path.basename(context.env_exe) |
| 340 |
exe_stem = os.path.splitext(exename)[0] |
| 341 |
exe_d = '_d' if os.path.normcase(exe_stem).endswith('_d') else '' |
| 342 |
if sysconfig.is_python_build(): |
| 343 |
scripts = dirname |
| 344 |
else: |
| 345 |
scripts = os.path.join(os.path.dirname(__file__), |
| 346 |
'scripts', 'nt') |
| 347 |
if not sysconfig.get_config_var("Py_GIL_DISABLED"): |
| 348 |
python_exe = os.path.join(dirname, f'python{exe_d}.exe') |
| 349 |
pythonw_exe = os.path.join(dirname, f'pythonw{exe_d}.exe') |
| 350 |
link_sources = { |
| 351 |
'python.exe': python_exe, |
| 352 |
f'python{exe_d}.exe': python_exe, |
| 353 |
'pythonw.exe': pythonw_exe, |
| 354 |
f'pythonw{exe_d}.exe': pythonw_exe, |
| 355 |
} |
| 356 |
python_exe = os.path.join(scripts, f'venvlauncher{exe_d}.exe') |
| 357 |
pythonw_exe = os.path.join(scripts, f'venvwlauncher{exe_d}.exe') |
| 358 |
copy_sources = { |
| 359 |
'python.exe': python_exe, |
| 360 |
f'python{exe_d}.exe': python_exe, |
| 361 |
'pythonw.exe': pythonw_exe, |
| 362 |
f'pythonw{exe_d}.exe': pythonw_exe, |
| 363 |
} |
| 364 |
else: |
| 365 |
exe_t = f'3.{sys.version_info[1]}t' |
| 366 |
python_exe = os.path.join(dirname, f'python{exe_t}{exe_d}.exe') |
| 367 |
pythonw_exe = os.path.join(dirname, f'pythonw{exe_t}{exe_d}.exe') |
| 368 |
link_sources = { |
| 369 |
'python.exe': python_exe, |
| 370 |
f'python{exe_d}.exe': python_exe, |
| 371 |
f'python{exe_t}.exe': python_exe, |
| 372 |
f'python{exe_t}{exe_d}.exe': python_exe, |
| 373 |
'pythonw.exe': pythonw_exe, |
| 374 |
f'pythonw{exe_d}.exe': pythonw_exe, |
| 375 |
f'pythonw{exe_t}.exe': pythonw_exe, |
| 376 |
f'pythonw{exe_t}{exe_d}.exe': pythonw_exe, |
| 377 |
} |
| 378 |
python_exe = os.path.join(scripts, f'venvlaunchert{exe_d}.exe') |
| 379 |
pythonw_exe = os.path.join(scripts, f'venvwlaunchert{exe_d}.exe') |
| 380 |
copy_sources = { |
| 381 |
'python.exe': python_exe, |
| 382 |
f'python{exe_d}.exe': python_exe, |
| 383 |
f'python{exe_t}.exe': python_exe, |
| 384 |
f'python{exe_t}{exe_d}.exe': python_exe, |
| 385 |
'pythonw.exe': pythonw_exe, |
| 386 |
f'pythonw{exe_d}.exe': pythonw_exe, |
| 387 |
f'pythonw{exe_t}.exe': pythonw_exe, |
| 388 |
f'pythonw{exe_t}{exe_d}.exe': pythonw_exe, |
| 389 |
} |
| 390 |
|
| 391 |
do_copies = True |
| 392 |
if self.symlinks: |
| 393 |
do_copies = False |
| 394 |
# For symlinking, we need all the DLLs to be available alongside |
| 395 |
# the executables. |
| 396 |
link_sources.update({ |
| 397 |
f: os.path.join(dirname, f) for f in os.listdir(dirname) |
| 398 |
if os.path.normcase(f).startswith(('python', 'vcruntime')) |
| 399 |
and os.path.normcase(os.path.splitext(f)[1]) == '.dll' |
| 400 |
}) |
| 401 |
|
| 402 |
to_unlink = [] |
| 403 |
for dest, src in link_sources.items(): |
| 404 |
dest = os.path.join(binpath, dest) |
| 405 |
try: |
| 406 |
os.symlink(src, dest) |
| 407 |
to_unlink.append(dest) |
| 408 |
except OSError: |
| 409 |
logger.warning('Unable to symlink %r to %r', src, dest) |
| 410 |
do_copies = True |
| 411 |
for f in to_unlink: |
| 412 |
try: |
| 413 |
os.unlink(f) |
| 414 |
except OSError: |
| 415 |
logger.warning('Failed to clean up symlink %r', |
| 416 |
f) |
| 417 |
logger.warning('Retrying with copies') |
| 418 |
break |
| 419 |
|
| 420 |
if do_copies: |
| 421 |
for dest, src in copy_sources.items(): |
| 422 |
dest = os.path.join(binpath, dest) |
| 423 |
try: |
| 424 |
shutil.copy2(src, dest) |
| 425 |
except OSError: |
| 426 |
logger.warning('Unable to copy %r to %r', src, dest) |
| 427 |
|
| 428 |
if sysconfig.is_python_build(): |
| 429 |
# copy init.tcl |
| 430 |
for root, dirs, files in os.walk(context.python_dir): |
| 431 |
if 'init.tcl' in files: |
| 432 |
tcldir = os.path.basename(root) |
| 433 |
tcldir = os.path.join(context.env_dir, 'Lib', tcldir) |
| 434 |
if not os.path.exists(tcldir): |
| 435 |
os.makedirs(tcldir) |
| 436 |
src = os.path.join(root, 'init.tcl') |
| 437 |
dst = os.path.join(tcldir, 'init.tcl') |
| 438 |
shutil.copyfile(src, dst) |
| 439 |
break |
| 440 |
|
| 441 |
def _call_new_python(self, context, *py_args, **kwargs): |
| 442 |
"""Executes the newly created Python using safe-ish options""" |
| 443 |
# gh-98251: We do not want to just use '-I' because that masks |
| 444 |
# legitimate user preferences (such as not writing bytecode). All we |
| 445 |
# really need is to ensure that the path variables do not overrule |
| 446 |
# normal venv handling. |
| 447 |
args = [context.env_exec_cmd, *py_args] |
| 448 |
kwargs['env'] = env = os.environ.copy() |
| 449 |
env['VIRTUAL_ENV'] = context.env_dir |
| 450 |
env.pop('PYTHONHOME', None) |
| 451 |
env.pop('PYTHONPATH', None) |
| 452 |
kwargs['cwd'] = context.env_dir |
| 453 |
kwargs['executable'] = context.env_exec_cmd |
| 454 |
subprocess.check_output(args, **kwargs) |
| 455 |
|
| 456 |
def _setup_pip(self, context): |
| 457 |
"""Installs or upgrades pip in a virtual environment""" |
| 458 |
self._call_new_python(context, '-m', 'ensurepip', '--upgrade', |
| 459 |
'--default-pip', stderr=subprocess.STDOUT) |
| 460 |
|
| 461 |
def setup_scripts(self, context): |
| 462 |
""" |
| 463 |
Set up scripts into the created environment from a directory. |
| 464 |
|
| 465 |
This method installs the default scripts into the environment |
| 466 |
being created. You can prevent the default installation by overriding |
| 467 |
this method if you really need to, or if you need to specify |
| 468 |
a different location for the scripts to install. By default, the |
| 469 |
'scripts' directory in the venv package is used as the source of |
| 470 |
scripts to install. |
| 471 |
""" |
| 472 |
path = os.path.abspath(os.path.dirname(__file__)) |
| 473 |
path = os.path.join(path, 'scripts') |
| 474 |
self.install_scripts(context, path) |
| 475 |
|
| 476 |
def post_setup(self, context): |
| 477 |
""" |
| 478 |
Hook for post-setup modification of the venv. Subclasses may install |
| 479 |
additional packages or scripts here, add activation shell scripts, etc. |
| 480 |
|
| 481 |
:param context: The information for the environment creation request |
| 482 |
being processed. |
| 483 |
""" |
| 484 |
pass |
| 485 |
|
| 486 |
def replace_variables(self, text, context): |
| 487 |
""" |
| 488 |
Replace variable placeholders in script text with context-specific |
| 489 |
variables. |
| 490 |
|
| 491 |
Return the text passed in , but with variables replaced. |
| 492 |
|
| 493 |
:param text: The text in which to replace placeholder variables. |
| 494 |
:param context: The information for the environment creation request |
| 495 |
being processed. |
| 496 |
""" |
| 497 |
replacements = { |
| 498 |
'__VENV_DIR__': context.env_dir, |
| 499 |
'__VENV_NAME__': context.env_name, |
| 500 |
'__VENV_PROMPT__': context.prompt, |
| 501 |
'__VENV_BIN_NAME__': context.bin_name, |
| 502 |
'__VENV_PYTHON__': context.env_exe, |
| 503 |
} |
| 504 |
|
| 505 |
def quote_ps1(s): |
| 506 |
""" |
| 507 |
This should satisfy PowerShell quoting rules [1], unless the quoted |
| 508 |
string is passed directly to Windows native commands [2]. |
| 509 |
[1]: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules |
| 510 |
[2]: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing#passing-arguments-that-contain-quote-characters |
| 511 |
""" |
| 512 |
s = s.replace("'", "''") |
| 513 |
return f"'{s}'" |
| 514 |
|
| 515 |
def quote_bat(s): |
| 516 |
return s |
| 517 |
|
| 518 |
# gh-124651: need to quote the template strings properly |
| 519 |
quote = shlex.quote |
| 520 |
script_path = context.script_path |
| 521 |
if script_path.endswith('.ps1'): |
| 522 |
quote = quote_ps1 |
| 523 |
elif script_path.endswith('.bat'): |
| 524 |
quote = quote_bat |
| 525 |
else: |
| 526 |
# fallbacks to POSIX shell compliant quote |
| 527 |
quote = shlex.quote |
| 528 |
|
| 529 |
replacements = {key: quote(s) for key, s in replacements.items()} |
| 530 |
for key, quoted in replacements.items(): |
| 531 |
text = text.replace(key, quoted) |
| 532 |
return text |
| 533 |
|
| 534 |
def install_scripts(self, context, path): |
| 535 |
""" |
| 536 |
Install scripts into the created environment from a directory. |
| 537 |
|
| 538 |
:param context: The information for the environment creation request |
| 539 |
being processed. |
| 540 |
:param path: Absolute pathname of a directory containing script. |
| 541 |
Scripts in the 'common' subdirectory of this directory, |
| 542 |
and those in the directory named for the platform |
| 543 |
being run on, are installed in the created environment. |
| 544 |
Placeholder variables are replaced with environment- |
| 545 |
specific values. |
| 546 |
""" |
| 547 |
binpath = context.bin_path |
| 548 |
plen = len(path) |
| 549 |
if os.name == 'nt': |
| 550 |
def skip_file(f): |
| 551 |
f = os.path.normcase(f) |
| 552 |
return (f.startswith(('python', 'venv')) |
| 553 |
and f.endswith(('.exe', '.pdb'))) |
| 554 |
else: |
| 555 |
def skip_file(f): |
| 556 |
return False |
| 557 |
for root, dirs, files in os.walk(path): |
| 558 |
if root == path: # at top-level, remove irrelevant dirs |
| 559 |
for d in dirs[:]: |
| 560 |
if d not in ('common', os.name): |
| 561 |
dirs.remove(d) |
| 562 |
continue # ignore files in top level |
| 563 |
for f in files: |
| 564 |
if skip_file(f): |
| 565 |
continue |
| 566 |
srcfile = os.path.join(root, f) |
| 567 |
suffix = root[plen:].split(os.sep)[2:] |
| 568 |
if not suffix: |
| 569 |
dstdir = binpath |
| 570 |
else: |
| 571 |
dstdir = os.path.join(binpath, *suffix) |
| 572 |
if not os.path.exists(dstdir): |
| 573 |
os.makedirs(dstdir) |
| 574 |
dstfile = os.path.join(dstdir, f) |
| 575 |
if os.name == 'nt' and srcfile.endswith(('.exe', '.pdb')): |
| 576 |
shutil.copy2(srcfile, dstfile) |
| 577 |
continue |
| 578 |
with open(srcfile, 'rb') as f: |
| 579 |
data = f.read() |
| 580 |
try: |
| 581 |
context.script_path = srcfile |
| 582 |
new_data = ( |
| 583 |
self.replace_variables(data.decode('utf-8'), context) |
| 584 |
.encode('utf-8') |
| 585 |
) |
| 586 |
except UnicodeError as e: |
| 587 |
logger.warning('unable to copy script %r, ' |
| 588 |
'may be binary: %s', srcfile, e) |
| 589 |
continue |
| 590 |
if new_data == data: |
| 591 |
shutil.copy(srcfile, dstfile) |
| 592 |
else: |
| 593 |
with open(dstfile, 'wb') as f: |
| 594 |
f.write(new_data) |
| 595 |
shutil.copymode(srcfile, dstfile) |
| 596 |
|
| 597 |
def upgrade_dependencies(self, context): |
| 598 |
logger.debug( |
| 599 |
f'Upgrading {CORE_VENV_DEPS} packages in {context.bin_path}' |
| 600 |
) |
| 601 |
self._call_new_python(context, '-m', 'pip', 'install', '--upgrade', |
| 602 |
*CORE_VENV_DEPS) |
| 603 |
|
| 604 |
|
| 605 |
def create(env_dir, system_site_packages=False, clear=False, |
| 606 |
symlinks=False, with_pip=False, prompt=None, upgrade_deps=False, |
| 607 |
*, scm_ignore_files=frozenset()): |
| 608 |
"""Create a virtual environment in a directory.""" |
| 609 |
builder = EnvBuilder(system_site_packages=system_site_packages, |
| 610 |
clear=clear, symlinks=symlinks, with_pip=with_pip, |
| 611 |
prompt=prompt, upgrade_deps=upgrade_deps, |
| 612 |
scm_ignore_files=scm_ignore_files) |
| 613 |
builder.create(env_dir) |
| 614 |
|
| 615 |
|
| 616 |
def main(args=None): |
| 617 |
import argparse |
| 618 |
|
| 619 |
parser = argparse.ArgumentParser(description='Creates virtual Python ' |
| 620 |
'environments in one or ' |
| 621 |
'more target ' |
| 622 |
'directories.', |
| 623 |
epilog='Once an environment has been ' |
| 624 |
'created, you may wish to ' |
| 625 |
'activate it, e.g. by ' |
| 626 |
'sourcing an activate script ' |
| 627 |
'in its bin directory.', |
| 628 |
color=True, |
| 629 |
) |
| 630 |
parser.add_argument('dirs', metavar='ENV_DIR', nargs='+', |
| 631 |
help='A directory to create the environment in.') |
| 632 |
parser.add_argument('--system-site-packages', default=False, |
| 633 |
action='store_true', dest='system_site', |
| 634 |
help='Give the virtual environment access to the ' |
| 635 |
'system site-packages dir.') |
| 636 |
if os.name == 'nt': |
| 637 |
use_symlinks = False |
| 638 |
else: |
| 639 |
use_symlinks = True |
| 640 |
group = parser.add_mutually_exclusive_group() |
| 641 |
group.add_argument('--symlinks', default=use_symlinks, |
| 642 |
action='store_true', dest='symlinks', |
| 643 |
help='Try to use symlinks rather than copies, ' |
| 644 |
'when symlinks are not the default for ' |
| 645 |
'the platform.') |
| 646 |
group.add_argument('--copies', default=not use_symlinks, |
| 647 |
action='store_false', dest='symlinks', |
| 648 |
help='Try to use copies rather than symlinks, ' |
| 649 |
'even when symlinks are the default for ' |
| 650 |
'the platform.') |
| 651 |
parser.add_argument('--clear', default=False, action='store_true', |
| 652 |
dest='clear', help='Delete the contents of the ' |
| 653 |
'environment directory if it ' |
| 654 |
'already exists, before ' |
| 655 |
'environment creation.') |
| 656 |
parser.add_argument('--upgrade', default=False, action='store_true', |
| 657 |
dest='upgrade', help='Upgrade the environment ' |
| 658 |
'directory to use this version ' |
| 659 |
'of Python, assuming Python ' |
| 660 |
'has been upgraded in-place.') |
| 661 |
parser.add_argument('--without-pip', dest='with_pip', |
| 662 |
default=True, action='store_false', |
| 663 |
help='Skips installing or upgrading pip in the ' |
| 664 |
'virtual environment (pip is bootstrapped ' |
| 665 |
'by default)') |
| 666 |
parser.add_argument('--prompt', |
| 667 |
help='Provides an alternative prompt prefix for ' |
| 668 |
'this environment.') |
| 669 |
parser.add_argument('--upgrade-deps', default=False, action='store_true', |
| 670 |
dest='upgrade_deps', |
| 671 |
help=f'Upgrade core dependencies ({", ".join(CORE_VENV_DEPS)}) ' |
| 672 |
'to the latest version in PyPI') |
| 673 |
parser.add_argument('--without-scm-ignore-files', dest='scm_ignore_files', |
| 674 |
action='store_const', const=frozenset(), |
| 675 |
default=frozenset(['git']), |
| 676 |
help='Skips adding SCM ignore files to the environment ' |
| 677 |
'directory (Git is supported by default).') |
| 678 |
options = parser.parse_args(args) |
| 679 |
if options.upgrade and options.clear: |
| 680 |
raise ValueError('you cannot supply --upgrade and --clear together.') |
| 681 |
builder = EnvBuilder(system_site_packages=options.system_site, |
| 682 |
clear=options.clear, |
| 683 |
symlinks=options.symlinks, |
| 684 |
upgrade=options.upgrade, |
| 685 |
with_pip=options.with_pip, |
| 686 |
prompt=options.prompt, |
| 687 |
upgrade_deps=options.upgrade_deps, |
| 688 |
scm_ignore_files=options.scm_ignore_files) |
| 689 |
for d in options.dirs: |
| 690 |
builder.create(d) |
| 691 |
|
| 692 |
|
| 693 |
if __name__ == '__main__': |
| 694 |
rc = 1 |
| 695 |
try: |
| 696 |
main() |
| 697 |
rc = 0 |
| 698 |
except Exception as e: |
| 699 |
print('Error: %s' % e, file=sys.stderr) |
| 700 |
sys.exit(rc) |