4. Использование Python в Windows¶Using Python on Windows

4.1.1. Установка¶Installation

Менеджер установки Python можно установить из приложения Microsoft Store или загрузить и установить с python.org/downloads. Обе версии идентичны.

Чтобы установить через Store, просто нажмите «Install». После завершения откройте терминал и введите python, чтобы начать работу.

Чтобы установить файл, загруженный с python.org, дважды щелкните и выберите «Install» или выполните Add-AppxPackage <path to MSIX> в Windows PowerShell.

После установки команды python, py и pymanager должны стать доступны. Если у вас уже есть установленные версии Python или вы изменили переменную PATH, возможно, потребуется удалить их или отменить изменения. Обратитесь к разделу Устранение неполадок за дополнительной помощью по исправлению неработающих команд.

При первой установке среды выполнения, скорее всего, будет предложено добавить каталог в переменную PATH. Это необязательно, если вы предпочитаете использовать команду py, но предлагается для тех, кто хочет, чтобы был доступен полный набор псевдонимов (например, python3.14.exe). По умолчанию каталог будет %LocalAppData%\Python\bin, но администратор может изменить его. Нажмите «Пуск» и найдите «Изменение переменных среды для вашей учетной записи» на странице параметров системы, чтобы добавить путь.

Каждая установленная среда выполнения Python будет иметь собственный каталог для скриптов. Их также необходимо добавить в PATH, если вы хотите их использовать.

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

Если вы не можете установить MSIX в вашем контексте, например, вы используете программное обеспечение для автоматического развертывания, которое не поддерживает его, или ваша целевая платформа – Windows Server 2019, обратитесь к разделу Расширенная установка ниже для получения дополнительной информации.

4.1.2. Базовое использование¶Basic use

Рекомендуемая команда для запуска Python – python. Она запустит версию, запрошенную запускаемым скриптом, активное виртуальное окружение или установленную версию по умолчанию, которая будет последней стабильной версией, если не настроено иное. Если ни одна версия явно не запрошена и среды выполнения вообще не установлены, будет автоматически установлена текущая последняя версия.

Для всех сценариев, включающих несколько версий среды выполнения, рекомендуемая команда – py. Ее можно использовать везде вместо python или старого лаунчера py.exe. По умолчанию py соответствует поведению python, но также позволяет выбирать конкретную версию с помощью параметров командной строки, а также использовать подкоманды для управления установками. Подробнее об этом ниже.

Поскольку команда py может уже использоваться предыдущей версией, существует также однозначная команда pymanager. Сценарии установки, предназначенные для использования менеджера установки Python, должны рассмотреть использование pymanager, поскольку вероятность конфликта с существующими установками ниже. Единственное различие между двумя командами – при запуске без аргументов: py запускает интерпретатор по умолчанию, а pymanager выводит справку (pymanager exec ... ведет себя так же, как py ...).

У каждой из этих команд также есть версия с окном, которая не создает окно консоли. Это pyw, pythonw и pymanagerw. Также включена команда python3, имитирующая команду python. Она предназначена для перехвата случайного использования типичной команды POSIX в Windows, но не предназначена для широкого использования или рекомендации.

Чтобы запустить среду выполнения по умолчанию, выполните python или py с аргументами, которые нужно передать среде (например, файлы скриптов или модуль для запуска):

$> py
...
$> python my-script.py
...
$> py -m this
...

Среду выполнения по умолчанию можно переопределить с помощью переменной среды PYTHON_MANAGER_DEFAULT или файла конфигурации. См. Конфигурация для получения информации о настройках конфигурации.

Чтобы запустить конкретную среду выполнения, команда py принимает опцию -V:<TAG>. Эта опция должна быть указана перед всеми остальными. Тег – это часть или полный идентификатор среды выполнения; для сред от команды CPython он выглядит как версия, возможно, с указанием платформы. Для совместимости V: может быть опущен, если тег относится к официальному релизу и начинается с 3.

$> py -V:3.14 ...
$> py -V:3-arm64 ...

Среды выполнения от других распространителей могут требовать указания компании. Она должна отделяться от тега косой чертой и может быть префиксом. Указание компании является необязательным, когда она PythonCore, а указание тега необязательно (но не косой черты), если требуется последний релиз от конкретной компании.

$> py -V:Distributor\1.0 ...
$> py -V:distrib/ ...

Если версия не указана, но передан файл скрипта, скрипт будет проверен на наличие шебанг-строки. Это специальный формат для первой строки в файле, который позволяет переопределить команду. См. Шебанг-строки для получения дополнительной информации. Если шебанг-строка отсутствует или не может быть обработана, скрипт будет запущен со средой выполнения по умолчанию.

При работе в активном виртуальном окружении, если не запрошена конкретная версия и шебанг-строка отсутствует, средой выполнения по умолчанию будет это виртуальное окружение. В этом случае команда python, скорее всего, уже была переопределена, и ни одна из этих проверок не выполнялась. Однако такое поведение гарантирует, что команду py можно использовать взаимозаменяемо.

Если ни одна среда выполнения не установлена, любая команда запуска попытается установить запрошенную версию и запустить её. Однако после установки любой версии только команды py exec ... и pymanager exec ... будут выполнять установку, если запрошенная версия отсутствует. Остальные формы команд выведут сообщение об ошибке и предложат сначала использовать py install.

4.1.3. Справка по командам¶Command help

Команда py help выводит полный список поддерживаемых команд вместе с их опциями. Любой команде можно передать опцию -? для отображения справки, или передать её имя команде py help.

$> py help
$> py help install
$> py install /?

Все команды поддерживают некоторые общие опции, которые будут отображены командой py help. Эти опции должны указываться после любой подкоманды. Указание -v или --verbose увеличивает объём выводимых данных, а -vv ещё больше увеличивает его для целей отладки. Передача -q или --quiet уменьшает вывод, а -qq уменьшает его ещё сильнее.

Опция --config=<PATH> позволяет указать файл конфигурации для одновременного переопределения нескольких настроек. См. Конфигурация ниже для получения дополнительной информации об этих файлах.

4.1.4. Список сред выполнения¶Listing runtimes

$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]

Список установленных сред выполнения можно просмотреть с помощью py list. Можно добавить фильтр в виде одного или нескольких тегов (с указанием компании или без), и каждый может включать префикс <, <=, >= или > для ограничения диапазона.

Поддерживается несколько форматов, которые можно передать в качестве опции --format=<FMT> или -f <FMT>. Форматы включают table (удобный для пользователя табличный вид), csv (таблица с разделителями-запятыми), json (один JSON-объект), jsonl (по одному JSON-объекту на результат), exe (только путь к исполняемому файлу), prefix (только путь к префиксу).

Опция --one или -1 отображает только один результат. Если в результаты включена среда выполнения по умолчанию, то будет показана она. В противном случае отображается «лучший» результат («лучший» намеренно определён расплывчато, но обычно это самая последняя версия). Результат, показываемый командой py list --one <TAG>, будет соответствовать среде выполнения, которая была бы запущена командой py -V:<TAG>.

Опция --only-managed исключает результаты, которые не были установлены менеджером установки Python. Это полезно при определении того, какие среды выполнения можно обновить или удалить с помощью команды py.

Опция --online является сокращением для передачи --source=<URL> с источником по умолчанию. Передача любой из этих опций приведёт к поиску в онлайн-индексе сред выполнения, которые можно установить. Результат, показываемый командой py list --online --one <TAG>, будет соответствовать среде выполнения, которая была бы установлена командой py install <TAG>.

$> py list --online 3.14

Для совместимости со старым загрузчиком команды --list, --list-paths, -0 и -0p (например, py -0p) сохранены. Они не допускают дополнительных опций и выдают вывод в устаревшем формате.

4.1.5. Установка сред выполнения¶Installing runtimes

$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]

Новые версии сред выполнения можно добавить с помощью py install. Можно указать один или несколько тегов, а специальный тег default может использоваться для выбора версии по умолчанию. Диапазоны не поддерживаются для установки.

Опция --source=<URL> позволяет переопределить онлайн-индекс, используемый для получения сред выполнения. Это можно использовать с автономным индексом, как показано в Автономные установки.

Передача --force приведёт к игнорированию любых кэшированных файлов и удалению любой существующей установки с заменой на указанную.

Передача --update приведёт к замене существующих установок, если новая версия новее. В противном случае они останутся без изменений. Если теги не указаны с --update, все установки, управляемые менеджером установки Python, будут обновлены, если доступны более новые версии. Обновления удалят любые изменения, внесённые в установку, включая глобально установленные пакеты, но виртуальные окружения продолжат работать.

Передача --dry-run приведёт к генерации вывода и журналов, но не изменит никаких установок.

Передача --refresh обновит все регистрации для установленных сред выполнения. Это заново создаст ярлыки в меню «Пуск», записи реестра и глобальные псевдонимы (такие как python3.14.exe или для любых установленных сценариев). Они автоматически обновляются при установке любой среды выполнения, но могут потребовать ручного обновления после установки пакетов.

В дополнение к указанным выше опциям, опция --target извлечёт среду выполнения в указанный каталог вместо обычной установки. Это полезно для встраивания сред выполнения в более крупные приложения. В отличие от обычной установки, py не будет знать об извлечённой среде выполнения, и не будут созданы ярлыки в меню «Пуск» или другие ярлыки. Чтобы запустить среду выполнения, непосредственно выполните главный исполняемый файл (обычно python.exe) в целевом каталоге.

$> py install ... [-t=|--target=<PATH>] <TAG>

Команда py exec установит запрошенную среду выполнения, если она ещё не установлена. Это управляется конфигурацией automatic_install (PYTHON_MANAGER_AUTOMATIC_INSTALL) и включено по умолчанию. Если среда выполнения вообще недоступна, все команды запуска выполнит автоматическую установку, если это разрешено настройкой конфигурации. Это сделано для обеспечения хорошего восприятия для новых пользователей, но в целом не следует полагаться на это вместо использования команды py exec или явных команд установки.

4.1.6. Автономные установки¶Offline installs

Для выполнения автономных установок Python необходимо сначала создать автономный индекс на машине, имеющей доступ к сети.

$> py install --download=<PATH> ... <TAG>...

Опция --download=<PATH> загрузит пакеты для указанных тегов и создаст каталог, содержащий их и файл index.json, подходящий для последующей установки. Этот каталог целиком можно переместить на автономную машину и использовать для установки одной или нескольких включённых сред выполнения:

$> py install --source="<PATH>\index.json" <TAG>...

Менеджер установки Python можно установить, загрузив его установщик и переместив его на другую машину перед установкой.

В качестве альтернативы ZIP-файлы в каталоге автономного индекса можно просто передать на другую машину и распаковать. Это никак не зарегистрирует установку, поэтому её необходимо запускать, напрямую ссылаясь на исполняемые файлы в распакованном каталоге, но иногда это предпочтительный подход в тех случаях, когда установка менеджера установки Python невозможна или неудобна.

Таким образом, среды выполнения Python можно устанавливать и управлять ими на машине без доступа к интернету.

4.1.7. Удаление сред выполнения¶Uninstalling runtimes

$> py uninstall [-y|--yes] <TAG>...

Среды выполнения можно удалить с помощью команды py uninstall. Необходимо указать один или несколько тегов. Диапазоны здесь не поддерживаются.

Опция --yes пропускает запрос подтверждения перед удалением.

Вместо указания отдельных тегов можно указать опцию --purge. Это приведет к удалению всех сред выполнения, управляемых установщиком Python, включая очистку меню «Пуск», реестра и кэша загрузок. Среды, которые не были установлены установщиком Python, не пострадают, как и вручную созданные файлы конфигурации.

$> py uninstall [-y|--yes] --purge

Установщик Python можно удалить через страницу настроек «Установленные приложения» в Windows. Это не удаляет среды выполнения, и они останутся работоспособными, хотя глобальные команды python и py будут удалены. Повторная установка установщика Python позволит снова управлять этими средами выполнения. Чтобы полностью очистить все среды выполнения Python, запустите с --purge перед удалением установщика Python.

4.1.8. Конфигурация¶Configuration

Установщик Python настраивается с помощью иерархии конфигурационных файлов, переменных окружения, параметров командной строки и настроек реестра. В целом, конфигурационные файлы позволяют настроить всё, включая расположение других конфигурационных файлов, а настройки реестра доступны только администратору и имеют приоритет над конфигурационными файлами. Параметры командной строки переопределяют все остальные настройки, но доступны не все параметры.

В этом разделе описаны настройки по умолчанию, но следует учитывать, что измененные или переопределенные установки могут обрабатывать настройки иначе.

Глобальный конфигурационный файл может быть настроен администратором и читается первым. Файл конфигурации пользователя находится по адресу %AppData%\Python\pymanager.json (обратите внимание, что этот путь находится в Roaming, а не в Local) и читается следующим, перезаписывая любые настройки из предыдущих файлов. Дополнительный конфигурационный файл может быть указан как переменная окружения PYTHON_MANAGER_CONFIG или параметр командной строки --config (но не оба одновременно). Эти расположения могут быть изменены параметрами административной настройки, перечисленными далее.

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

Стандартные параметры конфигурации

Имена с точками должны быть вложены в объекты JSON; например, list.format будет указано как {"list": {"format": "table"}}.

4.1.9. Shebang-строки¶Shebang lines

Если первая строка файла скрипта начинается с #!, она называется «шебанг»-строкой. Операционные системы Linux и другие Unix-подобные имеют встроенную поддержку таких строк, и они обычно используются в таких системах для указания способа выполнения скрипта. Команды python и py позволяют использовать те же возможности для скриптов Python на Windows.

Чтобы обеспечить переносимость шебанг-строк в скриптах Python между Unix и Windows, поддерживается ряд «виртуальных» команд, которые указывают, какой интерпретатор использовать. Поддерживаемые виртуальные команды:

• /usr/bin/env <ALIAS>

• /usr/bin/env -S <ALIAS>

• /usr/bin/<ALIAS>

• /usr/local/bin/<ALIAS>

• <ALIAS>

Например, если первая строка вашего сценария начинается с

#! /usr/bin/python

Будет найдена и использована стандартная Python или активная виртуальная среда. Поскольку многие скрипты Python, написанные для Unix, уже содержат эту строку, вы должны обнаружить, что эти скрипты могут использоваться программой-загрузчиком без изменений. Если вы пишете новый скрипт на Windows, который, как вы надеетесь, будет полезен на Unix, следует использовать одну из shebang-строк, начинающихся с /usr.

Любую из вышеперечисленных виртуальных команд можно заменить <ALIAS> на псевдоним из установленной исполняющей среды. То есть любая команда, сгенерированная в каталоге глобальных псевдонимов (который вы могли добавить в вашу переменную окружения PATH), может использоваться в шебанге, даже если она не находится в вашей PATH. Это позволяет использовать шебанги, например /usr/bin/python3.12, для выбора конкретной среды.

Если среда выполнения не установлена или включена автоматическая установка, требуемая среда будет установлена при необходимости. См. Конфигурация для информации о настройках конфигурации.

Форма шебанг-строки /usr/bin/env также будет искать переменную окружения PATH для нераспознанных команд. Это соответствует поведению программы Unix env, которая выполняет тот же поиск, но предпочитает запускать известные команды Python. Может отображаться предупреждение при поиске произвольных исполняемых файлов, и этот поиск может быть отключён опцией конфигурации shebang_can_run_anything.

Шебанг-строки, не соответствующие ни одному из шаблонов, обрабатываются как Windows пути к исполняемым файлам – абсолютные или относительные каталога, содержащего файл скрипта. Это удобно для скриптов, работающих только в Windows, например, созданных установщиком, поскольку такое поведение несовместимо с оболочками в стиле Unix. Эти пути могут быть заключены в кавычки и могут содержать несколько аргументов, после которых будет добавлен путь к скрипту и любые дополнительные аргументы. Эта функциональность может быть отключена опцией конфигурации shebang_can_run_anything.

Начиная с версии 26.3 Python install manager, в файл конфигурации можно добавлять пользовательские шаблоны шебанга. Добавьте объект shebang_templates с одним элементом для каждого шаблона (строка для сопоставления) и команду, используемую при совпадении шаблона. Большинство команд должны быть py -V:<tag> (или pyw) для запуска одной из установленных сред. Форма py -3.<version> также допускается, как и простая py для запуска среды по умолчанию. Другие аргументы не поддерживаются.

{
    "shebang_templates": {
        "/usr/bin/python": "py",
        "/usr/bin/my_custom_python": "py -V:MyCustomPython/3"
    }
}

Если команда подстановки не является py или pyw, она будет записана обратно в шебанг, и продолжится обычная обработка. Если разрешён запуск произвольных исполняемых файлов, то указание полного пути позволит перенаправить выполнение с Python на любой исполняемый файл. Шаблон должен соответствовать либо всей строке (игнорируя начальные и конечные пробелы), либо до первого пробела в строке шебанга.

4.1.10. Расширенная установка¶Advanced installation

Для ситуаций, когда установка MSIX невозможна (например, на некоторых устаревших платформах административного распространения), доступен MSI на странице загрузки python.org. Этот MSI не имеет пользовательского интерфейса и может выполнять только установку на машину в своё местоположение по умолчанию в Program Files. Он попытается изменить системную переменную окружения PATH, чтобы включить это место установки, но обязательно проверьте это в вашей конфигурации.

Обратите внимание: пакет MSI не включает в себя среды выполнения, поэтому он не подходит для установки в автономных средах без создания автономного индекса установки. См. Автономные установки и Административная конфигурация для получения информации о работе в таких сценариях.

Среды выполнения, установленные с помощью MSI, являются общими с установленными через MSIX и являются только пользовательскими. Python install manager не поддерживает установку сред на машину. Чтобы эмулировать установку на машину, вы можете использовать py install --target=<shared location> от имени администратора и добавить собственные общесистемные изменения в PATH, реестр или меню «Пуск».

Когда MSIX установлен, но команды не доступны в переменной окружения PATH, их можно найти в %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km или %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0, в зависимости от того, был ли он установлен с python.org или через Магазин Windows. Попытка запустить исполняемый файл непосредственно из Program Files не рекомендуется.

Для программной установки Python install manager проще всего использовать WinGet, который входит во все поддерживаемые версии Windows:

$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

# При необходимости запустите проверку конфигурации и примите все изменения.
$> py install --configure -y

Чтобы загрузить Python install manager и установить на другой машине, следующая команда WinGet загрузит необходимые файлы из Магазина в ваш каталог Загрузки (добавьте -d <location>, чтобы изменить расположение вывода). Также генерируется YAML-файл, который, по-видимому, не нужен, так как загруженный MSIX можно установить запуском или с помощью команд ниже.

$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements

Для программной установки или удаления MSIX, используя только PowerShell, рекомендуются командлеты PowerShell Add-AppxPackage и Remove-AppxPackage:

$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage

Последний выпуск можно загрузить и установить в Windows, передав файл AppInstaller команде Add-AppxPackage. При этом установка выполняется с помощью MSIX на python.org, и это рекомендуется только для случаев, когда установка через Магазин (интерактивно или с помощью WinGet) невозможна.

$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller

Другие инструменты и API также могут использоваться для подготовки пакета MSIX для всех пользователей на машине, но Python не считает это поддерживаемым сценарием. Мы предлагаем изучить командлет PowerShell Add-AppxProvisionedPackage, собственный класс Windows PackageManager или документацию и поддержку вашего инструмента развёртывания.

Независимо от метода установки, пользователям всё равно нужно будет установить свои собственные копии Python, поскольку нет возможности инициировать эти установки без выполненного входа в систему. При использовании MSIX последняя версия Python будет доступна для установки всем пользователям без доступа к сети.

Обратите внимание, что MSIX, доступный для загрузки из Магазина и с веб-сайта Python, незначительно отличаются и не могут быть установлены одновременно. По возможности мы рекомендуем использовать приведённые выше команды WinGet для загрузки пакета из Магазина, чтобы снизить риск создания конфликтующих установок. Нет никаких лицензионных ограничений на Python install manager, которые препятствовали бы использованию пакета из Магазина таким образом.

4.1.11. Административная конфигурация¶Administrative configuration

Существует ряд параметров, которые могут быть полезны администраторам для переопределения конфигурации Python install manager. Они могут использоваться для организации локального кэширования, отключения определённых типов ярлыков, переопределения встроенного содержимого. Все вышеперечисленные параметры конфигурации могут быть установлены, так же как и приведённые ниже.

Параметры конфигурации могут быть переопределены в реестре путём задания значений в разделе HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager, где имя значения соответствует ключу конфигурации, а тип значения – REG_SZ. Обратите внимание, что этот раздел можно настроить, но только путём изменения основного конфигурационного файла, распространяемого с Python install manager. Однако мы рекомендуем использовать значения реестра только для установки base_config в JSON-файл, содержащий полный набор переопределений. Переопределения из раздела реестра заменят любые другие настроенные параметры, в то время как base_config позволяет пользователям дополнительно изменять настройки, которые им могут понадобиться.

Обратите внимание, что большинство настроек с переменными окружения используют эти переменные, потому что их значение по умолчанию указывает на переменную. Если их переопределить, переменная окружения перестанет работать, если только не переопределить её другой. Например, значение по умолчанию confirm в буквальном смысле равно %PYTHON_MANAGER_CONFIRM%, что разрешает переменную во время загрузки. Если переопределить значение на yes, переменная окружения больше не будет использоваться. Если переопределить значение на %CONFIRM%, будет использоваться эта переменная окружения.

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

Параметры административной конфигурации

4.1.12. Установка двоичных файлов со свободной многопоточностью¶Installing free-threaded binaries

Предварительно собранные дистрибутивы сборки со свободными потоками доступны при установке тегов с суффиксом t.

$> py install 3.14t
$> py install 3.14t-arm64
$> py install 3.14t-32

Это установится и зарегистрируется как обычно. Если другие среды выполнения не установлены, python запустит эту. В противном случае потребуется использовать py -V:3.14t ... или, если глобальный каталог псевдонимов добавлен в переменную окружения PATH, команды python3.14t.exe.

4.1.13. Подписи индексов¶Index signatures

Файлы индекса могут быть подписаны для обнаружения подделки. Подпись – это файл каталога по тому же URL, что и индекс, с добавлением .cat к имени файла. Файл каталога должен содержать хеш соответствующего файла индекса и быть подписан действительной подписью Authenticode. Это позволяет стандартным инструментам (в Windows) генерировать подпись, и может использоваться любой сертификат, если операционная система клиента уже доверяет его удостоверяющему центру (корневому ЦС).

Подписи индексов загружаются и проверяются только в том случае, если в локальной конфигурации раздел source_settings содержит URL индекса и requires_signature имеет значение true, или JSON индекса содержит requires_signature со значением true. Если настройка существует в локальной конфигурации, даже со значением false, настройки в индексе игнорируются.

Помимо требования действительной подписи, настройки required_root_subject и required_publisher_subject могут дополнительно ограничивать допустимые подписи на основе полей Subject сертификата. Любой атрибут, указанный в конфигурации, должен совпадать с атрибутом в сертификате (дополнительные атрибуты в сертификате игнорируются). Типичные атрибуты: CN= для общего имени, O= для организационной единицы и C= для страны издателя.

Наконец, настройка required_publisher_eku позволяет требовать, чтобы сертификату издателя был назначен определённый расширенный ключ использования (EKU). Например, EKU 1.3.6.1.5.5.7.3.3 указывает, что сертификат предназначен для подписи кода (в отличие от аутентификации сервера или клиента). В сочетании с определённым корневым ЦС это даёт ещё один механизм проверки легитимной подписи.

Это пример раздела source_settings из файла конфигурации. В данном случае издатель канала однозначно идентифицируется комбинацией корневого сертификата Microsoft Identity Verification и EKU, назначенного этим корнем. Подпись для этого случая будет находиться по адресу https://www.python.org/ftp/python/index-windows.json.cat.

{
  "source_settings": {
    "https://www.python.org/ftp/python/index-windows.json": {
      "requires_signature": true,
      "required_root_subject": "CN=Microsoft Identity Verification Root Certificate Authority 2020",
      "required_publisher_subject": "CN=Python Software Foundation",
      "required_publisher_eku": "1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327"
    }
  }
}

Те же настройки можно указать в файле index.json. В этом случае корневой сертификат и EKU опускаются, что означает, что подпись должна быть действительной и содержать определённое общее имя в сертификате издателя, но никакие другие проверки не применяются.

{
  "requires_signature": true,
  "required_publisher_subject": "CN=Python Software Foundation",
  "versions": [
    // ...
  ]
}

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

Невозможно переопределить расположение файла подписи в канале или через файл конфигурации. Администраторы могут указать свой собственный source_settings в обязательном файле конфигурации (см. Административную конфигурацию).

Если проверка подписи не удалась, вы будете уведомлены и получите запрос на продолжение. Если интерактивное подтверждение не разрешено (например, из-за указания --yes), операция всегда прерывается. Чтобы использовать канал с недействительной конфигурацией в этом сценарии, необходимо предоставить файл конфигурации, отключающий проверку подписи для этого канала.

"source_settings": {
  "https://www.example.com/feed-with-invalid-signature.json": {
    "requires_signature": false
  }
}

4.1.14. Поиск и устранение неполадок¶Troubleshooting

Если менеджер установки Python работает некорректно, выполните следующие проверки и исправления. Если это не поможет, сообщите о проблеме в наш трекер ошибок, приложив соответствующие файлы журналов (по умолчанию они сохраняются в каталог %TEMP%).

Поиск и устранение неполадок

4.2.1. Приложение Python¶Python application

Приложение, написанное на Python, не обязательно требует, чтобы пользователи знали об этом факте. В этом случае встраиваемое распространение может быть использовано для включения частной версии Python в установочный пакет. В зависимости от того, насколько прозрачным оно должно быть (или, наоборот, насколько профессиональным оно должно выглядеть), есть два варианта.

Использование специализированного исполняемого файла в качестве загрузчика требует некоторого программирования, но обеспечивает наиболее прозрачный интерфейс для пользователей. При использовании настраиваемого загрузчика нет явных признаков того, что программа работает на Python: значки можно настраивать, можно указать информацию о компании и версии, а ассоциации файлов работают правильно. В большинстве случаев настраиваемый загрузчик должен просто вызывать Py_Main с жестко заданной командной строкой.

Более простой подход – предоставить пакетный файл или созданный ярлык, который напрямую вызывает python.exe или pythonw.exe с необходимыми аргументами командной строки. В этом случае приложение будет отображаться как Python, а не под своим реальным именем, и у пользователей могут возникнуть трудности с его отличием от других запущенных процессов Python или ассоциаций файлов.

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

4.2.2. Встраивание Python¶Embedding Python

Приложения, написанные на нативном коде, часто требуют какую-либо форму языка сценариев, и для этой цели может быть использовано встраиваемое распространение Python. В общем случае большая часть приложения написана на нативном коде, и некоторая часть будет либо вызывать python.exe, либо напрямую использовать python3.dll. В любом случае, извлечение встраиваемого распространения в подкаталог установки приложения достаточно для обеспечения загружаемого интерпретатора Python.

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

4.3.1. Пакеты со свободной многопоточностью¶Free-threaded packages

Пакеты, содержащие свободно-поточные двоичные файлы, называются python-freethreaded для 64-битной версии, pythonx86-freethreaded для 32-битной версии и pythonarm64-freethreaded для ARM64 версии. Эти пакеты содержат как точку входа python3.13t.exe, так и python.exe, обе из которых работают в свободно-поточном режиме.

4.9.1. PyWin32¶

Модуль PyWin32 от Марка Хаммонда – это набор модулей для расширенной поддержки Windows. Он включает утилиты для:

• Component Object Model (COM)

• Вызовы Win32 API

• Реестр

• Журнал событий

• Microsoft Foundation Classes (MFC) пользовательские интерфейсы

PythonWin – это пример MFC-приложения, поставляемого с PyWin32. Это встраиваемая среда разработки со встроенным отладчиком.

4.9.2. cx_Freeze¶

cx_Freeze упаковывает скрипты Python в исполняемые программы Windows (*.exe файлы). После этого можно распространять ваше приложение без необходимости устанавливать Python пользователям.

4.11.1. Шаги установки¶Installation steps

Four Python 3.14 installers are available for download - two each for the 32-bit and 64-bit versions of the interpreter. The web installer is a small initial download, and it will automatically download the required components as necessary. The offline installer includes the components necessary for a default installation and only requires an internet connection for optional features. See Installing without downloading for other ways to avoid downloading during installation.

После запуска установщика можно выбрать один из двух вариантов:

Если вы выберете «Установить сейчас»:

• You will not need to be an administrator (unless a system update for the C Runtime Library is required or you install the Python install manager for all users)

• Python будет установлен в ваш пользовательский каталог

• Менеджер установки Python будет установлен в соответствии с опцией внизу первой страницы

• Стандартная библиотека, тестовый набор, средство запуска и pip будут установлены

• Если выбрано, каталог установки будет добавлен в ваши PATH

• Ярлыки будут видны только текущему пользователю

Выбор «Настраиваемая установка» позволит выбрать компоненты для установки, расположение установки и другие параметры или действия после установки. Чтобы установить отладочные символы или двоичные файлы, нужно использовать этот вариант.

Для установки для всех пользователей следует выбрать «Настраиваемая установка». В этом случае:

• Может потребоваться предоставить учетные данные администратора или одобрение

• Python будет установлен в каталог Program Files

• Менеджер установки Python будет установлен в каталог Windows

• Дополнительные компоненты можно выбрать во время установки

• Стандартная библиотека может быть предварительно скомпилирована в байт-код

• Если выбрано, каталог установки будет добавлен в системные PATH

• Ярлыки доступны для всех пользователей

4.11.2. Удаление ограничения MAX_PATH¶Removing the MAX_PATH limitation

Исторически сложилось так, что в Windows длина пути была ограничена 260 символами. Это означало, что пути длиннее этого значения не распознавались и приводили к ошибкам.

В последних версиях Windows это ограничение можно расширить до приблизительно 32 000 символов. Администратору необходимо активировать групповую политику «Enable Win32 long paths» или установить значение LongPathsEnabled равным 1 в разделе реестра HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

Это позволяет функции open(), модулю os и большинству других функций работы с путями принимать и возвращать пути длиннее 260 символов.

После изменения указанного параметра никаких дополнительных настроек не требуется.

4.11.3. Установка без пользовательского интерфейса¶Installing without UI

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

Следующие параметры (определяемые при запуске установщика с /?) можно передать установщику:

Все остальные параметры передаются в виде name=value, где значение обычно 0 для отключения функции, 1 для включения функции или путь. Полный список доступных параметров приведён ниже.

Например, для автоматической установки Python по умолчанию в общесистемном режиме можно использовать следующую команду (из командной строки с правами администратора):

python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

Чтобы пользователи могли легко установить личную копию Python без набора тестов, можно предоставить ярлык со следующей командой. Она отобразит упрощённую начальную страницу и запретит настройку:

python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
    SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."

(Обратите внимание: отказ от лаунчера также отключает ассоциации файлов, и это рекомендуется только для установок для одного пользователя при наличии общесистемной установки, включающей лаунчер.)

Перечисленные выше параметры также можно указать в файле с именем unattend.xml, расположенном рядом с исполняемым файлом. Этот файл задаёт список параметров и значений. Если значение указано как атрибут, оно будет преобразовано в число, если это возможно. Значения, указанные как текст элемента, всегда остаются строками. В этом примере файл задаёт те же параметры, что и в предыдущем примере:

<Options>
    <Option Name="InstallAllUsers" Value="no" />
    <Option Name="Include_launcher" Value="0" />
    <Option Name="Include_test" Value="no" />
    <Option Name="SimpleInstall" Value="yes" />
    <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
</Options>

4.11.4. Установка без загрузки¶Installing without downloading

Поскольку некоторые возможности Python не входят в начальный загружаемый установщик, для выбора этих возможностей может потребоваться подключение к интернету. Чтобы избежать этого, все возможные компоненты можно загрузить по требованию, создав полную сборку, которая больше не будет требовать подключения к интернету независимо от выбранных возможностей. Обратите внимание, что такая загрузка может быть больше необходимой, но при большом количестве установок очень полезно иметь локально кэшированную копию.

Выполните следующую команду в командной строке, чтобы загрузить все возможные необходимые файлы. Не забудьте заменить python-3.9.0.exe на фактическое имя вашего установщика и создавать сборки в отдельных каталогах, чтобы избежать конфликтов между файлами с одинаковыми именами.

python-3.9.0.exe /layout [optional target directory]

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

4.11.5. Изменение установки¶Modifying an install

После установки Python можно добавлять или удалять компоненты через средство «Программы и компоненты», входящее в состав Windows. Выберите запись Python и выберите «Удаление/Изменение», чтобы открыть установщик в режиме обслуживания.

«Изменить» позволяет добавлять или удалять компоненты, изменяя флажки – неизменённые флажки ничего не устанавливают и не удаляют. Некоторые параметры нельзя изменить в этом режиме, например, каталог установки; чтобы изменить их, потребуется полностью удалить и затем переустановить Python.

«Восстановить» проверяет все файлы, которые должны быть установлены в соответствии с текущими настройками, и заменяет те, которые были удалены или изменены.

«Удалить» полностью удаляет Python, за исключением Диспетчера установки Python, который имеет собственную запись в «Программах и компонентах».

4.11.6. Установка двоичных файлов со свободной многопоточностью¶Installing free-threaded binaries

Чтобы установить предварительно собранные двоичные файлы со включённой свободной многопоточностью (см. PEP 703), необходимо выбрать «Выборочная установка». На второй странице параметров находится флажок «Загрузить двоичные файлы со свободной многопоточностью».

Выбор этой опции загрузит и установит дополнительные двоичные файлы в ту же директорию, что и основная установка Python. Главный исполняемый файл называется python3.13t.exe, а другие двоичные файлы получают суффикс t или полный суффикс ABI. Исходные файлы Python и встроенные сторонние зависимости являются общими с основной установкой.

Версия со свободной многопоточностью регистрируется как обычная установка Python с тегом 3.13t (с суффиксом -32 или -arm64, как обычно для этих платформ). Это позволяет инструментам обнаруживать её, а Диспетчеру установки Python – поддерживать py.exe -3.13t. Обратите внимание, что лаунчер интерпретирует py.exe -3 (или шебанг python3) как «последнюю установку 3.x», что будет отдавать предпочтение двоичным файлам со свободной многопоточностью перед обычными, тогда как py.exe -3.13 – нет. Если используется краткий стиль параметров, возможно, стоит пока не устанавливать двоичные файлы со свободной многопоточностью.

Чтобы указать параметр установки в командной строке, используйте Include_freethreaded=1. См. Установка без загрузки для инструкций по предварительной загрузке дополнительных двоичных файлов для автономной установки. Параметры включения отладочных символов и отладочных двоичных файлов также применяются к сборкам со свободной многопоточностью.

Двоичные файлы со свободной многопоточностью также доступны на nuget.org.

4.12.1. Начало работы¶Getting started

py

py -3.7

py -2

'py' is not recognized as an internal or external command,
operable program or batch file.

py --list

# Select any '3.*' tagged runtime
py -V:3

# Select any 'PythonCore' released runtime
py -V:PythonCore/

# Select PythonCore's latest Python 3 runtime
py -V:PythonCore/3

#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))

py hello.py

#! python3

4.12.2. Shebang-строки¶Shebang lines

Если первая строка файла сценария начинается с #!, она называется «shebang»-строкой. Linux и другие Unix-подобные операционные системы имеют встроенную поддержку таких строк, и они обычно используются в этих системах для указания того, как следует выполнять сценарий. Данный загрузчик позволяет использовать те же возможности для сценариев Python в Windows, и примеры выше демонстрируют их применение.

Чтобы обеспечить переносимость shebang-строк в сценариях Python между Unix и Windows, этот загрузчик поддерживает ряд «виртуальных» команд для указания того, какой интерпретатор использовать. Поддерживаемые виртуальные команды:

• /usr/bin/env

• /usr/bin/python

• /usr/local/bin/python

• python

Например, если первая строка вашего сценария начинается с

#! /usr/bin/python

Будет найдена и использована стандартная Python или активная виртуальная среда. Поскольку многие скрипты Python, написанные для Unix, уже содержат эту строку, вы должны обнаружить, что эти скрипты могут использоваться программой-загрузчиком без изменений. Если вы пишете новый скрипт на Windows, который, как вы надеетесь, будет полезен на Unix, следует использовать одну из shebang-строк, начинающихся с /usr.

К любой из указанных выше виртуальных команд можно добавить явную версию (только старшую версию или старшую и младшую версию). Кроме того, 32-битную версию можно запросить, добавив «-32» после младшей версии. То есть /usr/bin/python3.7-32 запросит использование 32-битной Python 3.7. Если активна виртуальная среда, версия будет проигнорирована и будет использована среда.

Форма /usr/bin/env shebang-строки имеет ещё одно особое свойство. Прежде чем искать установленные интерпретаторы Python, эта форма выполняет поиск в исполняемом файле PATH исполняемого файла Python, соответствующего имени, указанному в качестве первого аргумента. Это соответствует поведению программы Unix env, которая выполняет поиск PATH. Если исполняемый файл, соответствующий первому аргументу после команды env, не найден, но аргумент начинается с python, он будет обработан так, как описано для других виртуальных команд. Переменная окружения PYLAUNCHER_NO_SEARCH_PATH может быть установлена (в любое значение), чтобы пропустить этот поиск PATH.

Shebang-строки, не соответствующие ни одному из этих шаблонов, ищутся в разделе [commands] файла .INI загрузчика. Это может использоваться для обработки определённых команд способом, подходящим для вашей системы. Имя команды должно быть одним аргументом (без пробелов в исполняемом файле shebang), а подставленное значение – это полный путь к исполняемому файлу (дополнительные аргументы, указанные в .INI, будут заключены в кавычки как часть имени файла).

[commands]
/bin/xpython=C:\Program Files\XPython\python.exe

Любые команды, не найденные в файле .INI, обрабатываются как пути к исполняемым файлам Windows, которые являются абсолютными или относительными относительно каталога, содержащего файл скрипта. Это удобно для скриптов, предназначенных только для Windows, например, созданных установщиком, поскольку такое поведение несовместимо с оболочками Unix. Эти пути могут быть заключены в кавычки и могут содержать несколько аргументов, после которых будет добавлен путь к скрипту и любые дополнительные аргументы.

4.12.3. Аргументы в shebang-строках¶Arguments in shebang lines

Shebang-строки также могут указывать дополнительные параметры, передаваемые интерпретатору Python. Например, если у вас есть shebang-строка:

#! /usr/bin/python -v

Тогда Python будет запущен с опцией -v

4.12.4. Настройка¶Customization

[defaults]
python=3.7

[defaults]
python=3
python3=3.7

4.12.5. Диагностика¶Diagnostics

Если установлена переменная окружения PYLAUNCHER_DEBUG (в любое значение), загрузчик будет выводить диагностическую информацию в stderr (т.е. на консоль). Хотя эта информация одновременно многословна и кратка, она должна позволить вам увидеть, какие версии Python были найдены, почему была выбрана конкретная версия и точная командная строка, используемая для запуска целевого Python. Она предназначена в первую очередь для тестирования и отладки.

4.12.6. Пробный запуск¶Dry run

Если установлена переменная окружения PYLAUNCHER_DRYRUN (с любым значением), лаунчер выведет команду, которую выполнил бы, но не запустит Python. Это может быть полезно для инструментов, которые хотят использовать лаунчер для обнаружения и последующего прямого запуска Python. Обратите внимание, что команда, записанная в стандартный вывод, всегда кодируется UTF-8 и может некорректно отображаться в консоли.

4.12.7. Установка по требованию¶Install on demand

Если установлена переменная окружения PYLAUNCHER_ALLOW_INSTALL (с любым значением), а запрошенная версия Python не установлена, но доступна в Microsoft Store, лаунчер попытается установить её. Для завершения может потребоваться взаимодействие с пользователем, и, возможно, команду нужно будет запустить снова.

Дополнительная переменная PYLAUNCHER_ALWAYS_INSTALL приводит к тому, что лаунчер всегда пытается установить Python, даже если он уже обнаружен. Это предназначено в основном для тестирования (и должно использоваться вместе с PYLAUNCHER_DRYRUN).

4.12.8. Коды возврата¶Return codes

Лаунчер Python может возвращать следующие коды завершения. К сожалению, невозможно отличить их от кода завершения самого Python.

Имена кодов соответствуют тем, что используются в исходном коде, и приведены только для справки. Получить или сопоставить их иным способом, кроме как из этой страницы, невозможно. Записи перечислены в алфавитном порядке имён.