venv — Создание виртуальных сред

Создание виртуальных сред

Создание виртуальных сред выполняется путём выполнения команды venv:

python -m venv /path/to/new/virtual/environment

Выполнение этой команды создаёт целевую директорию (создавая любые родительские директории, которых ещё нет) и помещает в неё файл pyvenv.cfg с ключом home, указывающим на установку Python, из которой была запущена команда (общее название для целевой директории — .venv). Она также создаёт поддиректорию bin (или Scripts в Windows), содержащую копию/символическую ссылку на бинарный файл(ы) Python (соответствующую платформе или аргументам, использованным при создании среды). Также создаётся поддиректорию lib/pythonX.Y/site-packages (в Windows это Lib\site-packages). Если задана существующая директория, она будет повторно использована.

В Windows, вызовите команду venv следующим образом:

c:\>c:\Python35\python -m venv c:\path\to\myenv

В качестве альтернативы, если вы настроили переменные PATH и PATHEXT для вашей установки Python:

c:\>python -m venv c:\path\to\myenv

Команда, если запущена с -h, покажет доступные опции:

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
            ENV_DIR [ENV_DIR ...]

Creates virtual Python environments in one or more target directories.

positional arguments:
  ENV_DIR               A directory to create the environment in.

optional arguments:
  -h, --help            show this help message and exit
  --system-site-packages
                        Give the virtual environment access to the system
                        site-packages dir.
  --symlinks            Try to use symlinks rather than copies, when symlinks
                        are not the default for the platform.
  --copies              Try to use copies rather than symlinks, even when
                        symlinks are the default for the platform.
  --clear               Delete the contents of the environment directory if it
                        already exists, before environment creation.
  --upgrade             Upgrade the environment directory to use this version
                        of Python, assuming Python has been upgraded in-place.
  --without-pip         Skips installing or upgrading pip in the virtual
                        environment (pip is bootstrapped by default)
  --prompt PROMPT       Provides an alternative prompt prefix for this
                        environment.
  --upgrade-deps        Upgrade core dependencies: pip setuptools to the
                        latest version in PyPI

Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.

Созданный файл pyvenv.cfg также включает ключ include-system-site-packages, установленный на true если venv запущен с опцией --system-site-packages, и false в противном случае.

Если опция --without-pip не задана, ensurepip будет вызван для инициализации pip в виртуальной среде.

Можно указать несколько путей для venv, в таком случае идентичная виртуальная среда будет создана по заданным параметрам в каждом указанном пути.

Как работают venv

Когда интерпретатор Python запускается из виртуальной среды, sys.prefix и sys.exec_prefix указывают на директории виртуальной среды, в то время как sys.base_prefix и sys.base_exec_prefix указывают на директории базового Python, использованного для создания среды. Достаточно проверить sys.prefix == sys.base_prefix для определения, запущен ли текущий интерпретатор из виртуальной среды.

Виртуальную среду можно «активировать», используя скрипт в её директории бинарных файлов (bin в POSIX; Scripts в Windows). Это добавит эту директорию в ваш PATH, так что запуск python вызовет интерпретатор Python среды, и вы сможете запускать установленные скрипты без указания полного пути. Вызов скрипта активации зависит от платформы (<venv> должен быть заменён на путь к директории, содержащей виртуальную среду):

Вам не обязательно активировать виртуальную среду, вы можете просто указать полный путь к интерпретатору Python этой среды при запуске Python. Кроме того, все скрипты, установленные в среде, должны выполняться без её активации.

Для этого скрипты, установленные в виртуальные среды, имеют строку «shebang», которая указывает на интерпретатор Python среды, например #!/<path-to-venv>/bin/python. Это означает, что скрипт будет выполняться с этим интерпретатором независимо от значения PATH. В Windows обработка строк «shebang» поддерживается, если установлен Загрузчик Python для Windows. Таким образом, двойной щелчок по установленным скриптам в окне Проводника Windows должен запустить их с правильным интерпретатором без необходимости активации среды или нахождения на PATH.

Когда виртуальная среда активирована, переменная среды VIRTUAL_ENV устанавливается в путь среды. Поскольку явная активация виртуальной среды не требуется для её использования, нельзя полагаться на VIRTUAL_ENV для определения использования виртуальной среды.

Вы можете деактивировать виртуальную среду, набрав deactivate в своей оболочке. Точный механизм зависит от платформы и является внутренней реализацией (как правило, используется скрипт или функция оболочки).

API

Вышеописанный метод высокого уровня использует простой API, который предоставляет механизмы для сторонних создателей виртуальных сред для настройки создания среды в соответствии с их потребностями, класс EnvBuilder.

class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False)

Класс EnvBuilder принимает следующие ключевые аргументы при создании:

• system_site_packages – логическое значение, указывающее, что системный каталог site-packages Python должен быть доступен в среде (по умолчанию False).
• clear – логическое значение, которое, если истинно, удалит содержимое любого существующего целевого каталога перед созданием среды.
• symlinks – логическое значение, указывающее, следует ли пытаться создать символическую ссылку на бинарник Python, а не копировать его.
• upgrade – логическое значение, которое, если истинно, обновит существующую среду с текущим Python — для использования в случае, если этот Python был обновлён на месте (по умолчанию False).
• with_pip – логическое значение, которое, если истинно, гарантирует установку pip в виртуальной среде. Это использует ensurepip с опцией --default-pip.
• prompt – строка, используемая после активации виртуальной среды (по умолчанию None , что означает, что будет использоваться имя каталога среды). Если предоставлена специальная строка ".", в качестве приглашения используется имя файла текущего каталога.
• upgrade_deps – обновление базовых модулей venv до последних версий на PyPI

Изменено в версии 3.4: Добавлен параметр with_pip

Введено в версии 3.6: Добавлен параметр prompt

Введено в версии 3.9: Добавлен параметр upgrade_deps

Создатели сторонних инструментов виртуальной среды могут использовать предоставленный класс EnvBuilder в качестве базового класса.

Возвращаемый объект env-builder имеет метод create:

create(env_dir)

Создаёт виртуальную среду, указав целевой каталог (абсолютный или относительный к текущему каталогу), который должен содержать виртуальную среду. Метод create создаст среду в указанном каталоге или вызовет соответствующее исключение.

Метод create класса EnvBuilder демонстрирует доступные хуки для настройки подклассов:

def create(self, env_dir):
    """
    Create a virtualized Python environment in a directory.
    env_dir is the target directory to create an environment in.
    """
    env_dir = os.path.abspath(env_dir)
    context = self.ensure_directories(env_dir)
    self.create_configuration(context)
    self.setup_python(context)
    self.setup_scripts(context)
    self.post_setup(context)

Каждый из методов ensure_directories(), create_configuration(), setup_python(), setup_scripts() и post_setup() может быть переопределён.

ensure_directories(env_dir)

Создаёт каталог среды и все необходимые подкаталоги, которые ещё не существуют, и возвращает объект контекста. Этот объект контекста — просто контейнер для атрибутов (таких как пути), используемых другими методами. Если EnvBuilder создаётся с аргументом clear=True, содержимое каталога среды будет очищено, а затем будут воссозданы все необходимые подкаталоги.

Возвращаемый объект контекста — types.SimpleNamespace со следующими атрибутами:

• env_dir - Путь к виртуальной среде. Используется для __VENV_DIR__ в скриптах активации (см. install_scripts()).
• env_name - Имя виртуальной среды. Используется для __VENV_NAME__ в скриптах активации (см. install_scripts()).
• prompt - Приглашение, используемое скриптами активации. Используется для __VENV_PROMPT__ в скриптах активации (см. install_scripts()).
• executable - Базовый исполняемый файл Python, используемый виртуальной средой. Это учитывает случай, когда виртуальная среда создаётся из другой виртуальной среды.
• inc_path - Путь к заголовкам (include) для виртуальной среды.
• lib_path - Путь к purelib для виртуальной среды.
• bin_path - Путь к скриптам для виртуальной среды.
• bin_name - Имя пути к скриптам, относительно расположения виртуальной среды. Используется для __VENV_BIN_NAME__ в скриптах активации (см. install_scripts()).
• env_exe - Имя интерпретатора Python в виртуальной среде. Используется для __VENV_PYTHON__ в скриптах активации (см. install_scripts()).
• env_exec_cmd - Имя интерпретатора Python с учётом перенаправлений файловой системы. Это можно использовать для запуска Python в виртуальной среде.

Изменено в версии 3.12: Добавлен атрибут lib_path в контекст, и был документирован объект контекста.

Изменено в версии 3.11: Используется схема установки venv sysconfig installation scheme для построения путей созданных каталогов.

create_configuration(context)

Создаёт конфигурационный файл pyvenv.cfg в среде.

setup_python(context)

Создаёт копию или символическую ссылку на исполняемый файл Python в среде. В системах POSIX, если был использован конкретный исполняемый файл python3.x, будут созданы символические ссылки на python и python3, указывающие на этот исполняемый файл, если файлы с такими именами ещё не существуют.

setup_scripts(context)

Устанавливает скрипты активации, соответствующие платформе, в виртуальную среду.

upgrade_dependencies(context)

Обновляет пакеты зависимостей core venv (в настоящее время pip и setuptools) в среде. Это выполняется с помощью исполняемого файла pip в среде.

Введено в версии 3.9.

post_setup(context)

Заполнитель метода, который можно переопределить в сторонних реализациях, чтобы предварительно установить пакеты в виртуальной среде или выполнить другие шаги после создания.

Изменено в версии 3.7.2: Windows теперь использует скрипты перенаправления для python[w].exe вместо копирования фактических бинарных файлов. В 3.7.2 только setup_python() ничего не делает, если выполняется из сборки в дереве исходного кода.

Изменено в версии 3.7.3: Windows копирует скрипты перенаправления в рамках setup_python() вместо setup_scripts(). Это не было так в 3.7.2. При использовании символических ссылок исходные исполняемые файлы будут сохранены.

Кроме того, EnvBuilder предоставляет этот утилитарный метод, который можно вызывать из setup_scripts() или post_setup() в подклассах, чтобы помочь в установке пользовательских скриптов в виртуальную среду.

install_scripts(context, path)

path — путь к каталогу, который должен содержать подкаталоги “common”, “posix”, “nt”, каждый из которых содержит скрипты, предназначенные для каталога bin в среде. Содержимое “common” и каталога, соответствующего os.name, копируются после замены некоторых текстовых заглушек:

• __VENV_DIR__ заменяется абсолютным путём каталога среды.
• __VENV_NAME__ заменяется именем среды (конечный сегмент пути каталога среды).
• __VENV_PROMPT__ заменяется приглашением (имя среды в скобках с последующим пробелом).
• __VENV_BIN_NAME__ заменяется именем каталога bin (либо bin , либо Scripts).
• __VENV_PYTHON__ заменяется абсолютным путём исполняемого файла среды.

Допускается существование каталогов (для случаев обновления существующей среды).

Также имеется функция удобства на уровне модуля:

venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None, upgrade_deps=False)

Создайте EnvBuilder с заданными ключевыми аргументами и вызовите его метод create() с аргументом env_dir.

Введено в версии 3.3.

Изменено в версии 3.4: Добавлен параметр with_pip

Изменено в версии 3.6: Добавлен параметр prompt

Изменено в версии 3.9: Добавлен параметр upgrade_deps

Пример расширения EnvBuilder

Следующий скрипт демонстрирует, как расширить EnvBuilder, реализовав подкласс, который устанавливает setuptools и pip в созданную виртуальную среду:

import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlparse
from urllib.request import urlretrieve
import venv

class ExtendedEnvBuilder(venv.EnvBuilder):
    """
    This builder installs setuptools and pip so that you can pip or
    easy_install other packages into the created virtual environment.

    :param nodist: If true, setuptools and pip are not installed into the
                   created virtual environment.
    :param nopip: If true, pip is not installed into the created
                  virtual environment.
    :param progress: If setuptools or pip are installed, the progress of the
                     installation can be monitored by passing a progress
                     callable. If specified, it is called with two
                     arguments: a string indicating some progress, and a
                     context indicating where the string is coming from.
                     The context argument can have one of three values:
                     'main', indicating that it is called from virtualize()
                     itself, and 'stdout' and 'stderr', which are obtained
                     by reading lines from the output streams of a subprocess
                     which is used to install the app.

                     If a callable is not specified, default progress
                     information is output to sys.stderr.
    """

    def __init__(self, *args, **kwargs):
        self.nodist = kwargs.pop('nodist', False)
        self.nopip = kwargs.pop('nopip', False)
        self.progress = kwargs.pop('progress', None)
        self.verbose = kwargs.pop('verbose', False)
        super().__init__(*args, **kwargs)

    def post_setup(self, context):
        """
        Set up any packages which need to be pre-installed into the
        virtual environment being created.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        os.environ['VIRTUAL_ENV'] = context.env_dir
        if not self.nodist:
            self.install_setuptools(context)
        # Can't install pip without setuptools
        if not self.nopip and not self.nodist:
            self.install_pip(context)

    def reader(self, stream, context):
        """
        Read lines from a subprocess' output stream and either pass to a progress
        callable (if specified) or write progress information to sys.stderr.
        """
        progress = self.progress
        while True:
            s = stream.readline()
            if not s:
                break
            if progress is not None:
                progress(s, context)
            else:
                if not self.verbose:
                    sys.stderr.write('.')
                else:
                    sys.stderr.write(s.decode('utf-8'))
                sys.stderr.flush()
        stream.close()

    def install_script(self, context, name, url):
        _, _, path, _, _, _ = urlparse(url)
        fn = os.path.split(path)[-1]
        binpath = context.bin_path
        distpath = os.path.join(binpath, fn)
        # Download script into the virtual environment's binaries folder
        urlretrieve(url, distpath)
        progress = self.progress
        if self.verbose:
            term = '\n'
        else:
            term = ''
        if progress is not None:
            progress('Installing %s ...%s' % (name, term), 'main')
        else:
            sys.stderr.write('Installing %s ...%s' % (name, term))
            sys.stderr.flush()
        # Install in the virtual environment
        args = [context.env_exe, fn]
        p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
        t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
        t1.start()
        t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))
        t2.start()
        p.wait()
        t1.join()
        t2.join()
        if progress is not None:
            progress('done.', 'main')
        else:
            sys.stderr.write('done.\n')
        # Clean up - no longer needed
        os.unlink(distpath)

    def install_setuptools(self, context):
        """
        Install setuptools in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'
        self.install_script(context, 'setuptools', url)
        # clear up the setuptools archive which gets downloaded
        pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')
        files = filter(pred, os.listdir(context.bin_path))
        for f in files:
            f = os.path.join(context.bin_path, f)
            os.unlink(f)

    def install_pip(self, context):
        """
        Install pip in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://bootstrap.pypa.io/get-pip.py'
        self.install_script(context, 'pip', url)

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:
        raise ValueError('This script is only for use with '
                         'Python 3.3 or later')
    else:
        import argparse

        parser = argparse.ArgumentParser(prog=__name__,
                                         description='Creates virtual Python '
                                                     'environments in one or '
                                                     'more target '
                                                     'directories.')
        parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
                            help='A directory in which to create the '
                                 'virtual environment.')
        parser.add_argument('--no-setuptools', default=False,
                            action='store_true', dest='nodist',
                            help="Don't install setuptools or pip in the "
                                 "virtual environment.")
        parser.add_argument('--no-pip', default=False,
                            action='store_true', dest='nopip',
                            help="Don't install pip in the virtual "
                                 "environment.")
        parser.add_argument('--system-site-packages', default=False,
                            action='store_true', dest='system_site',
                            help='Give the virtual environment access to the '
                                 'system site-packages dir.')
        if os.name == 'nt':
            use_symlinks = False
        else:
            use_symlinks = True
        parser.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.')
        parser.add_argument('--clear', default=False, action='store_true',
                            dest='clear', help='Delete the contents of the '
                                               'virtual environment '
                                               'directory if it already '
                                               'exists, before virtual '
                                               'environment creation.')
        parser.add_argument('--upgrade', default=False, action='store_true',
                            dest='upgrade', help='Upgrade the virtual '
                                                 'environment directory to '
                                                 'use this version of '
                                                 'Python, assuming Python '
                                                 'has been upgraded '
                                                 'in-place.')
        parser.add_argument('--verbose', default=False, action='store_true',
                            dest='verbose', help='Display the output '
                                               'from the scripts which '
                                               'install setuptools and pip.')
        options = parser.parse_args(args)
        if options.upgrade and options.clear:
            raise ValueError('you cannot supply --upgrade and --clear together.')
        builder = ExtendedEnvBuilder(system_site_packages=options.system_site,
                                       clear=options.clear,
                                       symlinks=options.symlinks,
                                       upgrade=options.upgrade,
                                       nodist=options.nodist,
                                       nopip=options.nopip,
                                       verbose=options.verbose)
        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)

Этот скрипт также доступен для скачивания онлайн.