ansible argspec gen

Gerador de especificação de argumento Ansible

Este pacote contém código para o programa de especificação de argumentos Ansible. Seu principal público são os mantenedores de módulos Ansible que gostariam de reduzir a duplicação em seus módulos, gerando a especificação de argumento diretamente a partir da documentação do usuário do módulo.

Investir rápido

O extrator de documentação é publicado no Pypi e podemos instalá -lo usando pip :

 $ PIP Instalar Ansible-ArgSpec-Gen [base] # Isso instalará a base Ansible
$ PIP Instalar Ansible-ArgSpec-Gen [Ansible] # Isso instalará Ansible
$ pip instalar Ansible-ArgSpec-Gen # Precisamos instalar Ansible ou
                                            # Ansible-Base nós mesmos

Se o comando anterior não falhar, estamos prontos para começar a atualizar nossos módulos. Quando usamos o gerador pela primeira vez, precisamos executar as três etapas a seguir:

1. Adicione dois comentários à fonte do módulo que marcará o local para o código gerado. Por padrão, o gerador pesquisou o comentário do # AUTOMATIC MODULE ARGUMENTS , mas isso pode ser alterado com o parâmetro --marker Command-Line.
2. Execute o gerador, possivelmente no modo seco e diff primeiro para identificar quaisquer problemas.
3. Remova todos os remanescentes escritos à mão que não são mais necessários.

Por exemplo, vamos supor que as primeiras linhas da função principal do nosso módulo se parecem com isso antes da execução do gerador:

 def main ():
    # Argumentos do módulo automático
    # Argumentos do módulo automático

    módulo = AnsiBlemodule (

Se executarmos o gerador agora no modo de cheque com diferença que pretende ligar, receberemos de volta algo assim:

 $ Ansible-ArgSpec-Gen-Diff-plugins/módulos de corrida-dry/rota.py
--- ../ansible_collections/steampunk/nginx_unit/plugins/modules/route.py.old
+++ ../ansible_collections/steampunk/nginx_unit/plugins/modules/route.py.new
@@ -359,6 +359,52 @@

 def main ():
     # Argumentos do módulo automático
+ argument_spec = {
+ "global": {"padrão": false, "tipo": "bool"},
+ "nome": {"type": "str"},
+ "soquete": {"tipo": "caminho"},
+ "estado": {
+ "escolhas": ["presente", "ausente"],
+ "padrão": "presente",
+ "tipo": "str",
+},
+}
+ requerir_if = [("global", false, ("nome",)), ("estado", "presente", ("etapa",))]]
     # Argumentos do módulo automático

     módulo = AnsiBlemodule (

Uma vez felizes com as alterações propostas, podemos escrevê -las no arquivo:

 $ ANSIBLE-ARGSPEC-GEN Plugins/Modules/Route.py

Se atualizarmos a documentação do módulo, podemos simplesmente executar novamente o comando e o gerador anteriores levarão ou atualizarão a especificação. Observe que o gerador substituirá o conteúdo entre os marcadores, portanto, não modifique manualmente essa parte do arquivo ou você perderá as alterações na próxima atualização.

Escrevendo documentação do módulo

A geração de especificação de argumentos para a classe AnsibleModule deve funcionar em qualquer módulo que tenha uma documentação. Mas fazer com que o gerador produza outros parâmetros, como requisitos condicionais, exige um pouco de trabalho.

Para gerar uma especificação required_if , nossos parâmetros precisam ter uma frase em sua descrição que se encaixa no modelo necessário se i ({param_name}) for c ({param_value}) . O próximo exemplo:

 Opções:
  nome:
    descrição:
      - Nome do recurso. Exigido se eu (estado) for c (presente).

produzirá a seguinte especificação:

 requerir_if = [("estado", "presente", ("nome",))]]

Outra coisa que o gerador sabe como produzir é a especificação mutually_exclusive . O padrão que o gerador está procurando neste caso é mutuamente exclusivo com i ({param1}), i ({param2}) e ​​i ({param3}) , onde o número de parâmetros que podemos especificar não é limitado. Exemplo:

 Opções:
  processos:
    descrição:
      - Limites dinâmicos do processo.
      - mutuamente exclusivo com i (não -processos).
  No_processos:
    descrição:
      - Limite de processo estático.
      - mutuamente exclusivo com i (processos).

Isso produzirá:

 mutuamente_exclusive = [("no_processos", "processos")]]

Configuração de desenvolvimento

Obter o ambiente de desenvolvimento em funcionamento é relativamente simples se tivermos pipenv instalado:

 Atualização $ PIPENV

Para testar o extrator, podemos executar:

 $ PIPENV RUN ANSIBLE-ARGSPEC-GEN