10 consejos de YAML para personas que odian YAML

Hay muchos formatos para los archivos de configuración: una lista de valores, pares de clave y valor, archivos INI, YAML, JSON, XML y muchos más. De estos, YAML a veces se cita como particularmente difícil de mantener por varias razones. Si bien su capacidad para reflejar valores jerárquicos es importante y su minimalismo puede ser refrescante para algunos, su dependencia similar a la de Python en los espacios en blanco sintácticos puede ser frustrante.

Sin embargo, el mundo del código abierto es lo suficientemente diverso y flexible como para que nadie tenga que sufrir por la tecnología abrasiva, así que si odias YAML, aquí hay 10 cosas que puedes (¡y debes!) hacer para que sea tolerable. Comenzando con cero, como debería hacerlo cualquier índice sensato.

Índice

    0. Pon tu editor a trabajar

    Independientemente del editor de texto que utilice, probablemente tenga complementos para ayudar con la gestión de la sintaxis. Si no usa un complemento YAML para su editor, busque uno e instálelo. El esfuerzo que pone en encontrar un complemento y configurarlo según sus necesidades se multiplicará por diez la próxima vez que modifique YAML.

    por ejemplo, el Átomo El editor viene con un modo YAML predeterminado y, aunque GNU Emacs viene con un soporte mínimo, puede agregar paquetes adicionales como modo yaml ayudar.

    Emacs en modo YAML y espacio en blanco.

    Si tu editor de texto favorito no tiene un modo YAML, puedes resolver algunas de tus quejas modificando ligeramente la configuración. Por ejemplo, el editor de texto predeterminado para el escritorio GNOME, Gedit, no tiene un modo YAML disponible, pero proporciona resaltado de sintaxis YAML de forma predeterminada y ofrece un ancho de pestaña configurable:

    Configurar el ancho y el tipo de pestaña en Gedit
    Configurando el ancho y el tipo de pestaña en Gedit.

    Con el drawspaces El paquete de complementos de Gedit, puede hacer que los espacios en blanco sean visibles como puntos principales, eliminando cualquier pregunta sobre los niveles de sangría.

    Tómese el tiempo para encontrar su editor de texto favorito. Descubra qué está haciendo el editor, o su comunidad, para facilitar YAML y aprovechar estas características en su trabajo. No te arrepentirás.

    1. Usa un pelusa

    Idealmente, los lenguajes de programación y los lenguajes de marcado utilizan una sintaxis predecible. Las ordenadores tienden a funcionar bien con la previsibilidad, por lo que el concepto de Enterrar fue inventado en 1978. Si no está usando un linter para YAML, es hora de adoptar esta tradición de 40 años y usar yamllint.

    puedes instalar yamllint en Linux usando el administrador de paquetes de su distribución. Por ejemplo, en Red Hat Enterprise Linux 8 o Sintió:

    $ sudo dnf install yamllint
    

    Invocar yamllint es tan simple como decirle que verifique un archivo. Aquí hay un ejemplo de yamllintrespuesta a un archivo YAML que contiene un error:

    $ yamllint errorprone.yaml
    errorprone.yaml
    23:10     error    syntax error: mapping values are not allowed here
    23:11     error    trailing spaces  (trailing-spaces)
    

    No es una marca de tiempo a la izquierda. Este es el número de fila y columna del error. Puede o no entender qué error es, pero ahora sabe dónde está el error. Una segunda mirada a la ubicación a menudo hace que la naturaleza del error sea obvia. El éxito es extrañamente silencioso, por lo que si desea comentarios basados ​​en el éxito de la pelusa, puede agregar un segundo comando condicional con un signo doble (&&). En un shell POSIX, && falla si algún comando devuelve algo 0, por lo que si tiene éxito, su echo orden especifica. Esta táctica es algo superficial, pero algunos usuarios prefieren la seguridad de que el comando se ejecutó correctamente, en lugar de fallar silenciosamente. Aquí un ejemplo :

    $ yamllint perfect.yaml && echo "OK"
    OK
    

    La razón yamllint es tan silencioso cuando tiene éxito que devuelve 0 errores cuando no hay errores.

    2. Escribe en Python, no en YAML

    Si realmente odias YAML, deja de escribir YAML, al menos en el sentido literal. Es posible que te quedes con YAML porque es el único formato que acepta una aplicación, pero si el único requisito es terminar en YAML, entonces trabaja en otra cosa y luego convierte. Python, así como el excelente pyyaml biblioteca, lo hace fácil, y tiene dos opciones: auto-conversión o secuencias de comandos.

    Conversión automática

    En el método de conversión automática, sus archivos de datos también son secuencias de comandos de Python que producen YAML. Funciona mejor para conjuntos de datos pequeños. Simplemente escriba sus datos JSON en una variable de Python, agregue un import y termine el archivo con una declaración de salida simple de tres líneas.

    #!/usr/bin/python3	
    import yaml 
    
    d={
    "glossary": {
      "title": "example glossary",
      "GlossDiv": {
    	"title": "S",
    	"GlossList": {
    	  "GlossEntry": {
    		"ID": "SGML",
    		"SortAs": "SGML",
    		"GlossTerm": "Standard Generalized Markup Language",
    		"Acronym": "SGML",
    		"Abbrev": "ISO 8879:1986",
    		"GlossDef": {
    		  "para": "A meta-markup language, used to create markup languages such as DocBook.",
    		  "GlossSeeAlso": ["GML", "XML"]
    		  },
    		"GlossSee": "markup"
    		}
    	  }
    	}
      }
    }
    
    f=open('output.yaml','w')
    f.write(yaml.dump(d))
    f.close
    

    Ejecute el archivo con Python para producir un archivo llamado output.yaml archivar.

    $ python3 ./example.json
    $ cat output.yaml
    glossary:
      GlossDiv:
    	GlossList:
    	  GlossEntry:
    		Abbrev: ISO 8879:1986
    		Acronym: SGML
    		GlossDef:
    		  GlossSeeAlso: [GML, XML]
    		  para: A meta-markup language, used to create markup languages such as DocBook.
    		GlossSee: markup
    		GlossTerm: Standard Generalized Markup Language
    		ID: SGML
    		SortAs: SGML
    	title: S
      title: example glossary
    

    Esta salida es YAML perfectamente válida, aunque yamllint emite una advertencia de que el archivo no está precedido por ---, que puede ajustar en el script de Python o manualmente.

    Conversión con guión

    En este método, escribe JSON y luego ejecuta un script de conversión de Python para producir YAML. Esto escala mejor que la conversión automática porque separa el convertidor de los datos.

    Cree un archivo JSON y guárdelo como example.json. Aquí hay un ejemplo de json.org:

    {
    	"glossary": {
    	  "title": "example glossary",
    	  "GlossDiv": {
    		"title": "S",
    		"GlossList": {
    		  "GlossEntry": {
    			"ID": "SGML",
    			"SortAs": "SGML",
    			"GlossTerm": "Standard Generalized Markup Language",
    			"Acronym": "SGML",
    			"Abbrev": "ISO 8879:1986",
    			"GlossDef": {
    			  "para": "A meta-markup language, used to create markup languages such as DocBook.",
    			  "GlossSeeAlso": ["GML", "XML"]
    			  },
    			"GlossSee": "markup"
    			}
    		  }
    		}
    	  }
    	}
    

    Cree un convertidor simple y guárdelo como json2yaml.py. Este script importa módulos Python YAML y JSON, carga un archivo JSON definido por el usuario, realiza la conversión y luego escribe los datos en output.yaml.

    #!/usr/bin/python3
    import yaml
    import sys
    import json
    
    OUT=open('output.yaml','w')
    IN=open(sys.argv[1], 'r')
    
    JSON = json.load(IN)
    IN.close()
    yaml.dump(JSON, OUT)
    OUT.close()
    

    Guarde este script en la ruta de su sistema y ejecútelo si es necesario:

    $ ~/bin/json2yaml.py example.json

    3. Analice temprano, analice a menudo

    A veces ayuda mirar un problema desde un ángulo diferente. Si su problema es YAML y tiene problemas para visualizar las relaciones entre los datos, puede que le resulte útil reestructurar esos datos, temporalmente, en algo con lo que esté más familiarizado.

    Si se siente más cómodo con las listas de estilo diccionario o JSON, por ejemplo, puede convertir YAML a JSON en dos comandos mediante un shell interactivo de Python. Digamos que su archivo YAML se llama mydata.yaml.

    $ python3
    >>> f=open('mydata.yaml','r')
    >>> yaml.load(f)
    {'document': 34843, 'date': datetime.date(2019, 5, 23), 'bill-to': {'given': 'Seth', 'family': 'Kenlon', 'address': {'street': '51b Mornington Roadn', 'city': 'Brooklyn', 'state': 'Wellington', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Good article. Could be better.'}
    

    Hay muchos otros ejemplos, y hay muchos convertidores en línea y analizadores locales, así que siéntete libre de reformatear los datos cuando comiencen a parecerse más a una lista de lavandería que a un marcado.

    4. Lea las especificaciones

    Después de estar lejos de YAML por un tiempo y volver a usarlo, volví directamente a yaml.org para leer la especificación. Si nunca ha leído la especificación YAML y encuentra YAML confuso, una mirada a la especificación puede proporcionarle la aclaración que nunca pensó que necesitaba. La especificación es sorprendentemente fácil de leer, con los requisitos para un YAML válido explicados con muchos ejemplos en Capítulo 6.

    5. Pseudoconfiguración

    Antes de empezar a escribir mi libro, Desarrollar juegos en Raspberry Pi, Apress, 2019, el editor me pidió un borrador. Uno pensaría que una descripción general sería fácil. Por definición, estos son solo títulos de capítulos y secciones, sin contenido real. Y sin embargo, de las 300 páginas publicadas, la más difícil de escribir fue este primer borrador.

    YAML puede ser de la misma manera. Es posible que tenga una idea de los datos que necesita registrar, pero eso no significa que comprenda completamente cómo se relaciona todo. Entonces, antes de sentarse a escribir YAML, intente hacer una pseudoconfiguración en su lugar.

    Una pseudoconfiguración es como un pseudocódigo. No tiene que preocuparse por la estructura o la sangría, las relaciones padre-hijo, la herencia o el anidamiento. Simplemente está creando iteraciones de datos de la forma en que actualmente los entiende en su cabeza.

    Una pseudoconfiguración.
    Una pseudoconfiguración.

    Una vez que tenga su pseudoconfiguración en papel, estúdiela y convierta sus resultados en YAML válido.

    6. Resuelve el debate entre espacios y tabulaciones

    OK, tal vez no resolverás el debate espacios vs tabulaciones, pero al menos deberías resolver el debate dentro de tu proyecto u organización. Ya sea que resuelva esta pregunta con un proceso posterior sed script, la configuración del editor de texto o el juramento de respetar los resultados de su linter, cualquier miembro de su equipo que toque un proyecto YAML debe aceptar usar espacios (según la especificación YAML).

    Cualquier buen editor de texto le permite establecer una cantidad de espacios en lugar de un carácter de tabulación, por lo que la elección no debería afectar negativamente a los fanáticos del Lengua llave.

    Las pestañas y los espacios son, como probablemente sepa muy bien, esencialmente invisibles. Y cuando algo está fuera de la vista, rara vez se le ocurre hasta el amargo final, cuando ha probado y eliminado todos los problemas "obvios". Una hora desperdiciada en una pestaña o grupo de espacios perdidos es su señal para crear una política para usar uno u otro, luego desarrollar una verificación de cumplimiento a prueba de fallas (como un gancho de Git para hacer cumplir la pelusa).

    7. Menos es más (o más es menos)

    A algunas personas les gusta escribir YAML para enfatizar su estructura. Sangran vigorosamente para ayudar a visualizar bloques de datos. Es una especie de trampa imitar lenguajes de marcas que tienen delimitadores explícitos.

    Aquí hay un buen ejemplo de Documentación de Ansible:

    # Employee records
    -  martin:
            name: Martin D'vloper
            job: Developer
            skills:
                - python
                - perl
                - pascal
    -  tabitha:
            name: Tabitha Bitumen
            job: Developer
            skills:
                - lisp
                - fortran
                - erlang
    

    Para algunos usuarios, este enfoque es una forma útil de diseñar un documento YAML, mientras que otros usuarios pierden la estructura debido al vacío de espacios en blanco aparentemente gratuitos.

    Si posee y administra un documento YAML, debe definir qué significa "sangrado". Si los bloques de espacios en blanco horizontales lo distraen, use la cantidad mínima de espacios en blanco requerida por la especificación YAML. Por ejemplo, el mismo YAML de la documentación de Ansible se puede representar con menos sangrías sin perder nada de su validez o significado:

    ---
    - martin:
       name: Martin D'vloper
       job: Developer
       skills:
       - python
       - perl
       - pascal
    - tabitha:
       name: Tabitha Bitumen
       job: Developer
       skills:
       - lisp
       - fortran
       - erlang
    

    8. Haz una receta

    Soy un gran fanático de la repetición que genera familiaridad, pero a veces la repetición solo genera errores estúpidos repetidos. Afortunadamente, una astuta campesina experimentó este mismo fenómeno en el año 396 d. C. (no me mires) e inventó el concepto de .

    Si se encuentra cometiendo errores de documentos YAML repetidamente, puede incrustar una receta o plantilla en el archivo YAML como una sección comentada. Cuando agregue una sección, copie la receta comentada y reemplace los datos ficticios con sus nuevos datos reales. Por ejemplo:

    ---
    # - <common name>:
    #   name: Given Surname
    #   job: JOB
    #   skills:
    #   - LANG
    - martin:
      name: Martin D'vloper
      job: Developer
      skills:
      - python
      - perl
      - pascal
    - tabitha:
      name: Tabitha Bitumen
      job: Developer
      skills:
      - lisp
      - fortran
      - erlang
    

    9. Usa otra cosa

    Soy fanático de YAML, en general, pero a veces YAML no es la respuesta. Si no está bloqueado en YAML por la aplicación que está utilizando, es posible que le sirva mejor otro formato de configuración. A veces, los archivos de configuración son demasiado grandes y es mejor refactorizarlos en secuencias de comandos simples de Lua o Python.

    YAML es una gran herramienta y es popular entre los usuarios por su minimalismo y simplicidad, pero no es la única herramienta en su kit. A veces es mejor separarse. Uno de los beneficios de YAML es que las bibliotecas de análisis son comunes, por lo que siempre que proporcione opciones de migración, sus usuarios deberían poder adaptarse sin problemas.

    Si YAML es un requisito, tenga en cuenta estos consejos y derrote su odio hacia YAML de una vez por todas.

    Artículos de interés

    Subir