"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.


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.

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

   Controla como os arquivos de bytecode gerados são invalidados no
   tempo de execução. O valor "timestamp" significa que os arquivos
   ".pyc" com o carimbo de data/hora do fonte e o tamanho incorporado
   serão gerados. Os valores "selected-hash" e "unchecked-hash" fazem
   com que os pycs baseados em hash sejam gerados. Arquivos pycs
   baseados em hash incorporam um hash do conteúdo do arquivo fonte em
   vez de um carimbo de data/hora. Veja Cached bytecode invalidation
   para obter mais informações sobre como o Python valida os arquivos
   de cache do bytecode em tempo de execução. O padrão é "timestamp"
   se a variável de ambiente "SOURCE_DATE_EPOCH" não estiver
   configurada e "selected-hash" se a variável de ambiente
   "SOURCE_DATE_EPOCH" estiver configurada.

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".

Alterado na versão 3.7: Adicionada a opção "--invalidation-mode".

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**.

Da mesma forma, a função "compile()" respeita a configuração
"sys.pycache_prefix". O cache do bytecode gerado somente será útil se
"compile()" for executado com o mesmo "sys.pycache_prefix" (se houver)
que será usado em tempo de execução.


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

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

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

   O argumento *workers* especifica quantos workers são usados para
   compilar arquivos em paralelo. O padrão é não usar vários workers.
   Se a plataforma não puder usar vários workers e o argumento
   *workers* for fornecido, a compilação sequencial será usada como
   reserva. Se *workers* for 0, o número de núcleos no sistema é
   usado. Se *workers* for menor que "0", a "ValueError" será
   levantada.

   *invalidation_mode* deve ser um membro de enum
   "py_compile.PycInvalidationMode" e controla como os pycs gerados
   são invalidados em tempo de execução.

   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 *objeto caminho ou similar*.

   Alterado na versão 3.7: O parâmetro *invalidation_mode* foi
   adicionado.

   Alterado na versão 3.7.2: O valor padrão do parâmetro
   *invalidation_mode* é atualizado para None.

   Alterado na versão 3.8: A definição de *workers* como 0 agora
   escolhe o número ideal de núcleos.

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

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

   *invalidation_mode* deve ser um membro de enum
   "py_compile.PycInvalidationMode" e controla como os pycs gerados
   são invalidados em tempo de execução.

   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*.

   Alterado na versão 3.7: O parâmetro *invalidation_mode* foi
   adicionado.

   Alterado na versão 3.7.2: O valor padrão do parâmetro
   *invalidation_mode* é atualizado para None.

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

   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*.

   Alterado na versão 3.7: O parâmetro *invalidation_mode* foi
   adicionado.

   Alterado na versão 3.7.2: O valor padrão do parâmetro
   *invalidation_mode* é atualizado para None.

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.
