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

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

Создание virtual environments осуществляется путем выполнения команды 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 installation:

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, для начальной загрузки pip в виртуальную среду будет вызван параметр ensurepip.

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

Как работают venvs¶

Когда интерпретатор 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, который предоставляет сторонним создателям виртуальной среды механизмы для настройки создания среды в соответствии с их потребностями, класс 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 – логическое значение, указывающее, что системные пакеты сайта Python должны быть доступны для среды (по умолчанию используется значение False).

• clear – логическое значение, которое, если оно равно true, приведет к удалению содержимого любого существующего целевого каталога перед созданием среды.

• symlinks – логическое значение, указывающее, следует ли пытаться использовать символическую ссылку на двоичный файл Python вместо копирования.

• upgrade – логическое значение, которое, если оно равно true, обновит существующую среду с помощью запущенного Python - для использования, когда этот Python был обновлен на месте (по умолчанию используется значение False).

• with_pip – логическое значение, которое, если оно равно true, гарантирует, что 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 - Путь включения для виртуальной среды.

• lib_path - чистый libpath для виртуальной среды.

• bin_path - Путь к скрипту для виртуальной среды.

• bin_name - Имя пути к скрипту относительно местоположения виртуальной среды. Используется для __VENV_BIN_NAME__ в сценариях активации (см. install_scripts()).

• env_exe - Имя интерпретатора Python в виртуальной среде. Используется для __VENV_PYTHON__ в сценариях активации (см. install_scripts()).

• env_exec_cmd - Имя интерпретатора Python, учитывающее перенаправления файловой системы. Это можно использовать для запуска Python в виртуальной среде.

Изменено в версии 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)¶

Обновляет основные пакеты зависимостей 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)

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