zipapp — Manage executable Python zip archives

Novo na versão 3.5.

Código-fonte: Lib/zipapp.py

Este módulo fornece ferramentas para gerenciar a criação de arquivos zip contendo código Python, que pode ser executado diretamente pelo interpretador Python. O módulo fornece uma Interface de Linha de Comando e uma API do Python.

Exemplo básico

O exemplo a seguir mostra como a Interface de Linha de Comando pode ser usada para criar um arquivo executável a partir de um diretório contendo código Python. Quando executado, o arquivo executará a função main do módulo myapp no arquivo.

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

Interface de Linha de Comando

Quando chamado como um programa a partir da linha de comando, as seguintes opções estão disponíveis:

$ python -m zipapp source [options]

Se source for um diretório, isso criará um arquivo a partir do conteúdo de source. Se source for um arquivo, ele deve ser um arquivo, e será copiado para o arquivo de destino (ou o conteúdo de sua linha shebang será exibido se a opção –info for especificada).

As seguintes opções são compreendidas:

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

Escreve a saída em um arquivo chamado output. Se essa opção não for especificada, o nome do arquivo de saída será o mesmo que o source de entrada, com a extensão .pyz adicionada. Se um nome de arquivo explícito for fornecido, ele será usado como está (então uma extensão .pyz deve ser incluída se necessário).

Um nome de arquivo de saída deve ser especificado se source for um arquivo (e nesse caso, output não deve ser o mesmo que source).

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

Adiciona uma linha #! ao arquivo especificando interpreter como o comando a ser executado. Além disso, no POSIX, torne o arquivo executável. O padrão é não escrever nenhuma linha #! e não tornar o arquivo executável.

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

Escreve um arquivo __main__.py no arquivo que executa mainfn. O argumento mainfn deve ter o formato “pkg.mod:fn”, onde “pkg.mod” é um pacote/módulo no arquivo, e “fn” é um chamável no módulo fornecido. O arquivo __main__.py executará esse chamável.

--main não pode ser especificado ao copiar um arquivo.

-c, --compress

Compacta arquivos com o método deflate, reduzindo o tamanho do arquivo de saída. Por padrão, os arquivos são armazenados descompactados no arquivo.

--compress não tem efeito ao copiar um arquivo.

Novo na versão 3.7.

--info

Exibe o interpretador incorporado no arquivo, para fins de diagnóstico. Neste caso, quaisquer outras opções são ignoradas e SOURCE deve ser um arquivo, não um diretório.

-h, --help

Exibe uma mensagem curta de uso e sai

API do Python

O módulo define duas funções de conveniência:

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

Cria um arquivo de aplicação a partir de source. A fonte pode ser qualquer um dos seguintes:

  • O nome de um diretório, ou um objeto caminho ou similar referente a um diretório, caso em que um novo arquivo de aplicação será criado a partir do conteúdo desse diretório.

  • O nome de um arquivo de aplicação existente, ou um objeto caminho ou similar referindo-se a tal arquivo, em cujo caso o arquivo é copiado para o alvo (modificando-o para refletir o valor dado para o argumento interpreter). O nome do arquivo deve incluir a extensão .pyz, se necessário.

  • Um objeto arquivo aberto para leitura no modo bytes. O conteúdo do arquivo deve ser um arquivo de aplicação, e o objeto arquivo é presumido como estando posicionado no início do arquivo.

O argumento target determina onde o arquivo resultante será escrito:

  • Se for o nome de um arquivo ou um objeto caminho ou similar, o arquivo será escrito nesse arquivo.

  • Se for um objeto arquivo aberto, o arquivo será escrito naquele objeto arquivo, que deve estar aberto para escrita no modo bytes.

  • Se o destino for omitido (ou Nenhum), a fonte deverá ser um diretório e o destino será um arquivo com o mesmo nome da fonte, com uma extensão .pyz adicionada.

O argumento interpreter especifica o nome do interpretador Python com o qual o arquivo será executado. Ele é escrito como uma linha “shebang” no início do arquivo. No POSIX, isso será interpretado pelo sistema operacional, e no Windows será manipulado pelo inicializador Python. Omitir o interpreter resulta em nenhuma linha shebang sendo escrita. Se um interpretador for especificado, e o alvo for um nome de arquivo, o bit executável do arquivo alvo será definido.

O argumento main especifica o nome de um chamável que será usado como o programa principal para o arquivo. Ele só pode ser especificado se a fonte for um diretório, e a fonte ainda não contiver um arquivo __main__.py. O argumento main deve ter o formato “pkg.módulo:chamável” e o arquivo será executado importando “pkg.módulo” e executando o chamável fornecido sem argumentos. É um erro omitir main se a fonte for um diretório e não contiver um arquivo __main__.py, pois, caso contrário, o arquivo resultante não seria executável.

O argumento opcional filter especifica uma função de retorno de chamada que recebe um objeto Path representando o caminho para o arquivo que está sendo adicionado (relativo ao diretório da fonte). Ele deve retornar True se o arquivo for adicionado.

O argumento opcional compressed determina se os arquivos são compactados. Se definido como True, os arquivos no arquivo são compactados com o método deflate; caso contrário, os arquivos são armazenados descompactados. Este argumento não tem efeito ao copiar um arquivo existente.

Se um objeto arquivo for especificado para source ou target, é responsabilidade do chamador fechá-lo após chamar create_archive.

Ao copiar um arquivo existente, os objetos arquivo fornecidos precisam apenas dos métodos read e readline ou write. Ao criar um arquivo de um diretório, se o alvo for um objeto arquivo, ele será passado para a classe zipfile.ZipFile e deve fornecer os métodos necessários para essa classe.

Novo na versão 3.7: Added the filter and compressed arguments.

zipapp.get_interpreter(archive)

Retorna o interpretador especificado na linha #! no início do arquivo. Se não houver nenhuma linha #!, retorna None. O argumento archive pode ser um nome de arquivo ou um objeto arquivo ou similar aberto para leitura no modo bytes. É presumido esteja no início do arquivo.

Exemplos

Compacte um diretório em um arquivo e execute-o.

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

O mesmo pode ser feito usando a função create_archive():

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

Para tornar o aplicativo diretamente executável no POSIX, especifique um interpretador a ser usado.

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

Para substituir a linha shebang em um arquivo existente, crie um arquivo modificado usando a função create_archive():

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

Para atualizar o arquivo no local, faça a substituição na memória usando um objeto BytesIO e, em seguida, sobrescreva a fonte depois. Observe que há um risco ao sobrescrever um arquivo no local de que um erro resultará na perda do arquivo original. Este código não protege contra tais erros, mas o código de produção deve fazê-lo. Além disso, este método só funcionará se o arquivo couber na memória:

>>> 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())

Especificando o interpretador

Observe que se você especificar um interpretador e então distribuir seu arquivo de aplicação, você precisa garantir que o interpretador usado seja portátil. O inicializador Python para Windows oferece suporte às formas mais comuns da linha POSIX #!, mas há outras questões a serem consideradas:

  • Se você usar “/usr/bin/env python” (ou outras formas do comando “python”, como “/usr/bin/python”), você precisa considerar que seus usuários podem ter Python 2 ou Python 3 como padrão, e escrever seu código para funcionar em ambas as versões.

  • Se você usar uma versão explícita, por exemplo “/usr/bin/env python3”, sua aplicação não funcionará para usuários que não tenham essa versão. (Isso pode ser o que você quer se não tiver tornado seu código compatível com Python 2).

  • Não há como dizer “python X.Y ou posterior”, então tome cuidado ao usar uma versão exata como “/usr/bin/env python3.4”, pois você precisará alterar sua linha shebang para usuários do Python 3.5, por exemplo.

Normalmente, você deve usar “/usr/bin/env python2” ou “/usr/bin/env python3”, dependendo se seu código foi escrito para Python 2 ou 3.

Criando aplicações autônomas com zipapp

Usando o módulo zipapp, é possível criar programas Python autocontidos, que podem ser distribuídos para usuários finais que precisam apenas ter uma versão adequada do Python instalada em seu sistema. A chave para fazer isso é agrupar todas as dependências da aplicação no arquivo, junto com o código da aplicação.

As etapas para criar um arquivo autônomo são as seguintes:

  1. Crie sua aplicação em um diretório normalmente, para que você tenha um diretório myapp contendo um arquivo __main__.py e qualquer código de aplicação de suporte.

  2. Instale todas as dependências da sua aplicação no diretório myapp, usando pip:

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

    (isso presume que você tenha os requisitos do seu projeto em um arquivo requirements.txt - caso contrário, você pode simplesmente listar as dependências manualmente na linha de comando do pip).

  3. Optionally, delete the .dist-info directories created by pip in the myapp directory. These hold metadata for pip to manage the packages, and as you won’t be making any further use of pip they aren’t required - although it won’t do any harm if you leave them.

  4. Empacote a aplicação usando:

    $ python -m zipapp -p "interpreter" myapp

Isso produzirá um executável autônomo, que pode ser executado em qualquer máquina com o interpretador apropriado disponível. Veja Especificando o interpretador para detalhes. Ele pode ser enviado aos usuários como um único arquivo.

No Unix, o arquivo myapp.pyz é executável como está. Você pode renomear o arquivo para remover a extensão .pyz se preferir um nome de comando “simples”. No Windows, o arquivo myapp.pyz[w] é executável em virtude do fato de que o interpretador Python registra as extensões de arquivo .pyz e .pyzw quando instalado.

Making a Windows executable

On Windows, registration of the .pyz extension is optional, and furthermore, there are certain places that don’t recognise registered extensions “transparently” (the simplest example is that subprocess.run(['myapp']) won’t find your application - you need to explicitly specify the extension).

On Windows, therefore, it is often preferable to create an executable from the zipapp. This is relatively easy, although it does require a C compiler. The basic approach relies on the fact that zipfiles can have arbitrary data prepended, and Windows exe files can have arbitrary data appended. So by creating a suitable launcher and tacking the .pyz file onto the end of it, you end up with a single-file executable that runs your application.

A suitable launcher can be as simple as the following:

#define Py_LIMITED_API 1
#include "Python.h"

#define WIN32_LEAN_AND_MEAN
#include <windows.h>

#ifdef WINDOWS
int WINAPI wWinMain(
    HINSTANCE hInstance,      /* handle to current instance */
    HINSTANCE hPrevInstance,  /* handle to previous instance */
    LPWSTR lpCmdLine,         /* pointer to command line */
    int nCmdShow              /* show state of window */
)
#else
int wmain()
#endif
{
    wchar_t **myargv = _alloca((__argc + 1) * sizeof(wchar_t*));
    myargv[0] = __wargv[0];
    memcpy(myargv + 1, __wargv, __argc * sizeof(wchar_t *));
    return Py_Main(__argc+1, myargv);
}

If you define the WINDOWS preprocessor symbol, this will generate a GUI executable, and without it, a console executable.

To compile the executable, you can either just use the standard MSVC command line tools, or you can take advantage of the fact that distutils knows how to compile Python source:

>>> from distutils.ccompiler import new_compiler
>>> import distutils.sysconfig
>>> import sys
>>> import os
>>> from pathlib import Path

>>> def compile(src):
>>>     src = Path(src)
>>>     cc = new_compiler()
>>>     exe = src.stem
>>>     cc.add_include_dir(distutils.sysconfig.get_python_inc())
>>>     cc.add_library_dir(os.path.join(sys.base_exec_prefix, 'libs'))
>>>     # First the CLI executable
>>>     objs = cc.compile([str(src)])
>>>     cc.link_executable(objs, exe)
>>>     # Now the GUI executable
>>>     cc.define_macro('WINDOWS')
>>>     objs = cc.compile([str(src)])
>>>     cc.link_executable(objs, exe + 'w')

>>> if __name__ == "__main__":
>>>     compile("zastub.c")

The resulting launcher uses the “Limited ABI”, so it will run unchanged with any version of Python 3.x. All it needs is for Python (python3.dll) to be on the user’s PATH.

For a fully standalone distribution, you can distribute the launcher with your application appended, bundled with the Python “embedded” distribution. This will run on any PC with the appropriate architecture (32 bit or 64 bit).

Advertência

There are some limitations to the process of bundling your application into a single file. In most, if not all, cases they can be addressed without needing major changes to your application.

  1. Se sua aplicação depende de um pacote que inclui uma extensão C, esse pacote não pode ser executado a partir de um arquivo zip (essa é uma limitação do sistema operacional, pois o código executável deve estar presente no sistema de arquivos para que o carregador do sistema operacional o carregue). Nesse caso, você pode excluir essa dependência do arquivo zip e exigir que seus usuários o tenham instalado ou enviá-lo junto com seu arquivo zip e adicionar código ao seu __main__.py para incluir o diretório que contém o módulo descompactado em sys.path. Nesse caso, você precisará certificar-se de enviar binários apropriados para sua(s) arquitetura(s) de destino (e potencialmente escolher a versão correta para adicionar ao sys.path no tempo de execução, com base na máquina do usuário).

  2. If you are shipping a Windows executable as described above, you either need to ensure that your users have python3.dll on their PATH (which is not the default behaviour of the installer) or you should bundle your application with the embedded distribution.

  3. The suggested launcher above uses the Python embedding API. This means that in your application, sys.executable will be your application, and not a conventional Python interpreter. Your code and its dependencies need to be prepared for this possibility. For example, if your application uses the multiprocessing module, it will need to call multiprocessing.set_executable() to let the module know where to find the standard Python interpreter.

O formato de arquivo da aplicação zip Python

O Python tem sido capaz de executar arquivos zip que contêm um arquivo __main__.py desde a versão 2.6. Para ser executado pelo Python, um arquivo de aplicação simplesmente tem que ser um arquivo zip padrão contendo um arquivo __main__.py que será executado como o ponto de entrada para o aplicativo. Como de costume para qualquer script Python, o pai do script (neste caso, o arquivo zip) será colocado em sys.path e, portanto, outros módulos podem ser importados do arquivo zip.

O formato de arquivo zip permite que dados arbitrários sejam prefixados a um arquivo zip. O formato de aplicação zip usa essa habilidade para prefixar uma linha “shebang” padrão POSIX ao arquivo (#!/caminho/para/interpretador).

Formalmente, o formato de aplicação zip Python é:

  1. An optional shebang line, containing the characters b'#!' followed by an interpreter name, and then a newline (b'\n') character. The interpreter name can be anything acceptable to the OS “shebang” processing, or the Python launcher on Windows. The interpreter should be encoded in UTF-8 on Windows, and in sys.getfilesystemencoding() on POSIX.

  2. Dados padrão do zipfile, conforme gerados pelo módulo zipfile. O conteúdo do zipfile deve incluir um arquivo chamado __main__.py (que deve estar na “raiz” do zipfile - ou seja, não pode estar em um subdiretório). Os dados do zipfile podem ser compactados ou descompactados.

Se um arquivo de aplicação tiver uma linha shebang, ele poderá ter o bit executável definido em sistemas POSIX, para permitir que seja executado diretamente.

Não há exigência de que as ferramentas neste módulo sejam usadas para criar arquivos de aplicações - o módulo é uma conveniência, mas arquivos no formato acima criados por qualquer meio são aceitáveis ​para Python.