module_ctx

Informar um problema Ver fonte Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

O contexto da extensão do módulo que contém funções auxiliares e informações sobre tags relevantes no gráfico de dependências. Você recebe um objeto module_ctx como argumento para a função implementation ao criar uma extensão de módulo.

Membros

download

unknown module_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True)

Faz o download de um arquivo para o caminho de saída do URL fornecido e retorna uma struct que contém success, uma flag que é true se o download for concluído, e, se for bem-sucedido, um hash do arquivo com os campos sha256 e integrity. Quando sha256 ou integrity é especificado pelo usuário, é altamente recomendável definir um canonical_id explícito. Por exemplo, get_default_canonical_id

Parâmetros

Parâmetro Descrição
url string ou iterável de strings; required
Lista de URLs espelhados que referenciam o mesmo arquivo.
output string; ou Label; ou path; o padrão é ''
caminho para o arquivo de saída, relativo ao diretório do repositório.
sha256 O padrão é ''
O hash SHA-256 esperado do arquivo baixado. Ele precisa corresponder ao hash SHA-256 do arquivo baixado. Omitir o SHA-256 é um risco de segurança, já que os arquivos remotos podem mudar. Na melhor das hipóteses, omitir esse campo vai tornar seu build não hermético. É opcional para facilitar o desenvolvimento, mas precisa ser definido antes do envio. Se fornecido, o cache do repositório será verificado primeiro em busca de um arquivo com o hash especificado. O download só será tentado se o arquivo não for encontrado no cache. Depois de um download bem-sucedido, o arquivo será adicionado ao cache.
executable O padrão é False
Defina a flag executável no arquivo criado. O padrão é "false".
allow_fail O padrão é False
. Se definido, indica o erro no valor de retorno em vez de gerar um erro para downloads com falha.
canonical_id O padrão é ''
. Se definido, restringe os acertos de cache aos casos em que o arquivo foi adicionado ao cache com o mesmo ID canônico. Por padrão, o armazenamento em cache usa o checksum (sha256 ou integrity).
auth O padrão é {}
. Um dicionário opcional que especifica informações de autenticação para alguns dos URLs.
headers O padrão é {}
Um dicionário opcional que especifica cabeçalhos HTTP para todos os URLs.
integrity O padrão é ''
Soma de verificação esperada do arquivo baixado, no formato de integridade de subrecursos. Ele precisa corresponder ao checksum do arquivo baixado. Omitir o checksum é um risco de segurança, já que os arquivos remotos podem mudar. Na melhor das hipóteses, omitir esse campo vai tornar seu build não hermético. É opcional para facilitar o desenvolvimento, mas precisa ser definido antes do envio. Se fornecido, o cache do repositório será verificado primeiro para um arquivo com o checksum especificado. Um download só será tentado se o arquivo não for encontrado no cache. Depois de um download bem-sucedido, o arquivo será adicionado ao cache.
block O padrão é True
. Se definido como "false", a chamada será retornada imediatamente e, em vez do valor de retorno regular, ela vai retornar um token com um único método, wait(), que bloqueia até que o download seja concluído e retorna o valor de retorno usual ou gera uma exceção como de costume.

download_and_extract

struct module_ctx.download_and_extract(url, output='', sha256='', type='', stripPrefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={})

Faz o download de um arquivo para o caminho de saída do URL fornecido, extrai e retorna uma struct que contém success, uma flag que é true se o download for concluído com êxito e, se for bem-sucedido, um hash do arquivo com os campos sha256 e integrity. Quando sha256 ou integrity é especificado pelo usuário, é altamente recomendável definir um canonical_id explícito. Por exemplo, get_default_canonical_id

Parâmetros

Parâmetro Descrição
url string ou iterável de strings; required
Lista de URLs espelhados que referenciam o mesmo arquivo.
output string; ou Label; ou path; o padrão é ''
Caminho para o diretório em que o arquivo será descompactado, relativo ao diretório do repositório.
sha256 O padrão é ''
O hash SHA-256 esperado do arquivo baixado. Ele precisa corresponder ao hash SHA-256 do arquivo baixado. Omitir o SHA-256 é um risco de segurança, já que os arquivos remotos podem mudar. Na melhor das hipóteses, omitir esse campo vai tornar seu build não hermético. É opcional para facilitar o desenvolvimento, mas precisa ser definido antes do envio. Se fornecido, o cache do repositório será verificado primeiro em busca de um arquivo com o hash especificado. O download só será tentado se o arquivo não for encontrado no cache. Depois de um download bem-sucedido, o arquivo será adicionado ao cache.
type O padrão é ''
O tipo de arquivo do arquivo baixado. Por padrão, o tipo de arquivo é determinado pela extensão do arquivo do URL. Se o arquivo não tiver uma extensão, especifique "zip", "jar", "war", "aar", "nupkg", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar" ou ".deb".
stripPrefix O padrão é ''
Um prefixo de diretório a ser removido dos arquivos extraídos. Muitos arquivos contêm um diretório de nível superior com todos os arquivos do arquivo. Em vez de precisar especificar esse prefixo várias vezes no build_file, esse campo pode ser usado para removê-lo dos arquivos extraídos.
allow_fail O padrão é False
. Se definido, indica o erro no valor de retorno em vez de gerar um erro para downloads com falha.
canonical_id O padrão é ''
. Se definido, restringe os acertos de cache aos casos em que o arquivo foi adicionado ao cache com o mesmo ID canônico. Por padrão, o armazenamento em cache usa o checksum" (sha256 ou integrity).
auth O padrão é {}
. Um dicionário opcional que especifica informações de autenticação para alguns dos URLs.
headers O padrão é {}
Um dicionário opcional que especifica cabeçalhos HTTP para todos os URLs.
integrity O padrão é ''
Soma de verificação esperada do arquivo baixado, no formato de integridade de subrecursos. Ele precisa corresponder ao checksum do arquivo baixado. Omitir o checksum é um risco de segurança, já que os arquivos remotos podem mudar. Na melhor das hipóteses, omitir esse campo vai tornar seu build não hermético. É opcional para facilitar o desenvolvimento, mas precisa ser definido antes do envio. Se fornecido, o cache do repositório será verificado primeiro para um arquivo com o checksum especificado. Um download só será tentado se o arquivo não for encontrado no cache. Depois de um download bem-sucedido, o arquivo será adicionado ao cache.
rename_files O padrão é {}
Um dicionário opcional que especifica os arquivos a serem renomeados durante a extração. As entradas de arquivo com nomes que correspondem exatamente a uma chave serão renomeadas para o valor antes de qualquer ajuste de prefixo de diretório. Isso pode ser usado para extrair arquivos que contêm nomes de arquivos não Unicode ou que têm arquivos que seriam extraídos para o mesmo caminho em sistemas de arquivos sem diferenciação de maiúsculas e minúsculas.

execute

exec_result module_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="")

Executa o comando fornecido pela lista de argumentos. O tempo de execução do comando é limitado por timeout (em segundos, padrão de 600 segundos). Esse método retorna uma estrutura exec_result que contém a saída do comando. O mapa environment pode ser usado para substituir algumas variáveis de ambiente que serão transmitidas ao processo.

Parâmetros

Parâmetro Descrição
arguments obrigatório
Lista de argumentos. O primeiro elemento precisa ser o caminho para o programa a ser executado.
timeout O padrão é 600
. Duração máxima do comando em segundos (o padrão é 600 segundos).
environment O padrão é {}
. Força a definição de algumas variáveis de ambiente para serem transmitidas ao processo.
quiet O padrão é True
Se stdout e stderr devem ser impressos no terminal.
working_directory O padrão é ""
Diretório de trabalho para execução de comandos. Pode ser relativo à raiz do repositório ou absoluto. O padrão é o repositório raiz.

extension_metadata

extension_metadata module_ctx.extension_metadata(root_module_direct_deps=None, root_module_direct_dev_deps=None, reproducible=False)

Cria um objeto opaco que pode ser retornado da função de implementação da extensão do módulo para fornecer metadados sobre os repositórios gerados pela extensão ao Bazel.

Parâmetros

Parâmetro Descrição
root_module_direct_deps sequência de strings; ou string; ou None; o padrão é None
Os nomes dos repositórios que a extensão considera dependências diretas do módulo raiz. Se o módulo raiz importar outros repositórios ou não importar todos eles usando use_repo, o Bazel vai mostrar um aviso quando a extensão for avaliada, instruindo o usuário a executar bazel mod tidy para corrigir as chamadas use_repo automaticamente.

Se um dos root_module_direct_deps e vai imprimir um aviso e um comando de correção quando a extensão for avaliada.

Se um dos campos root_module_direct_deps e root_module_direct_dev_deps for especificado, o outro também precisará ser. As listas especificadas por esses dois parâmetros não podem ter elementos em comum.

Exatamente um de root_module_direct_deps e root_module_direct_dev_deps pode ser definido como o valor especial "all", que é tratado como se uma lista com os nomes de todos os repositórios gerados pela extensão fosse especificada como o valor.

root_module_direct_dev_deps sequência de strings; ou string; ou None; o padrão é None
Os nomes dos repositórios que a extensão considera como dependências de desenvolvimento diretas do módulo raiz. Se o módulo raiz importar outros repositórios ou não importar todos eles usando use_repo em um proxy de extensão criado com use_extension(..., dev_dependency = True), o Bazel vai mostrar um aviso quando a extensão for avaliada, instruindo o usuário a executar bazel mod tidy para corrigir as chamadas use_repo automaticamente.

Se um dos campos root_module_direct_deps e root_module_direct_dev_deps for especificado, o outro também precisará ser. As listas especificadas por esses dois parâmetros não podem ter elementos em comum.

Exatamente um de root_module_direct_deps e root_module_direct_dev_deps pode ser definido como o valor especial "all", que é tratado como se uma lista com os nomes de todos os repositórios gerados pela extensão fosse especificada como o valor.

reproducible bool; o padrão é False
Declara que essa extensão de módulo garante a reprodutibilidade completa e, portanto, não deve ser armazenada no arquivo de bloqueio.

extrair

None module_ctx.extract(archive, output='', stripPrefix='', *, rename_files={}, watch_archive='auto')

Extraia um arquivo para o diretório do repositório.

Parâmetros

Parâmetro Descrição
archive string, Label ou path; required
caminho para o arquivo que será descompactado, relativo ao diretório do repositório.
output string; ou Label; ou path; o padrão é ''
caminho para o diretório em que o arquivo será descompactado, relativo ao diretório do repositório.
stripPrefix O padrão é ''
, um prefixo de diretório a ser removido dos arquivos extraídos. Muitos arquivos contêm um diretório de nível superior com todos os arquivos do arquivo. Em vez de precisar especificar esse prefixo várias vezes no build_file, esse campo pode ser usado para removê-lo dos arquivos extraídos.
rename_files O padrão é {}
Um dicionário opcional que especifica os arquivos a serem renomeados durante a extração. As entradas de arquivo com nomes que correspondem exatamente a uma chave serão renomeadas para o valor antes de qualquer ajuste de prefixo de diretório. Isso pode ser usado para extrair arquivos que contêm nomes de arquivos não Unicode ou que têm arquivos que seriam extraídos para o mesmo caminho em sistemas de arquivos sem diferenciação de maiúsculas e minúsculas.
watch_archive O padrão é 'auto'
para monitorar o arquivo. Pode ser a string "yes", "no" ou "auto". Transmitir "yes" é equivalente a invocar imediatamente o método watch(). Transmitir "no" não tenta monitorar o arquivo. Transmitir "auto" só tenta monitorar o arquivo quando isso é permitido (consulte os documentos watch() para mais informações).

arquivo

None module_ctx.file(path, content='', executable=True, legacy_utf8=True)

Gera um arquivo no diretório do repositório com o conteúdo fornecido.

Parâmetros

Parâmetro Descrição
path string; ou Label; ou path; required
Caminho do arquivo a ser criado, relativo ao diretório do repositório.
content O padrão é ''
O conteúdo do arquivo a ser criado, vazio por padrão.
executable O padrão é True
Defina a flag executável no arquivo criado, que é "true" por padrão.
legacy_utf8 O padrão é True
Codifica o conteúdo do arquivo em UTF-8, o padrão é "true". Versões futuras vão mudar o padrão e remover esse parâmetro.

getenv

string module_ctx.getenv(name, default=None)

Retorna o valor de uma variável de ambiente name como uma string, se existir, ou default, se não existir.

Ao criar incrementalmente, qualquer mudança no valor da variável nomeada por name fará com que esse repositório seja buscado novamente.

Parâmetros

Parâmetro Descrição
name string; required
Nome da variável de ambiente desejada.
default string ou None; o padrão é None
. Valor padrão a ser retornado se name não for encontrado.
Pode retornar None.

is_dev_dependency

bool module_ctx.is_dev_dependency(tag)

Retorna se a tag especificada foi informada no resultado de uma chamada use_extension com devDependency = True.

Parâmetros

Parâmetro Descrição
tag bazel_module_tag; required
A tag obtida de bazel_module.tags.

modules

list module_ctx.modules

Uma lista de todos os módulos do Bazel no gráfico de dependência externa que usam essa extensão de módulo. Cada um deles é um objeto bazel_module que expõe todas as tags especificadas para essa extensão. A ordem de iteração desse dicionário é garantida como sendo a mesma da pesquisa em largura que começa no módulo raiz.

os

repository_os module_ctx.os

Uma struct para acessar informações do sistema.

caminho

path module_ctx.path(path)

Retorna um caminho de uma string, um rótulo ou um caminho. Se o caminho for relativo, ele será resolvido em relação ao diretório do repositório. Se o caminho for um rótulo, ele será resolvido para o caminho do arquivo correspondente. Os repositórios remotos são executados durante a fase de análise e, portanto, não podem depender de um resultado de destino. O rótulo precisa apontar para um arquivo não gerado. Se o caminho for um caminho, ele será retornado como está.

Parâmetros

Parâmetro Descrição
path string; ou Label; ou path; required
string, Label ou path de onde criar um caminho.

ler

string module_ctx.read(path, *, watch='auto')

Lê o conteúdo de um arquivo no sistema de arquivos.

Parâmetros

Parâmetro Descrição
path string; ou Label; ou path; required
Caminho do arquivo a ser lido.
watch O padrão é 'auto'
. Se o arquivo será monitorado. Pode ser a string "yes", "no" ou "auto". Transmitir "yes" é equivalente a invocar imediatamente o método watch(). Transmitir "no" não tenta monitorar o arquivo. Transmitir "auto" só tenta monitorar o arquivo quando isso é permitido (consulte os documentos watch() para mais informações).

report_progress

None module_ctx.report_progress(status='')

Atualiza o status do progresso da busca desta extensão de repositório ou módulo.

Parâmetros

Parâmetro Descrição
status string; o padrão é ''
string que descreve o status atual do progresso da busca.

root_module_has_non_dev_dependency

bool module_ctx.root_module_has_non_dev_dependency

Indica se o módulo raiz usa essa extensão como uma dependência não de desenvolvimento.

relógio

None module_ctx.watch(path)

Diz ao Bazel para ficar atento a mudanças no caminho especificado, independente de ele existir ou ser um arquivo ou diretório. Qualquer mudança no arquivo ou diretório vai invalidar esse repositório ou extensão de módulo, fazendo com que ele seja buscado ou reavaliado na próxima vez.

"Mudanças" incluem alterações no conteúdo do arquivo (se o caminho for um arquivo), se o caminho era um arquivo, mas agora é um diretório ou vice-versa, e se o caminho começa ou deixa de existir. É importante lembrar que isso não inclui mudanças em arquivos no diretório se o caminho for um diretório. Para isso, use path.readdir().

A tentativa de observar caminhos dentro do repositório que está sendo buscado ou dentro do diretório de trabalho da extensão do módulo atual vai resultar em um erro. Uma extensão de módulo que tenta observar um caminho fora do espaço de trabalho atual do Bazel também resulta em um erro.

Parâmetros

Parâmetro Descrição
path string; ou Label; ou path; required
Caminho do arquivo a ser monitorado.

qual

path module_ctx.which(program)

Retorna o path do programa correspondente ou None se não houver um programa desse tipo no caminho.

Parâmetros

Parâmetro Descrição
program required
Programa a ser encontrado no caminho.
Pode retornar None.