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.
