32.10. py_compile — Compilar arquivos fonte do Python

Código-Fonte: Lib/py_compile.py

O módulo py_compile fornece uma função para gerar um arquivo de bytecode a partir de um arquivo fonte, e outra função usada quando o arquivo fonte do módulo é chamado como um script.

Embora nem sempre seja necessária, essa função pode ser útil ao instalar módulos para uso compartilhado, especialmente se alguns usuários não tiverem permissão para gravar os arquivos de cache de bytecodes no diretório que contém o código-fonte.

exception py_compile.PyCompileError

Exceção levantada quando ocorre um erro ao tentar compilar o arquivo.

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1)

Compila um arquivo fonte para bytecode e grava o arquivo de cache de bytecode. O código-fonte é carregado a partir do arquivo chamado file. O bytecode é gravado em cfile, cujo padrão é o caminho PEP 3147/PEP 488, terminando em .pyc. Por exemplo, se file for /foo/bar/baz.py, o cfile será padronizado como /foo/bar/__pycache__/baz.cpython-32.pyc para o Python 3.2. Se dfile for especificado, ele será usado como o nome do arquivo fonte nas mensagens de erro quando em vez de file. Se doraise for verdadeiro, a PyCompileError será levantada quando um erro for encontrado durante a compilação de file. Se doraise for false (o padrão), uma string de erros será gravada em sys.stderr, mas nenhuma exceção será gerada. Essa função retorna o caminho para o arquivo compilado em bytes, ou seja, qualquer valor cfile foi usado.

Se o caminho que cfile se tornar (especificado ou computado explicitamente) for um link simbólico ou um arquivo não regular, FileExistsError será levantada. Isso serve como um aviso de que a importação transformará esses caminhos em arquivos regulares se for permitido gravar arquivos compilados em bytes nesses caminhos. Esse é um efeito colateral da importação usando a renomeação de arquivo para colocar o arquivo final compilado em bytecode para evitar problemas de gravação simultânea de arquivos.

optimize controla o nível de otimização e é passado para a função interna compile(). O padrão de -1 seleciona o nível de otimização do interpretador atual.

Alterado na versão 3.2: Alterado o valor padrão de cfile para ficar em conformidade com a PEP 3147. O padrão anterior era file + 'c' ('o' se a otimização estivesse ativada). Também foi adicionado o parâmetro optimize.

Alterado na versão 3.4: Alterado o código para usar importlib para a gravação do arquivo de cache do bytecode. Isso significa que a semântica de criação/gravação de arquivo agora corresponde ao que importlib faz, por exemplo, permissões, semântica de gravação e movimentação, etc. Também foi adicionada a ressalva de que FileExistsError é levantada se cfile for um link simbólico ou um arquivo não regular.

py_compile.main(args=None)

Compila vários arquivos fonte. Os arquivos nomeados em args (ou na linha de comando, se args for None) são compilados e o bytecode resultante é armazenado em cache da maneira normal. Esta função não pesquisa uma estrutura de diretórios para localizar arquivos fonte; ela apenas compila arquivos nomeados explicitamente. Se '-' é o único parâmetro em args, a lista de arquivos é obtida da entrada padrão.

Alterado na versão 3.2: Adicionado suporte a '-'.

Quando este módulo é executado como um script, main() é usada para compilar todos os arquivos nomeados na linha de comando. O status de saída é diferente de zero se um dos arquivos não pôde ser compilado.

Ver também

Módulo compileall

Utilitários para compilar todos os arquivos fontes Python em uma árvore de diretórios.