__init__.py 18.4 KB
Newer Older
1 2 3
"""
Virtual environment (venv) package for Python. Based on PEP 405.

4
Copyright (C) 2011-2014 Vinay Sajip.
5
Licensed to the PSF under a contributor agreement.
6
"""
7 8 9
import logging
import os
import shutil
10
import subprocess
11
import sys
12
import sysconfig
13
import types
14 15 16 17 18 19 20

logger = logging.getLogger(__name__)


class EnvBuilder:
    """
    This class exists to allow virtual environment creation to be
21
    customized. The constructor parameters determine the builder's
22 23 24
    behaviour when called upon to create a virtual environment.

    By default, the builder makes the system (global) site-packages dir
25
    *un*available to the created environment.
26

27 28 29
    If invoked using the Python -m option, the default is to use copying
    on Windows platforms but symlinks elsewhere. If instantiated some
    other way, the default is to *not* use symlinks.
30 31 32

    :param system_site_packages: If True, the system (global) site-packages
                                 dir is available to created environments.
33 34
    :param clear: If True, delete the contents of the environment directory if
                  it already exists, before environment creation.
35 36 37
    :param symlinks: If True, attempt to symlink rather than copy files into
                     virtual environment.
    :param upgrade: If True, upgrade an existing virtual environment.
38 39
    :param with_pip: If True, ensure pip is installed in the virtual
                     environment
40
    :param prompt: Alternative terminal prefix for the environment.
41 42 43
    """

    def __init__(self, system_site_packages=False, clear=False,
44
                 symlinks=False, upgrade=False, with_pip=False, prompt=None):
45 46 47 48
        self.system_site_packages = system_site_packages
        self.clear = clear
        self.symlinks = symlinks
        self.upgrade = upgrade
49
        self.with_pip = with_pip
50
        self.prompt = prompt
51 52 53 54 55 56 57 58 59 60

    def create(self, env_dir):
        """
        Create a virtual environment in a directory.

        :param env_dir: The target directory to create an environment in.

        """
        env_dir = os.path.abspath(env_dir)
        context = self.ensure_directories(env_dir)
61 62 63 64
        # See issue 24875. We need system_site_packages to be False
        # until after pip is installed.
        true_system_site_packages = self.system_site_packages
        self.system_site_packages = False
65 66
        self.create_configuration(context)
        self.setup_python(context)
67 68
        if self.with_pip:
            self._setup_pip(context)
69 70 71
        if not self.upgrade:
            self.setup_scripts(context)
            self.post_setup(context)
72 73 74 75 76
        if true_system_site_packages:
            # We had set it to False before, now
            # restore it and rewrite the configuration
            self.system_site_packages = True
            self.create_configuration(context)
77

78 79 80 81 82 83 84 85
    def clear_directory(self, path):
        for fn in os.listdir(path):
            fn = os.path.join(path, fn)
            if os.path.islink(fn) or os.path.isfile(fn):
                os.remove(fn)
            elif os.path.isdir(fn):
                shutil.rmtree(fn)

86 87 88 89 90 91 92 93 94 95 96
    def ensure_directories(self, env_dir):
        """
        Create the directories for the environment.

        Returns a context object which holds paths in the environment,
        for use by subsequent logic.
        """

        def create_if_needed(d):
            if not os.path.exists(d):
                os.makedirs(d)
97 98
            elif os.path.islink(d) or os.path.isfile(d):
                raise ValueError('Unable to create directory %r' % d)
99 100

        if os.path.exists(env_dir) and self.clear:
101
            self.clear_directory(env_dir)
102
        context = types.SimpleNamespace()
103 104
        context.env_dir = env_dir
        context.env_name = os.path.split(env_dir)[1]
105 106
        prompt = self.prompt if self.prompt is not None else context.env_name
        context.prompt = '(%s) ' % prompt
107 108
        create_if_needed(env_dir)
        env = os.environ
109 110
        if sys.platform == 'darwin' and '__PYVENV_LAUNCHER__' in env:
            executable = os.environ['__PYVENV_LAUNCHER__']
111 112 113 114 115 116 117 118 119 120 121 122 123
        else:
            executable = sys.executable
        dirname, exename = os.path.split(os.path.abspath(executable))
        context.executable = executable
        context.python_dir = dirname
        context.python_exe = exename
        if sys.platform == 'win32':
            binname = 'Scripts'
            incpath = 'Include'
            libpath = os.path.join(env_dir, 'Lib', 'site-packages')
        else:
            binname = 'bin'
            incpath = 'include'
124 125 126
            libpath = os.path.join(env_dir, 'lib',
                                   'python%d.%d' % sys.version_info[:2],
                                   'site-packages')
127 128 129
        context.inc_path = path = os.path.join(env_dir, incpath)
        create_if_needed(path)
        create_if_needed(libpath)
130
        # Issue 21197: create lib64 as a symlink to lib on 64-bit non-OS X POSIX
131
        if ((sys.maxsize > 2**32) and (os.name == 'posix') and
132 133
            (sys.platform != 'darwin')):
            link_path = os.path.join(env_dir, 'lib64')
134
            if not os.path.exists(link_path):   # Issue #21643
135
                os.symlink('lib', link_path)
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168
        context.bin_path = binpath = os.path.join(env_dir, binname)
        context.bin_name = binname
        context.env_exe = os.path.join(binpath, exename)
        create_if_needed(binpath)
        return context

    def create_configuration(self, context):
        """
        Create a configuration file indicating where the environment's Python
        was copied from, and whether the system site-packages should be made
        available in the environment.

        :param context: The information for the environment creation request
                        being processed.
        """
        context.cfg_path = path = os.path.join(context.env_dir, 'pyvenv.cfg')
        with open(path, 'w', encoding='utf-8') as f:
            f.write('home = %s\n' % context.python_dir)
            if self.system_site_packages:
                incl = 'true'
            else:
                incl = 'false'
            f.write('include-system-site-packages = %s\n' % incl)
            f.write('version = %d.%d.%d\n' % sys.version_info[:3])

    if os.name == 'nt':
        def include_binary(self, f):
            if f.endswith(('.pyd', '.dll')):
                result = True
            else:
                result = f.startswith('python') and f.endswith('.exe')
            return result

169
    def symlink_or_copy(self, src, dst, relative_symlinks_ok=False):
170 171 172 173 174 175 176
        """
        Try symlinking a file, and if that fails, fall back to copying.
        """
        force_copy = not self.symlinks
        if not force_copy:
            try:
                if not os.path.islink(dst): # can't link to itself!
177 178 179 180 181
                    if relative_symlinks_ok:
                        assert os.path.dirname(src) == os.path.dirname(dst)
                        os.symlink(os.path.basename(src), dst)
                    else:
                        os.symlink(src, dst)
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
            except Exception:   # may need to use a more specific exception
                logger.warning('Unable to symlink %r to %r', src, dst)
                force_copy = True
        if force_copy:
            shutil.copyfile(src, dst)

    def setup_python(self, context):
        """
        Set up a Python executable in the environment.

        :param context: The information for the environment creation request
                        being processed.
        """
        binpath = context.bin_path
        path = context.env_exe
        copier = self.symlink_or_copy
        copier(context.executable, path)
        dirname = context.python_dir
        if os.name != 'nt':
            if not os.path.islink(path):
                os.chmod(path, 0o755)
203 204 205
            for suffix in ('python', 'python3'):
                path = os.path.join(binpath, suffix)
                if not os.path.exists(path):
206 207
                    # Issue 18807: make copies if
                    # symlinks are not wanted
208
                    copier(context.env_exe, path, relative_symlinks_ok=True)
209 210
                    if not os.path.islink(path):
                        os.chmod(path, 0o755)
211 212 213 214
        elif sysconfig.is_python_build(True):
            # See bpo-34011. This copying code should only be needed when a
            # venv is created from a source Python build (i.e. not an installed
            # Python)
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
            subdir = 'DLLs'
            include = self.include_binary
            files = [f for f in os.listdir(dirname) if include(f)]
            for f in files:
                src = os.path.join(dirname, f)
                dst = os.path.join(binpath, f)
                if dst != context.env_exe:  # already done, above
                    copier(src, dst)
            dirname = os.path.join(dirname, subdir)
            if os.path.isdir(dirname):
                files = [f for f in os.listdir(dirname) if include(f)]
                for f in files:
                    src = os.path.join(dirname, f)
                    dst = os.path.join(binpath, f)
                    copier(src, dst)
            # copy init.tcl over
            for root, dirs, files in os.walk(context.python_dir):
                if 'init.tcl' in files:
                    tcldir = os.path.basename(root)
                    tcldir = os.path.join(context.env_dir, 'Lib', tcldir)
235 236
                    if not os.path.exists(tcldir):
                        os.makedirs(tcldir)
237 238 239 240 241
                    src = os.path.join(root, 'init.tcl')
                    dst = os.path.join(tcldir, 'init.tcl')
                    shutil.copyfile(src, dst)
                    break

242 243
    def _setup_pip(self, context):
        """Installs or upgrades pip in a virtual environment"""
244 245 246
        # We run ensurepip in isolated mode to avoid side effects from
        # environment vars, the current directory and anything else
        # intended for the global Python environment
247
        cmd = [context.env_exe, '-Im', 'ensurepip', '--upgrade',
248
                                                    '--default-pip']
249
        subprocess.check_output(cmd, stderr=subprocess.STDOUT)
250

251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287
    def setup_scripts(self, context):
        """
        Set up scripts into the created environment from a directory.

        This method installs the default scripts into the environment
        being created. You can prevent the default installation by overriding
        this method if you really need to, or if you need to specify
        a different location for the scripts to install. By default, the
        'scripts' directory in the venv package is used as the source of
        scripts to install.
        """
        path = os.path.abspath(os.path.dirname(__file__))
        path = os.path.join(path, 'scripts')
        self.install_scripts(context, path)

    def post_setup(self, context):
        """
        Hook for post-setup modification of the venv. Subclasses may install
        additional packages or scripts here, add activation shell scripts, etc.

        :param context: The information for the environment creation request
                        being processed.
        """
        pass

    def replace_variables(self, text, context):
        """
        Replace variable placeholders in script text with context-specific
        variables.

        Return the text passed in , but with variables replaced.

        :param text: The text in which to replace placeholder variables.
        :param context: The information for the environment creation request
                        being processed.
        """
        text = text.replace('__VENV_DIR__', context.env_dir)
288 289
        text = text.replace('__VENV_NAME__', context.env_name)
        text = text.replace('__VENV_PROMPT__', context.prompt)
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
        text = text.replace('__VENV_BIN_NAME__', context.bin_name)
        text = text.replace('__VENV_PYTHON__', context.env_exe)
        return text

    def install_scripts(self, context, path):
        """
        Install scripts into the created environment from a directory.

        :param context: The information for the environment creation request
                        being processed.
        :param path:    Absolute pathname of a directory containing script.
                        Scripts in the 'common' subdirectory of this directory,
                        and those in the directory named for the platform
                        being run on, are installed in the created environment.
                        Placeholder variables are replaced with environment-
                        specific values.
        """
        binpath = context.bin_path
        plen = len(path)
        for root, dirs, files in os.walk(path):
            if root == path: # at top-level, remove irrelevant dirs
                for d in dirs[:]:
                    if d not in ('common', os.name):
                        dirs.remove(d)
                continue # ignore files in top level
            for f in files:
                srcfile = os.path.join(root, f)
                suffix = root[plen:].split(os.sep)[2:]
                if not suffix:
                    dstdir = binpath
                else:
                    dstdir = os.path.join(binpath, *suffix)
                if not os.path.exists(dstdir):
                    os.makedirs(dstdir)
                dstfile = os.path.join(dstdir, f)
                with open(srcfile, 'rb') as f:
                    data = f.read()
327
                if not srcfile.endswith('.exe'):
328 329 330
                    try:
                        data = data.decode('utf-8')
                        data = self.replace_variables(data, context)
331 332
                        data = data.encode('utf-8')
                    except UnicodeError as e:
333 334 335 336
                        data = None
                        logger.warning('unable to copy script %r, '
                                       'may be binary: %s', srcfile, e)
                if data is not None:
337
                    with open(dstfile, 'wb') as f:
338 339
                        f.write(data)
                    shutil.copymode(srcfile, dstfile)
340 341


342
def create(env_dir, system_site_packages=False, clear=False,
343
                    symlinks=False, with_pip=False, prompt=None):
344
    """Create a virtual environment in a directory."""
345
    builder = EnvBuilder(system_site_packages=system_site_packages,
346 347
                         clear=clear, symlinks=symlinks, with_pip=with_pip,
                         prompt=prompt)
348 349 350 351 352 353 354 355 356
    builder.create(env_dir)

def main(args=None):
    compatible = True
    if sys.version_info < (3, 3):
        compatible = False
    elif not hasattr(sys, 'base_prefix'):
        compatible = False
    if not compatible:
357
        raise ValueError('This script is only for use with Python >= 3.3')
358 359 360 361 362 363 364
    else:
        import argparse

        parser = argparse.ArgumentParser(prog=__name__,
                                         description='Creates virtual Python '
                                                     'environments in one or '
                                                     'more target '
365 366 367 368 369 370
                                                     'directories.',
                                         epilog='Once an environment has been '
                                                'created, you may wish to '
                                                'activate it, e.g. by '
                                                'sourcing an activate script '
                                                'in its bin directory.')
371 372 373 374
        parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
                            help='A directory to create the environment in.')
        parser.add_argument('--system-site-packages', default=False,
                            action='store_true', dest='system_site',
375 376
                            help='Give the virtual environment access to the '
                                 'system site-packages dir.')
377
        if os.name == 'nt':
378 379 380
            use_symlinks = False
        else:
            use_symlinks = True
381 382 383 384 385 386 387 388 389 390 391
        group = parser.add_mutually_exclusive_group()
        group.add_argument('--symlinks', default=use_symlinks,
                           action='store_true', dest='symlinks',
                           help='Try to use symlinks rather than copies, '
                                'when symlinks are not the default for '
                                'the platform.')
        group.add_argument('--copies', default=not use_symlinks,
                           action='store_false', dest='symlinks',
                           help='Try to use copies rather than symlinks, '
                                'even when symlinks are the default for '
                                'the platform.')
392
        parser.add_argument('--clear', default=False, action='store_true',
393 394 395 396
                            dest='clear', help='Delete the contents of the '
                                               'environment directory if it '
                                               'already exists, before '
                                               'environment creation.')
397 398 399
        parser.add_argument('--upgrade', default=False, action='store_true',
                            dest='upgrade', help='Upgrade the environment '
                                               'directory to use this version '
400 401
                                               'of Python, assuming Python '
                                               'has been upgraded in-place.')
402 403 404 405 406
        parser.add_argument('--without-pip', dest='with_pip',
                            default=True, action='store_false',
                            help='Skips installing or upgrading pip in the '
                                 'virtual environment (pip is bootstrapped '
                                 'by default)')
407 408 409
        parser.add_argument('--prompt',
                            help='Provides an alternative prompt prefix for '
                                 'this environment.')
410 411 412
        options = parser.parse_args(args)
        if options.upgrade and options.clear:
            raise ValueError('you cannot supply --upgrade and --clear together.')
413
        builder = EnvBuilder(system_site_packages=options.system_site,
414 415 416
                             clear=options.clear,
                             symlinks=options.symlinks,
                             upgrade=options.upgrade,
417 418
                             with_pip=options.with_pip,
                             prompt=options.prompt)
419 420 421 422 423 424 425 426 427 428 429
        for d in options.dirs:
            builder.create(d)

if __name__ == '__main__':
    rc = 1
    try:
        main()
        rc = 0
    except Exception as e:
        print('Error: %s' % e, file=sys.stderr)
    sys.exit(rc)