Como utilizar o Yamllint: validador de arquivos .yaml

Um dos primeiros itens necessários para iniciar os trabalhos na disciplina de PDS é  que "após a criação da pasta no repositório Subversion um arquivo equipe.yaml deve ser criado com os dados da equipe e projeto de acordo com modelo no repositório". Estes dados nada mais são do que aqueles existentes na página Blogs de Trabalhos do Dicas Ivan, mas para que os trabalhos criados sejam expostos nesta página é preciso seguir alguns critérios na criação do arquivo, e o primeiro deles é a utilização de um validador de arquivos com extensão .yaml, isto é, o yamllint.

Diante da dificuldade de alguns colegas em validar o arquivo e após fazer algumas pesquisas sobre o validador, percebi que a maior parte dos conteúdos sobre o assunto está em inglês e, arquivos dessa natureza possuem muitas especificações minuciosas para serem validadas, e muitas vezes a documentação do yamllint não as deixa tão claras ao leitor. Por isso, resolvi compartilhar um pouco do que entendi sobre o processo de validação do arquivo, o que inclui a instalação do validador, erros comuns após a validação e a espera até que o projeto apareça na página de Blogs de Trabalhos.


O que é o yamllint e por que devo validar um arquivo .yaml?

Segundo a documentação do Yamllint, o validador é inspirado no eslint do JavaScript, uma ferramenta para análise estática do código. Isso quer dizer que seu objetivo é acusar erros (de programação e de estilo), bugs e construções suspeitas sem precisar executar o programa. Ou seja, a análise estática de um validador tem como objetivo trazer uma lista de erros, warnings e pontos de melhorias do seu código. 

O que o Yamllint faz, basicamente, é este processo de linting/análise estática do conteúdo presente em um arquivo .yaml (ou .yml), procurando, não só problemas de sintaxe, como estranhezas e problemas estilísticos. 

Ademais, a linguagem utilizada nesses arquivos, o YAML, Ã© uma "linguagem de serialização de dados" e por isso é muito usada para arquivos de configuração, pois gerenciar configurações de um projeto é importante para manter a consistência do seu sistema e para documentar mudanças nas aplicações - mas isso é assunto pra outro post.


No final, o que você precisa saber é que a formatação do seu arquivo é necessária para que o sistema que vai "lê-lo" entenda corretamente as instruções que você deseja passar. Veja algumas coisas importantes sobre a formatação de arquivos .yaml:

  • O YAML utiliza recuo no estilo Python para alinhamento;
  • Caracteres de tabulação (os chamados "\t" ou apenas "TAB")  não são permitidos, por isso utilize espaços em branco;
  • A forma que os espaços em branco estão dispostos faz diferença na formatação do arquivo e pode apontar erros no validador. Por exemplo: esquecer de colocar um espaço após o caractere ":";
  • Não há símbolos de formatos comuns, como chaves, colchetes, tags de fechamento, etc;
  • Os arquivos .yaml são estruturados em mapas ou listas;
  • As listas têm ordem específica e sua sequência começa com um traço (-) seguido de um espaço.
Existem outras coisas a se atentar, mas isso você vai descobrir quando rodar o yamllint. Se quiser saber mais sobre o YAML, recomendo ler este artigo da Red Hat (tirei algumas coisinhas de lá).

Como instalar o yamllint?


Antes de começar a falar da instalação propriamente dita, considerando que você esteja utilizando o sistema operacional Windows, é importante que você se certifique se possui o Node.js (com npm) ou o Python (com o pip) instalados em sua máquina. Caso esteja utilizando algum sistema operacional baseado em Unix, você pode verificar se possui o gerenciador de pacotes mais utilizado nele e seguir as orientações da documentação do yamllint para instalar; ou utilizar o Python mesmo (também funcionará). Mas, se preferir um caminho alternativo, siga as próximas instruções.

Em sistemas tipo Unix (alternativa)

  1. Primeiro, abra seu terminal Bash e verifique já se possui, na sua pasta $HOME, o arquivo .bash_profile (é nele que ficam suas variáveis de ambiente), com o comando open $HOME/.bash_profile;
  2. Caso ele não exista, crie-o na sua pasta de usuário e depois siga os passos para a instalação do gerenciador de pacotes Homebrew;
  3. Dependendo do seu tipo de SO, pode ser que o comando brew não funcione após a instalação, isso acontece porque você precisa criar uma variável de ambiente para ele no seu arquivo .bash_profile;
  4. Para isso, se o próprio instalador não lhe alertar sobre os próximos passos, insira com o comando: echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> $HOME/.bash_profile
  5. Depois, insira o comando  source $HOME/.bash_profile para atualizar o arquivo;
  6. Agora, basta instalar o yamllint com o comando brew install yamllint.

Dica: se o sistema for muito rebelde e não reconhecer os comandos, tente fechar e abrir novamente o terminal após a instalação. Para ter mais certeza se a variável foi inserida, abra seu arquivo .bash_profile e verifique se ela está lá. Veja mais dicas de instalação aqui.

No Windows

Antes, já deixe seu Prompt de Comando/cmd aberto e vamos lá!

Dica: para essas instalações, prefira utilizar o cmd (executado como administrador) ao invés do Windows PowerShell, pois o segundo apresentou um erro inesperado durante a instalação do pacote.


Para usuários de Node.js 
  1. Baixar o pacote via npm install -g yaml-lint
  2. Verificar se a instalação está foi feita com sucesso inserindo o comando yamllint -v ou yamllint --version
Obs.: Nesse caso, você deve tomar cuidado se seu arquivo constar como válido, mesmo não estando, pois a versão do yamllint para Node.js, até este momento, vem apresentando algumas instabilidades que ainda estão sendo corrigidas. Por isso, tente atualizar sempre para a versão mais recente ou prefira utilizar o Python.

     

Para usuários de Python 
  1. Instale a última versão do gerenciador de pacotes pip, com o comando pip install --upgrade pip ;
  2. Para instalar o yamllint, digite o comando pip install yamllint, depois, verifique se a instalação foi inserindo o comando yamllint -v ou yamllint --version.

    Obs
    .: É melhor fazer a instalação global ao invés de dentro da pasta usuário, por isso, pode ser que utilizar o parâmetro --user na instalação cause instabilidades para rodar em outros lugares.

Como funciona a validação?

Começar a validar é um processo muito simples, basta dar o comando, no mesmo diretório do em que seu arquivo está,  yamllint equipe.yaml. O grande problema, na realidade, é descobrir o que deu de errado com ele. É bem provável que você encontre algo assim:

Fonte: yamllint docs

Obs.: Antes, é legal que você tenha olhado os arquivos das outras equipes que conseguiram validar o equipe.yaml, assim você consegue entender melhor como é a estrutura do arquivo. Se preferir baixar o nosso, é só acessar aqui, mas também olhe lá no Blog de Trabalhos os que já estão validados (é só clicar no link chamado "SVNdos projetos).

Para entender melhor essas mensagens, recomendo que leia também as regras dispostas na documentação do yamllint, lá você vai encontrar o que significa cada erro/warning gerado nesse log, além de situações em que a estrutura disposta falhe ou passe nos testes. Porém, existem alguns erros comuns que pode ser que você se confunda mais caso leia a documentação. Alguns deles são:

  • Erro -  trailling spaces: esse erro acontece quando você não remove o espaço depois da última palavra de uma linha. Por isso, fique atento aos números a direita do log, eles mostram em qual linha está aquele erro. Por exemplo:
O cursor precisaria estar "colado" no número 2
para que não apontasse o erro de trailling spaces.

  • Erro - no new line at the end of file: nesse caso você precisa se certificar de que a última linha do seu arquivo é uma linha em branco. Dessa maneira:

    Aqui percebemos que a linha 15 é a última linha
    do arquivo e está em branco.


  • Erro - line too long (X > 80 characters): esse erro indica que as linhas de um arquivo .yaml não podem ter mais do 80 caracteres, então se você se deparar com ele, quer dizer que no lugar do "X" estará a quantidade de caracteres daquela linha, sendo essa maior do que 80. Uma dica para isso é quebrar as linhas do texto dando alguns espaços aqui e ali, e não fazer um texto corrido de uma vez (mas cuidado com as monografias).

  • Erro - found character '\t' that cannot start any token (syntax): aqui você deve se lembrar lá de cima quando falei sobre a formatação do arquivo, pois esse erro é devido ao uso de tabulação em alguma linha do seu equipe.yaml. 

Dicas extras e considerações finais

Uma coisa muito importante a se atentar é o cuidado com os caracteres especiais, pois pode ser que seu arquivo lá no SVN  apareça de um jeito estranho, mais ou menos assim:


Isso geralmente acontece pelo Unicode do seu arquivo não ser UTF-8. Por isso, ao salvar o arquivo, verifique se a codificação dele está no padrão esperado.

Outra coisa importante de se saber é se seu arquivo só vai ser atualizado na página do Dicas Ivan, quando o site for recompilado, o que ocorre a cada dois dias. Então, fique tranquilo se a atualização não for imediata: é normal. 

Uma dica é sempre verificar o log do equipes.yaml, para ver quando/se a compilação já foi feita. Aliás, lá você vai perceber o mesmo tipo de validação que ocorre no yamllint, pois os arquivos que não foram compilados possuem seus erros logo abaixo.

Por último, não esqueça: o Google é seu amigo, se não encontrar algum erro super estranho na documentação, copie-o e cole-o no Google, pode ser que com um pouquinho de garimpo, você encontre a solução que procura.



Por hoje é isso pessoal, se tivermos mais dicas e relacionados para compartilhar com vocês, fiquem atentos nas próximas postagens.

Até mais! :) 


Fontes:

https://pt.stackoverflow.com/questions/330821/o-que-significa-executar-lint-no-código
https://yamllint.readthedocs.io/en/stable/
https://www.redhat.com/pt-br/topics/automation/what-is-configuration-management
https://www.redhat.com/pt-br/topics/automation/what-is-yaml



You Might Also Like

0 comments