zipapp — Управление исполняемыми Python-архивами zip

Пример использования

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

$ python -m zipapp myapp -m "myapp:main"
$ python myapp.pyz
<output from myapp>

Командная строка

При вызове в качестве программы из командной строки используется следующий формат:

$ python -m zipapp source [options]

Если source — это директория, это создаст архив из содержимого source. Если source — это файл, он должен быть архивом, и он будет скопирован в целевой архив (или содержимое его строки shebang будет выведено, если указан параметр –info).

Поддерживаются следующие параметры:

-o <output>, --output=<output>

Записать вывод в файл с именем output. Если этот параметр не указан, имя файла вывода будет таким же, как у входного файла source, с добавленным расширением .pyz. Если задано явное имя файла, оно используется как есть (поэтому необходимо включать расширение .pyz, если это требуется).

Имя файла вывода должно быть указано, если source является архивом (и в этом случае output не должен совпадать с source).

-p <interpreter>, --python=<interpreter>

Добавить строку shebang в архив, указывающую interpreter в качестве команды для выполнения. Также, в POSIX-системах, сделать архив исполняемым. По умолчанию не добавляется строка shebang и файл не делается исполняемым.

-m <mainfn>, --main=<mainfn>

Записать в архив файл, который выполняет mainfn. Аргумент mainfn должен иметь вид “pkg.mod:fn”, где “pkg.mod” — пакет/модуль в архиве, а “fn” — вызываемый объект в данном модуле. Файл __main__.py выполнит этот вызываемый объект.

--main не может быть указан при копировании архива.

-c, --compress

Сжимать файлы методом deflate, уменьшая размер выходного файла. По умолчанию файлы хранятся в архиве без сжатия.

--compress не имеет эффекта при копировании архива.

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

--info

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

-h, --help

Вывести короткое сообщение об использовании и завершить работу.

Python-API

Модуль определяет две удобные функции:

zipapp.create_archive(source, target=None, interpreter=None, main=None, filter=None, compressed=False)

Создать архив приложения из source. Источник может быть следующим:

• Имя директории или объект-путь, указывающий на директорию, в этом случае новый архив приложения будет создан из содержимого этой директории.
• Имя существующего файла архива приложения или объект-путь, указывающий на такой файл, в этом случае файл будет скопирован в целевой файл (изменяя его в соответствии со значением, заданным для аргумента interpreter). Имя файла должно содержать расширение .pyz , если требуется.
• Объект файла, открытый для чтения в формате байтов. Содержимое файла должно быть архивом приложения, и предполагается, что объект файла находится в начале архива.

Аргумент target определяет, куда будет записан результирующий архив:

• Если это имя файла или объект-путь, архив будет записан в этот файл.
• Если это открытый объект файла, архив будет записан в этот объект файла, который должен быть открыт для записи в формате байтов.
• Если целевой файл не указан (или None), исходный файл должен быть директорией, и целевой файл будет иметь такое же имя, как исходный файл, с добавленным расширением .pyz.

Аргумент interpreter указывает имя интерпретатора Python, с которым будет выполнен архив. Он записывается в строку shebang в начале архива. В POSIX-системах это будет интерпретировано операционной системой, а в Windows это будет обрабатываться загрузчиком Python. Опускание interpreter приводит к тому, что строка shebang не записывается. Если интерпретатор указан, и цель — имя файла, биты исполняемости целевого файла будут установлены.

Аргумент main указывает имя вызываемого объекта, который будет использоваться в качестве основной программы для архива. Он может быть указан только если источник — директория, и источник не содержит файла __main__.py. Аргумент main должен иметь вид “pkg.module:callable”, и архив будет запущен путем импорта “pkg.module” и выполнения указанного вызываемого объекта без аргументов. Опускание main является ошибкой, если источник — директория и не содержит файла __main__.py , так как в противном случае результирующий архив не будет исполняемым.

Необязательный аргумент filter указывает функцию обратного вызова, которой передается объект Path, представляющий путь к файлу (относительно исходной директории). Он должен возвращать True , если файл должен быть добавлен.

Необязательный аргумент compressed определяет, сжаты ли файлы. Если он установлен в True, файлы в архиве сжимаются методом deflate, в противном случае файлы хранятся без сжатия. Этот аргумент не имеет эффекта при копировании существующего архива.

Если для source или target указан объект файла, ответственность за его закрытие лежит на вызывающей стороне после вызова create_archive.

При копировании существующего архива, объекты файлов, передаваемые только read и readline, или write методами. При создании архива из директории, если цель — объект файла, он будет передан классу zipfile.ZipFile, и должен предоставить необходимые методы для этого класса.

Изменено в версии 3.7: Добавлены параметры filter и compressed.

zipapp.get_interpreter(archive)

Возвращает интерпретатор, указанный в строке shebang в начале архива. Если строки shebang нет, возвращает None. Аргумент archive может быть именем файла или объектом файла, открытым для чтения в формате байтов. Предполагается, что он находится в начале архива.

Примеры

Упаковка директории в архив и запуск архива.

$ python -m zipapp myapp
$ python myapp.pyz
<output from myapp>

То же самое можно сделать, используя функцию create_archive():

>>> import zipapp
>>> zipapp.create_archive('myapp', 'myapp.pyz')

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

$ python -m zipapp myapp -p "/usr/bin/env python"
$ ./myapp.pyz
<output from myapp>

Для замены строки shebang в существующем архиве, создайте изменённый архив, используя функцию create_archive():

>>> import zipapp
>>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')

Для обновления файла на месте, выполните замену в памяти, используя объект BytesIO, а затем перезапишите исходный файл. Обратите внимание, что при перезаписи файла на месте существует риск, что ошибка приведёт к потере исходного файла. Этот код не защищает от таких ошибок, но код для производства должен это сделать. Кроме того, этот метод будет работать только если архив помещается в память:

>>> import zipapp
>>> import io
>>> temp = io.BytesIO()
>>> zipapp.create_archive('myapp.pyz', temp, '/usr/bin/python2')
>>> with open('myapp.pyz', 'wb') as f:
>>>     f.write(temp.getvalue())

Указание интерпретатора

Обратите внимание, что если вы укажете интерпретатор и затем будете распространять архив приложения, вам нужно убедиться, что используемый интерпретатор портативный. Загрузчик Python для Windows поддерживает большинство общих форм POSIX #! строки, но есть и другие моменты, которые следует учитывать:

• Если вы используете “/usr/bin/env python” (или другие формы команды «python», такие как «/usr/bin/python»), вам нужно учитывать, что ваши пользователи могут иметь как Python 2, так и Python 3 в качестве значения по умолчанию, и написать свой код так, чтобы он работал в обеих версиях.
• Если вы используете явную версию, например «/usr/bin/env python3», ваше приложение не будет работать для пользователей, у которых нет этой версии. (Это может быть тем, что вы хотите, если вы не сделали свой код совместимым с Python 2).
• Нет способа сказать «python X.Y или более поздняя версия», поэтому будьте осторожны при использовании точной версии, такой как «/usr/bin/env python3.4», так как вам понадобится изменить строку shebang для пользователей Python 3.5, например.

Как правило, вы должны использовать «/usr/bin/env python2» или «/usr/bin/env python3», в зависимости от того, для Python 2 или 3 написан ваш код.

Создание автономных приложений с помощью zipapp

Используя модуль zipapp, можно создавать автономные программы Python, которые можно распространять конечным пользователям, которым требуется только подходящая версия Python на их системе. Ключ к этому — объединение всех зависимостей приложения в архив вместе с кодом приложения.

Шаги по созданию автономного архива следующие:

1. Создайте своё приложение в каталоге как обычно, чтобы у вас был каталог myapp, содержащий файл __main__.py и любой поддерживающий код приложения.

2. Установите все зависимости вашего приложения в каталог myapp с помощью pip:

   $ python -m pip install -r requirements.txt --target myapp
   

   (это предполагает, что у вас есть требования к вашему проекту в файле requirements.txt — если нет, вы можете просто перечислить зависимости вручную в командной строке pip).

3. Упакуйте приложение с помощью:

   $ python -m zipapp -p "interpreter" myapp
   

Это создаст автономный исполняемый файл, который можно запустить на любой машине с доступным интерпретатором. Подробности см. в разделе Указание интерпретатора. Его можно отправить пользователям в виде одного файла.

В Unix-системах файл myapp.pyz исполняемый как есть. Вы можете переименовать файл, удалив расширение .pyz, если предпочитаете имя команды без расширения. В Windows файл myapp.pyz[w] исполняемый благодаря тому, что интерпретатор Python регистрирует расширения файлов .pyz и .pyzw при установке.

Формат архива приложения Python в формате zip

Python может выполнять файлы zip, содержащие файл __main__.py начиная с версии 2.6. Чтобы приложение выполнялось Python, архив приложения должен быть стандартным файлом zip, содержащим файл __main__.py, который будет использоваться в качестве точки входа в приложение. Как обычно для любого скрипта Python, родительский каталог скрипта (в данном случае файл zip) будет помещён в sys.path, и, следовательно, можно импортировать дополнительные модули из файла zip.

Формат файла zip позволяет добавлять произвольные данные в начало файла zip. Формат архива приложения zip использует эту возможность для добавления стандартной строки POSIX «shebang» в файл (#!/path/to/interpreter).

Формально, формат приложения Python в формате zip:

1. Необязательная строка shebang, содержащая символы b'#!' , за которыми следует имя интерпретатора, а затем символ новой строки (b'\n'). Имя интерпретатора может быть любым, приемлемым для обработки «shebang» ОС или запуска Python в Windows. Интерпретатор должен быть закодирован в UTF-8 в Windows и в sys.getfilesystemencoding() в POSIX.
2. Стандартные данные файла zip, созданные модулем zipfile. Содержание файла zip обязательно должно содержать файл под названием __main__.py (который должен находиться в «корне» файла zip — то есть он не может находиться в подкаталоге). Данные файла zip могут быть сжаты или не сжаты.

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

Нет требования, чтобы инструменты в этом модуле использовались для создания архивов приложений — этот модуль является удобством, но Python будут приемлемы архивы в указанном выше формате, созданные любым способом.