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

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

Виртуальные среды создаются путем выполнения модуля venv:

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

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

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

PS> python -m venv C:\path\to\new\virtual\environment

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

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
            [--without-scm-ignore-files]
            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.

options:
  -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) to the latest
                        version in PyPI
  --without-scm-ignore-files
                        Skips adding SCM ignore files to the environment
                        directory (Git is supported by default).

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

PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Созданный файл 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, *, scm_ignore_files=frozenset())

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

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

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

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

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

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

EnvBuilder может использоваться в качестве базового класса.

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 - Путь к заголовочным файлам виртуальной среды.
• 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.11: Используется схема установки sysconfig для построения путей созданных директорий.

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

create_configuration(context)

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

setup_python(context)

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

setup_scripts(context)

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

upgrade_dependencies(context)

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

Добавлен в версии 3.9.

Изменено в версии 3.12: setuptools больше не является основной зависимостью venv.

post_setup(context)

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

install_scripts(context, path)

Этот метод можно вызвать из setup_scripts() или post_setup() в подклассах для помощи в установке пользовательских скриптов в виртуальную среду.

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

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

Разрешается существование директорий (для случаев обновления существующей среды).

create_git_ignore_file(context)

Создаёт файл .gitignore в виртуальной среде, который заставляет менеджер контроля версий Git игнорировать весь каталог.

Добавлена в версии 3.13.

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

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

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

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

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

Добавлена в версии 3.3.

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

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

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

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

Пример расширения 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://bootstrap.pypa.io/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):
    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)

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