Pular para o conteúdo
CodeMDD.io | Coding Tutorials

Como usar o pyyaml de forma fácil?

[

YAML: A Bateria que Faltava no Python

Por Bartosz Zaczyński (intermediário)

Python é frequentemente divulgado como uma linguagem “baterias incluídas”, porque ela possui quase tudo o que você espera de uma linguagem de programação. Essa afirmação é em grande parte verdadeira, uma vez que a biblioteca padrão e os módulos externos cobrem uma ampla gama de necessidades de programação. No entanto, o Python não possui suporte nativo para o formato de dados YAML, comumente usado para configuração e serialização, apesar das claras similaridades entre as duas linguagens.

Neste tutorial, você aprenderá como trabalhar com YAML em Python usando as bibliotecas de terceiros disponíveis, com foco no PyYAML. Se você é novo no YAML ou não o utiliza há algum tempo, terá a oportunidade de fazer um curso rápido antes de aprofundar o assunto.

Neste tutorial, você aprenderá a:

  • Ler e escrever documentos YAML em Python
  • Serializar tipos de dados internos e personalizados do Python para YAML
  • Ler documentos YAML de fontes não confiáveis de forma segura
  • Ter controle sobre o parsing de documentos YAML em um nível mais baixo

Posteriormente, você aprenderá sobre recursos avançados do YAML, potencialmente perigosos, e como se proteger deles. Para fazer o parsing do YAML em um nível mais baixo, você criará uma ferramenta de destaque de sintaxe e uma visualização interativa em HTML. Por fim, você aproveitará as tags YAML personalizadas para estender a sintaxe do formato de dados.

Para aproveitar ao máximo este tutorial, você deve estar familiarizado com a programação orientada a objetos em Python e saber como criar uma classe. Se estiver pronto para começar, você pode seguir o link abaixo para obter o código-fonte dos exemplos que você irá codificar neste tutorial:

Fazendo um Curso Rápido em YAML

Nesta seção, você aprenderá fatos básicos sobre o YAML, incluindo seus usos, sintaxe e alguns de seus recursos únicos e poderosos. Se você já trabalhou com YAML anteriormente, pode pular para a próxima seção, que aborda o uso do YAML em Python.

Contexto Histórico

YAML, que rima com “camelo”, é um acrônimo recursivo para “YAML Ain’t Markup Language” (“YAML Não é uma Linguagem de Marcação”, em tradução livre). É um formato de serialização de dados legível por humanos e foi projetado para ser fácil de ler e escrever. O YAML foi desenvolvido por Clark Evans e Brian Ingerson, com a contribuição de Oren Ben-Kiki, e a primeira especificação foi lançada em 2001.

Inicialmente, o YAML foi inspirado em outras linguagens de serialização de dados, como XML e JSON. No entanto, o YAML se destaca por ser mais conciso e fácil de editar. Ele fornece um formato de dados legível por humanos que pode ser usado para representar configurações e estruturas de dados complexas.

Comparação com XML e JSON

Uma das principais diferenças entre o YAML, o XML e o JSON é a sintaxe. YAML utiliza indentação e caracteres especiais para estruturar o documento, enquanto XML utiliza tags e JSON utiliza chaves e colchetes.

Aqui está um exemplo comparando a representação de um objeto em YAML, XML e JSON:

YAML:

person:
  name: John
  age: 30

XML:

<person>
  <name>John</name>
  <age>30</age>
</person>

JSON:

{
  "person": {
    "name": "John",
    "age": 30
  }
}

Como você pode ver, a representação em YAML é mais concisa e legível por humanos. Isso torna o YAML uma escolha popular para configurações de aplicativos e arquivos de dados complexos.

Usos Práticos do YAML

O YAML é comumente usado para configurações de aplicativos, porque sua sintaxe é fácil de ler e editar, e sua estrutura permite representar dados complexos de forma legível. Você pode utilizar o YAML para representar estruturas de dados como listas, dicionários e objetos, bem como para definir valores escalares como números, strings e booleanos.

Além das configurações de aplicativos, o YAML também é usado para:

  • Transferir dados entre diferentes sistemas e linguagens de programação
  • Armazenar dados hierárquicos em arquivos legíveis por humanos
  • Escrever testes automatizados e scripts de automação

Em resumo, o YAML é uma ferramenta versátil para estruturar e serializar dados de forma legível por humanos.

Sintaxe YAML

A sintaxe YAML é projetada para ser simples e legível por humanos. Ela utiliza indentação, pontos de interrogação (:?) e hífens (-) para estruturar o documento. Aqui estão alguns elementos-chave da sintaxe YAML:

  • Indentação: O YAML utiliza a indentação para estruturar o documento, diferentemente de outros formatos como XML e JSON. A indentação deve ser feita com espaços, não com tabulações.

  • Chave e Valor: Os pares chave-valor são escritos com a chave seguida de dois pontos e um espaço (: ). O valor pode ser representado como uma string, número, booleano, lista ou objeto.

  • Listas: Listas no YAML são representadas por hífens (-) seguidos de um espaço. Os itens da lista são indentados para indicar níveis diferentes de hierarquia.

  • Objetos: Objetos no YAML são representados como pares chave-valor. As chaves são escritas seguidas de dois pontos, e os valores são indentados para indicar níveis diferentes de hierarquia.

Aqui está um exemplo de um documento YAML simples que representa informações sobre uma pessoa:

name: John Doe
age: 30
email: john@example.com

Este documento possui três pares chave-valor: “name” com o valor “John Doe”, “age” com o valor 30 e “email” com o valor “john@example.com”.

Recursos Únicos

O YAML possui alguns recursos únicos que o distinguem de outros formatos de dados:

  • Referências: O YAML permite que você faça referências a outros objetos no documento usando âncoras e aliases. Isso facilita a reutilização de dados e reduz a duplicação da informação.

  • Tipos Personalizados: O YAML permite que você defina tipos de dados personalizados e os serialize em documentos YAML. Isso é útil quando você precisa serializar objetos complexos que não fazem parte dos tipos de dados padrão do Python.

  • Tags: As tags YAML permitem que você anote os valores com metainformações adicionais. Isso é útil quando você precisa associar informações adicionais aos valores, como o formato de uma data ou a unidade de medida de um número.

Esses recursos fazem do YAML uma linguagem flexível e poderosa para representar dados estruturados.

Começando com YAML em Python

Agora que você tem uma compreensão básica do YAML, vamos dar uma olhada em como começar a usar o YAML em Python. Para começar, você precisará instalar a biblioteca PyYAML, que fornece suporte para trabalhar com YAML em Python.

Serializando Documentos YAML como JSON

Em alguns casos, você pode querer serializar um documento YAML como JSON, já que a sintaxe dos dois formatos é semelhante. O PyYAML permite que você faça isso diretamente, usando a função yaml.dump(). Veja um exemplo:

import yaml


data = {
    'name': 'John',
    'age': 30,
    'email': 'john@example.com'
}


yaml_data = yaml.dump(data)
print(yaml_data)

A saída desse código será:

age: 30
email: john@example.com
name: John

Como você pode ver, o PyYAML serializa corretamente o dicionário Python para YAML. Note que a ordem das chaves pode ser diferente da ordem original dos itens, já que os dicionários do Python não possuem uma ordem garantida.

Instalando a Biblioteca PyYAML

Para começar a trabalhar com YAML em Python, você precisará instalar a biblioteca PyYAML. Você pode fazer isso usando o gerenciador de pacotes pip, executando o seguinte comando:

pip install pyyaml

Certifique-se de ter o pip instalado em seu sistema antes de tentar instalar o PyYAML.

Lendo e Escrevendo Seu Primeiro Documento YAML

Agora que o PyYAML está instalado, você pode começar a ler e escrever documentos YAML em Python. Para fazer isso, vamos dar uma olhada em um exemplo simples que cria um documento YAML a partir de um dicionário Python e, em seguida, lê esse documento de volta para Python:

import yaml


data = {
    'name': 'John',
    'age': 30,
    'email': 'john@example.com'
}


# Escrever o documento YAML
with open('data.yaml', 'w') as file:
    yaml.dump(data, file)


# Ler o documento YAML
with open('data.yaml', 'r') as file:
    loaded_data = yaml.load(file, Loader=yaml.Loader)


print(loaded_data)

A saída desse código será:

{'name': 'John', 'age': 30, 'email': 'john@example.com'}

Como você pode ver, o PyYAML lida corretamente com a escrita e leitura do documento YAML. É importante mencionar que o PyYAML possui métodos adicionais para trabalhar com documentos YAML mais complexos, como carregar ou gravar vários documentos YAML em um único arquivo.

Carregando Documentos YAML em Python

Ao ler um documento YAML em Python, você precisará escolher uma classe de carregamento (Loader) para analisar o documento e criar uma representação Python correspondente. O PyYAML fornece várias classes de carregamento diferentes, cada uma com recursos e comportamentos específicos.

Escolher a Classe de Carregamento

Ao escolher uma classe de carregamento do PyYAML, você precisa considerar os recursos específicos do documento YAML que está carregando. Aqui estão algumas opções a serem consideradas:

  • SafeLoader: Essa classe de carregamento é segura e restrita. Ela desabilita a execução de código Python incorporado no documento YAML e limita-se a analisar apenas tipos de dados básicos.

  • FullLoader: Essa classe de carregamento é mais flexível e permite a execução de código Python contido no documento YAML. Tenha cuidado ao usar essa classe, pois ela pode apresentar riscos quando você usa YAML proveniente de fontes não confiáveis.

  • Loader: Essa classe de carregamento é uma combinação entre o SafeLoader e o FullLoader. Ela permite a execução de código Python contido no documento YAML, mas também oferece proteção contra as construções Python mais perigosas.

Você pode escolher a classe de carregamento apropriada com base nas necessidades do seu projeto. No exemplo a seguir, vamos usar a classe Loader:

import yaml


# Carregar o documento YAML
with open('data.yaml', 'r') as file:
    loaded_data = yaml.load(file, Loader=yaml.Loader)


print(loaded_data)

A saída desse código será a mesma do exemplo anterior. Observe que é importante abrir o arquivo YAML com o uso do contexto with open() para garantir que ele seja fechado corretamente após o carregamento dos dados.

Carregar Múltiplos Documentos

O YAML permite que você escreva e leia vários documentos YAML em um único arquivo. Para carregar múltiplos documentos YAML em Python, você pode usar o método yaml.safe_load_all() em vez do método yaml.load().

import yaml


# Carregar múltiplos documentos YAML
with open('data.yaml', 'r') as file:
    for document in yaml.safe_load_all(file):
        print(document)

Com esse código, o PyYAML carregará cada documento YAML separadamente e os imprimirá na saída. Certifique-se de usar o método yaml.safe_load_all() para proteger seu código contra construções perigosas de Python embutidas no documento YAML.

Serializando Objetos Python em Documentos YAML

Ao escrever documentos YAML a partir de objetos Python, você precisará escolher uma classe de serialização (Dumper) para criar uma representação YAML correspondente. O PyYAML fornece várias classes de serialização diferentes, cada uma com recursos e comportamentos específicos.

Escolher a Classe de Serialização

Ao escolher uma classe de serialização do PyYAML, você precisa considerar o tipo de objeto Python que deseja serializar. Aqui estão algumas opções a serem consideradas:

  • SafeDumper: Essa classe de serialização é segura e restrita. Ela serializa apenas tipos de dados básicos e não permite a execução de código Python embutido.

  • FullDumper: Essa classe de serialização é mais flexível e permite a execução de código Python embutido. Tenha cuidado ao usar essa classe, pois ela pode apresentar riscos quando você serializa objetos Python provenientes de fontes não confiáveis.

  • Dumper: Essa classe de serialização é uma combinação entre o SafeDumper e o FullDumper. Ela permite a execução de código Python embutido, mas também fornece proteção contra as construções Python mais perigosas.

import yaml


data = {
    'name': 'John',
    'age': 30,
    'email': 'john@example.com'
}


# Serializar o objeto Python em YAML
yaml_data = yaml.dump(data, Dumper=yaml.Dumper)
print(yaml_data)

No exemplo acima, a saída será a mesma do exemplo da seção de serialização YAML como JSON. Certifique-se de usar a classe de serialização apropriada com base no tipo de objeto Python que você está serializando.

Gravar Documentos YAML

Depois de serializar um objeto Python em YAML, você pode gravar o documento YAML em um arquivo usando o método file.write().

import yaml


data = {
    'name': 'John',
    'age': 30,
    'email': 'john@example.com'
}


# Serializar o objeto Python em YAML
yaml_data = yaml.dump(data, Dumper=yaml.Dumper)


# Gravar o documento YAML em um arquivo
with open('data.yaml', 'w') as file:
    file.write(yaml_data)

Com esse código, o PyYAML serializa o objeto Python em YAML e o grava em um arquivo chamado “data.yaml”. Certifique-se de abrir o arquivo YAML no modo de gravação (‘w’) e use o método file.write() para escrever o conteúdo do documento YAML.

Multiplíplos Documentos

O PyYAML também permite serializar e gravar múltiplos documentos YAML em um único arquivo. Para fazer isso, você pode usar o método yaml.safe_dump_all() em vez do método yaml.dump().

import yaml


data1 = {
    'name': 'John',
    'age': 30,
    'email': 'john@example.com'
}


data2 = {
    'name': 'Jane',
    'age': 25,
    'email': 'jane@example.com'
}


# Serializar e gravar múltiplos documentos YAML
with open('data.yaml', 'w') as file:
    yaml.safe_dump_all([data1, data2], file)

Nesse código, o PyYAML serializa cada objeto Python em YAML separadamente e os grava no arquivo “data.yaml”. Certifique-se de usar o método yaml.safe_dump_all() para proteger seu código contra construções perigosas de Python embutidas nos objetos Python.

Parseando Documentos YAML em um Nível Mais Baixo

O PyYAML permite que você faça o parsing de documentos YAML em um nível mais baixo, o que lhe dá controle sobre o processo de parsing e a estrutura dos dados resultantes. Para fazer isso, você precisa trabalhar com três conceitos principais: tokens, eventos e nós.

Tokenizar um Documento YAML

O primeiro passo para fazer o parsing de um documento YAML em um nível mais baixo é tokenizar o documento. Um token no YAML é um pedaço significativo de texto que representa um elemento sintático do documento, como uma chave, valor ou caractere especial.

Para tokenizar um documento YAML, você pode usar a função yaml.scan() do PyYAML:

import yaml


document = '''
person:
  name: John
  age: 30
'''


# Tokenizar o documento YAML
for token in yaml.scan(document):
    print(token)

Com esse código, o PyYAML tokeniza o documento YAML e imprime cada token na saída. Isso permite examinar a estrutura do documento YAML em um nível mais baixo.

Analisar um Fluxo de Eventos

Depois de tokenizar um documento YAML, você pode analisar o fluxo de eventos correspondente aos tokens. Um evento no YAML é uma transformação do token em um objeto Python, que representa uma ação ou um estado do documento YAML.

Para analisar um fluxo de eventos no PyYAML, você pode usar a função yaml.parse():

import yaml


document = '''
person:
  name: John
  age: 30
'''


# Analisar o fluxo de eventos YAML
for event in yaml.parse(document):
    print(event)

Com esse código, o PyYAML analisa o fluxo de eventos do documento YAML e imprime cada evento na saída. Isso permite examinar a estrutura do documento YAML em um nível ainda mais baixo.

Construir uma Árvore de Nós

Depois de analisar o fluxo de eventos de um documento YAML, você pode construir uma árvore de nós que representa a estrutura hierárquica do documento. Um nó no YAML é um objeto Python que representa um valor, como uma string, número, lista ou objeto.

Para construir uma árvore de nós no PyYAML, você pode usar a função yaml.compose():

import yaml


document = '''
person:
  name: John
  age: 30
'''


# Construir a árvore de nós YAML
tree = yaml.compose(document)


# Imprimir a árvore de nós
yaml.dump(tree)

Com esse código, o PyYAML constrói a árvore de nós do documento YAML e a imprime na saída. Isso permite examinar a estrutura hierárquica do documento YAML em um nível mais natural e semântico.

Conclusão

Neste tutorial, você aprendeu como trabalhar com YAML em Python usando a biblioteca PyYAML. Você viu como ler e escrever documentos YAML, carregar e serializar objetos Python em YAML e fazer o parsing de documentos YAML em um nível mais baixo.

O YAML é uma ferramenta poderosa para representar dados estruturados de forma legível por humanos. Usando o PyYAML, você pode integrar facilmente o YAML em seus projetos Python e aproveitar todos os recursos e flexibilidade oferecidos por esse formato de dados.

Agora que você tem uma compreensão básica do YAML e do PyYAML, você pode explorar mais recursos e tópicos avançados para aproveitar ao máximo essas ferramentas em seus projetos.