32.11. "compileall" --- Compilar bibliotecas do Python para bytecode
********************************************************************

**Código Fonte:** Lib/compileall.py

======================================================================

Este módulo fornece algumas funções utilitárias para dar suporte à
instalação de bibliotecas Python. Essas funções compilam arquivos
fonte Python em uma árvore de diretórios. Este módulo pode ser usado
para criar os arquivos de bytecodes em cache no momento da instalação
da biblioteca, o que os torna disponíveis para uso mesmo por usuários
que não têm permissão de gravação nos diretórios da biblioteca.


32.11.1. Uso na linha de comando
================================

Este módulo pode funcionar como um script (usando **python -m
compileall**) para compilar fontes do Python.

directory ...
file ...

   Argumentos posicionais são arquivos a serem compilados ou
   diretórios que contêm arquivos de origem, percorridos
   recursivamente. Se nenhum argumento for fornecido, comporta-se como
   se a linha de comando fosse "-l <diretórios do sys.path>".

-l

   Não atua recursivamente em subdiretórios, apenas compila arquivos
   de código-fonte diretamente contidos nos diretórios nomeados ou
   implícitos.

-f

   Força a recompilação, mesmo que os carimbos de data e hora estejam
   atualizados.

-q

   Não imprime a lista de arquivos compilados. Se passado uma vez, as
   mensagens de erro ainda serão impressas. Se passado duas vezes
   ("-qq"), toda a saída é suprimida.

-d destdir

   Diretório anexado ao caminho de cada arquivo que está sendo
   compilado. Isso aparecerá nos tracebacks em tempo de compilação e
   também será compilado no arquivo de bytecode, onde será usado em
   tracebacks e outras mensagens nos casos em que o arquivo de origem
   não exista no momento em que o arquivo de bytecode for executado.

-x regex

   A expressão regular "regex" é usada para pesquisar o caminho
   completo para cada arquivo considerado para compilação e, se a
   "regex" produzir uma correspondência, o arquivo será ignorado.

-i list

   Lê o arquivo "list" e adicione cada linha que ele contém à lista de
   arquivos e diretórios a serem compilados. Se "list" for "-", lê as
   linhas do "stdin".

-b

   Escreve os arquivos de bytecode em seus locais e nomes legados, que
   podem sobrescrever arquivos de bytecode criados por outra versão do
   Python. O padrão é gravar arquivos em seus locais e nomes do **PEP
   3147**, o que permite que arquivos de bytecode de várias versões do
   Python coexistam.

-r

   Controla o nível máximo de recursão para subdiretórios. Se isso for
   dado, a opção "-l" não será levada em consideração. **python -m
   compileall <diretório> -r 0** é equivalente a **python -m
   compileall <diretório> -l**.

-j N

   Use *N* workers para compilar os arquivos dentro do diretório
   especificado. Se "0" for usado, o resultado de "os.cpu_count()"
   será usado.

Alterado na versão 3.2: Adicionadas as opções "-i", "-b" e "-h".

Alterado na versão 3.5: Adicionadas as opções "-j", "-r" e "-qq". A
opção "-q" foi alterada para um valor multinível. "-b" sempre
produzirá um arquivo de bytecodes que termina em ".pyc", nunca em
".pyo".

Não há opção na linha de comando para controlar o nível de otimização
usado pela função "compile()" porque o próprio interpretador Python já
fornece a opção: **python -O -m compileall**.


32.11.2. Funções públicas
=========================

compileall.compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1)

   Desce recursivamente a árvore de diretórios nomeada por *dir*,
   compilando todos os arquivos ".py" ao longo do caminho. Retorna um
   valor verdadeiro se todos os arquivos forem compilados com êxito e
   um valor falso caso contrário.

   O parâmetro *maxlevels* é usado para limitar a profundidade da
   recursão; o padrão é "10".

   Se *ddir* for fornecido, ele será anexado ao caminho de cada
   arquivo que está sendo compilado para uso em tracebacks em tempo de
   compilação e também será compilado no arquivo de bytecode, onde
   será usado em tracebacks e outras mensagens nos casos em que o
   arquivo de origem não existe no momento em que o arquivo de
   bytecode é executado.

   Se *force* for verdadeiro, os módulos serão recompilados, mesmo que
   os carimbos de data e hora estejam atualizados.

   Se *rx* for fornecido, seu método de pesquisa será chamado no
   caminho completo para cada arquivo considerado para compilação e,
   se retornar um valor verdadeiro, o arquivo será ignorado.

   Se *quiet* for "False" ou "0" (o padrão), os nomes dos arquivos e
   outras informações serão impressos com o padrão. Definido como "1",
   apenas os erros são impressos. Definido como "2", toda a saída é
   suprimida.

   Se *legacy* for verdadeiro, os arquivos de bytecodes serão gravados
   em seus locais e nomes herdados, o que poderá sobrescrever arquivos
   de bytecodes criados por outra versão do Python. O padrão é gravar
   arquivos em seus locais e nomes do **PEP 3147**, o que permite que
   arquivos de bytecodes de várias versões do Python coexistam.

   *optimize* especifica o nível de otimização para o compilador. Ele
   é passado para a função embutida "compile()".

   The argument *workers* specifies how many workers are used to
   compile files in parallel. The default is to not use multiple
   workers. If the platform can't use multiple workers and *workers*
   argument is given, then sequential compilation will be used as a
   fallback.  If *workers* is lower than "0", a "ValueError" will be
   raised.

   Alterado na versão 3.2: Adicionado os parâmetros *legacy* e
   *optimize*.

   Alterado na versão 3.5: Adicionado o parâmetro *workers*.

   Alterado na versão 3.5: O parâmetro *quiet* foi alterado para um
   valor multinível.

   Alterado na versão 3.5: O parâmetro *legacy* grava apenas arquivos
   ".pyc", não os arquivos ".pyo", independentemente do valor de
   *optimize*.

   Alterado na versão 3.6: Aceita um *path-like object*.

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1)

   Compila o arquivo com o caminho *fullname*. Retorna um valor
   verdadeiro se o arquivo compilado com êxito e um valor falso caso
   contrário.

   Se *ddir* for fornecido, ele será anexado ao caminho do arquivo que
   está sendo compilado para uso em rastreamentos em tempo de
   compilação e também será compilado no arquivo de bytecode, onde
   será usado em tracebacks e outras mensagens nos casos em que o
   arquivo fonte não existe no momento em que o arquivo de bytecode é
   executado.

   Se *rx* for fornecido, seu método de pesquisa passará o nome do
   caminho completo para o arquivo que está sendo compilado e, se
   retornar um valor verdadeiro, o arquivo não será compilado e "True"
   será retornado.

   Se *quiet* for "False" ou "0" (o padrão), os nomes dos arquivos e
   outras informações serão impressos com o padrão. Definido como "1",
   apenas os erros são impressos. Definido como "2", toda a saída é
   suprimida.

   Se *legacy* for verdadeiro, os arquivos de bytecodes serão gravados
   em seus locais e nomes herdados, o que poderá sobrescrever arquivos
   de bytecodes criados por outra versão do Python. O padrão é gravar
   arquivos em seus locais e nomes do **PEP 3147**, o que permite que
   arquivos de bytecodes de várias versões do Python coexistam.

   *optimize* especifica o nível de otimização para o compilador. Ele
   é passado para a função embutida "compile()".

   Novo na versão 3.2.

   Alterado na versão 3.5: O parâmetro *quiet* foi alterado para um
   valor multinível.

   Alterado na versão 3.5: O parâmetro *legacy* grava apenas arquivos
   ".pyc", não os arquivos ".pyo", independentemente do valor de
   *optimize*.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1)

   Compila Byte para bytecodes todos os arquivos ".py" encontrados ao
   longo de "sys.path". Retorna um valor verdadeiro se todos os
   arquivos forem compilados com êxito e um valor falso caso
   contrário.

   Se *skip_curdir* for verdadeiro (o padrão), o diretório atual não
   será incluído na pesquisa. Todos os outros parâmetros são passados
   para a função "compile_dir()". Note que, ao contrário das outras
   funções de compilação, "maxlevels" é padronizado como "0".

   Alterado na versão 3.2: Adicionado os parâmetros *legacy* e
   *optimize*.

   Alterado na versão 3.5: O parâmetro *quiet* foi alterado para um
   valor multinível.

   Alterado na versão 3.5: O parâmetro *legacy* grava apenas arquivos
   ".pyc", não os arquivos ".pyo", independentemente do valor de
   *optimize*.

Para forçar uma recompilação de todos os arquivos ".py" no
subdiretório "Lib/" e todos os seus subdiretórios:

   import compileall

   compileall.compile_dir('Lib/', force=True)

   # Perform same compilation, excluding files in .svn directories.
   import re
   compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

   # pathlib.Path objects can also be used.
   import pathlib
   compileall.compile_dir(pathlib.Path('Lib/'), force=True)

Ver também:

  Módulo "py_compile"
     Compila para bytecode um único arquivo fonte.
