Cómo leer archivos YAML seguros en Python con safe_load

1. ¿Cómo leer YAML con Python?｜Resumen del artículo y público objetivo

Para ti que quieres trabajar con YAML en Python

Al desarrollar aplicaciones o herramientas con Python, cada vez aparecen más situaciones en las que deseas usar el formato YAML para “archivos de configuración” o “gestión de datos externos”. En particular, YAML, que es más legible que JSON y permite una escritura sencilla, es un formato de datos muy popular entre ingenieros y científicos de datos.

Por ejemplo, en los siguientes casos es necesario leer YAML:

• de aplicaciones web o scripts externalizar los archivos de configuración
• Quiero analizar con Python los archivos de configuración de Docker Compose y Kubernetes
• Quiero gestionar los parámetros de frameworks de aprendizaje automático con YAML

Por otro lado, también se escuchan muchas voces de principiantes que dicen “no sé cómo leer un archivo YAML” o “aparecen errores y no puedo leerlo correctamente”.

Lo que aprenderás en este artículo

En este artículo, explicaremos de manera clara para principiantes cómo leer archivos YAML con Python de forma segura y fiable. Concretamente, cubriremos los siguientes puntos:

• Estructura básica y características de los archivos YAML
• Método de lectura en Python (uso de safe_load())
• Errores comunes y sus soluciones
• Ejemplos prácticos de lectura de múltiples documentos y de archivos de configuración

Además, abordaremos aspectos de seguridad, así como diferencias entre load() y safe_load(), información poco conocida. Además, al final incluimos preguntas frecuentes (FAQ) para que tus dudas se resuelvan.

Público objetivo

Este artículo está dirigido a las siguientes personas:

• Principiantes a intermedios que quieren usar YAML con Python
• Desarrolladores que necesitan manejar archivos de configuración
• Personas que tienen dudas sobre cómo usar PyYAML
• Personas que desean conocer en detalle safe_load() y la gestión de errores

Si deseas mejorar la eficiencia del desarrollo con Python en el futuro, dominar el manejo de YAML será un gran paso.

En las siguientes secciones, explicaremos paso a paso la visión general de YAML y su uso con Python. Comencemos con “¿Qué es YAML?”.

2. ¿Qué es YAML? | Comparación sencilla de diferencias y características con JSON

¿Qué es YAML?

YAML (Yameru, o Yamuru) es un acrónimo recursivo para «YAML Ain’t Markup Language (YAML no es un lenguaje de marcado)», diseñado principalmente para que los humanos lean y escriban datos estructurados de manera fácil. También tiene buena compatibilidad con lenguajes de programación como Python y Ruby, y se usa mucho en archivos de configuración y en escenarios de intercambio de datos.

YAML representa la estructura jerárquica mediante la indentación, y una de sus principales características es que permite una escritura simple e intuitiva.

Diferencias con JSON

YAML se usa en propósitos similares a JSON, pero existen algunas diferencias claras entre ambos. Veamos una comparación de los ítems representativos a continuación.

Ventajas de YAML

Usar YAML tiene las siguientes ventajas:

• Escritura intuitiva: similar a la indentación de Python, lo que facilita comprender la estructura
• Se pueden escribir comentarios: útil para añadir notas en archivos de configuración
• No es redundante: no requiere llaves ni comillas dobles como JSON
• Amigable para humanos: fácil de leer y modificar incluso para no ingenieros

Escenarios de uso de YAML

YAML se utiliza frecuentemente en las siguientes herramientas y sistemas:

• Docker Compose（docker-compose.yml）
• Kubernetes archivos de configuración (definiciones de Pods y Services)
• Herramientas CI/CD (GitHub Actions, GitLab CI, etc.)
• Bibliotecas de aprendizaje automático (PyTorch Lightning, Hydra, etc.)
• Archivos de configuración de aplicaciones web y scripts

En resumen, saber manejar YAML se convierte en una gran ventaja en los entornos de desarrollo actuales.

3. Preparación para manejar YAML en Python | Instalación de PyYAML

¿Qué es PyYAML?

Para leer o escribir archivos YAML en Python, es común usar la biblioteca externa «PyYAML». PyYAML es una biblioteca simple pero potente basada en la especificación YAML 1.1, y como no está incluida en la biblioteca estándar de Python, es necesario instalarla por separado.

Con PyYAML, puedes manejar archivos YAML como diccionarios de Python (dict) o listas (list). Esto permite leer y escribir archivos de configuración y manipular datos estructurados de forma intuitiva.

Cómo instalar PyYAML

La instalación de PyYAML es muy sencilla. Puedes instalarlo desde la línea de comandos (o terminal) usando pip como se muestra a continuación.

pip install pyyaml

※ Si pip no está disponible en tu entorno, también puedes usar python -m pip install pyyaml sin problemas.

Se recomienda usar entornos virtuales

Si deseas aislar tu entorno de desarrollo, se recomienda instalar dentro de un entorno virtual (venv o conda). Esto facilita la gestión de versiones de las bibliotecas al trabajar con varios proyectos.

# Crear entorno virtual
python -m venv venv

# Activar entorno virtual
# En caso de Windows
venvScriptsctivate
# En caso de macOS/Linux
source venv/bin/activate

# Instalar PyYAML
pip install pyyaml

Cómo verificar la instalación

Después de la instalación, puedes comprobar que la biblioteca se importa correctamente escribiendo lo siguiente en el modo interactivo de Python (REPL) o en un script.

import yaml
print(yaml.__version__)

Si no aparece ningún error, PyYAML se ha instalado correctamente. Verificar la versión también será útil para investigar posibles problemas en el futuro.

4. 【Básico】Cómo leer archivos YAML con Python (uso de safe_load)

Método de lectura más básico: safe_load()

Al leer archivos YAML con PyYAML, la función más utilizada es safe_load(). Esta función es un método diseñado para leer YAML de forma segura y permite obtener los datos leídos como diccionario de Python (dict) o lista (list).

Primero, veamos un archivo YAML básico y su código de lectura.

Archivo YAML de ejemplo (config.yaml)

app:
  name: SampleApp
  version: 1.0.0
debug: true
servers:
  - host: localhost
    port: 8000
  - host: example.com
    port: 443

De esta manera, los archivos YAML que incluyen estructuras anidadas y listas son un formato muy fácil de usar como archivo de configuración.

Ejemplo de código de lectura en Python

Con el siguiente código, puedes leer el archivo YAML anterior:

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    config = yaml.safe_load(f)

print(config)

Ejemplo de salida (formato de diccionario de Python)

{
  'app': {'name': 'SampleApp', 'version': '1.0.0'},
  'debug': True,
  'servers': [
    {'host': 'localhost', 'port': 8000},
    {'host': 'example.com', 'port': 443}
  ]
}

Así, los archivos YAML pueden manejarse directamente como estructuras de datos nativas de Python, lo que permite utilizarlos sin problemas en procesos posteriores.

open() función: especificar la codificación es importante

Especialmente al trabajar con archivos YAML que contienen japonés, no olvides especificar encoding='utf-8' en la función open(). Omitirlo puede causar problemas de codificación, como caracteres corruptos en entornos Windows.

Consejo: uso de la sintaxis with

Al leer archivos, usar with como en with open(...) as f: evita que el archivo quede abierto y permite procesarlo de forma segura. Esta es la forma recomendada como buena práctica en Python.

5. Diferencias entre safe_load y load | Precauciones al leer YAML en Python

safe_load() y load() ¿Qué diferencia hay entre ellos?

En PyYAML existen varias funciones para leer archivos YAML, pero la que más genera confusión es la diferencia entre safe_load() y load().

A primera vista, ambas son funciones para cargar YAML como datos de Python, pero existen grandes diferencias en seguridad y funcionalidad. Si se usan incorrectamente, hay un riesgo de que un archivo YAML malicioso ejecute código, por lo que es importante comprenderlas y utilizarlas adecuadamente.

safe_load() Características (carga segura)

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

• Función básica recomendada
• Alta seguridad (no carga objetos Python arbitrarios)
• Limitado a tipos de datos básicos (diccionarios, listas, cadenas, números, etc.)
• Genera error al intentar cargar tipos u objetos desconocidos

safe_load() es, como su nombre indica, una función que realiza una carga segura y, al manejar archivos de configuración o datos externos, en la mayoría de los casos es la mejor opción.

load() Características (flexible pero con riesgos)

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.load(f, Loader=yaml.FullLoader)

• Permite interpretar YAML de forma más flexible
• Puede reconstruir objetos Python (p. ej., funciones, instancias de clases, etc.)
• Debido a riesgos de seguridad, es obligatorio especificar el Loader

En realidad, en versiones antiguas de PyYAML se podía usar load() de forma independiente, pero ahora se requiere especificar explícitamente el Loader. Si no se indica, aparecen advertencias o errores como los siguientes:

yaml.YAMLLoadWarning: calling yaml.load() without Loader=... is deprecated

Esto se debe a que load() en el pasado contenía una vulnerabilidad que permitía ejecutar objetos Python arbitrarios. Es decir, al cargar un archivo YAML malicioso, existe el riesgo de que se ejecute código Python sin intención.

Tipos de Loader (diferencias de seguridad y flexibilidad)

Conclusión: normalmente use safe_load()

Si solo necesita cargar archivos YAML como archivos de configuración o datos externos, safe_load() es suficiente y, de hecho, debería usarse. load() solo debe emplearse para casos especiales (por ejemplo, cuando se desea deserializar objetos Python personalizados).

6. Errores comunes y sus soluciones | Trampas al leer YAML con Python

¿Por qué aparecen problemas al cargar YAML?

YAML es un formato muy simple y legible, pero por ello es estricto con las reglas de sintaxis detalladas. En particular, al leerlo con Python, hay varios puntos que los principiantes pueden pasar por alto.

En esta sección, presentaremos de manera concreta los errores comunes al leer archivos YAML con Python y sus causas, y los métodos de solución.

1. Error de sintaxis por indentación incorrecta

En YAML, la indentación es un elemento importante que indica la estructura. Si hay inconsistencias entre espacios y tabulaciones, se producirá un error al cargar.

Ejemplo: YAML con error de indentación

user:
  name: Alice
    age: 30

Ejemplo de mensaje de error:

yaml.scanner.ScannerError: mapping values are not allowed here

Solución:

• La indentación debe uniformarse a espacios 2-4 (no usar tabulaciones)
• Los elementos hijos deben indentarse más que los elementos padres

2. Codificación del archivo que causa caracteres corruptos

Si el archivo YAML contiene caracteres no ASCII como japonés, y no se especifica la codificación adecuada, se producirán caracteres corruptos o errores de decodificación.

Ejemplo de error:

UnicodeDecodeError: 'cp932' codec can't decode byte...

Solución:

• Se puede resolver especificando explícitamente encoding='utf-8'
• En entornos Windows es un punto que se olvida especialmente

3. Ruta de archivo incorrecta / archivo inexistente

Es un error simple, pero si el archivo YAML especificado no existe, se producirá FileNotFoundError.

Ejemplo de error:

FileNotFoundError: [Errno 2] No such file or directory: 'config.yaml'

Solución:

• Verifique que la ruta esté especificada como ruta absoluta o como ruta relativa correcta
• Compruebe que no haya errores tipográficos en el nombre del archivo o la extensión
• Verifique que el archivo esté en el mismo directorio que el script

4. El resultado de safe_load es None

Esto ocurre incluso si la sintaxis del YAML es correcta, pero el contenido del archivo está vacío o solo contiene comentarios.

Ejemplo:

# No hay ninguna configuración en este archivo

Resultado:

data = yaml.safe_load(f)
print(data)  # Salida: None

Solución:

• Verifique que el archivo contenga datos YAML válidos
• Es un comportamiento normal que se devuelva None cuando solo hay comentarios o espacios en blanco

5. Error de análisis de estructuras YAML demasiado complejas

En archivos YAML de gran escala y con anidamiento profundo, pueden producirse errores debido a errores de sintaxis o al uso incorrecto de anclas/alias.

Solución:

• Verifique la sintaxis de forma incremental (validando por secciones pequeñas)
• yaml.YAMLError Se recomienda capturar la excepción y revisar los mensajes detallados

try:
    with open('config.yaml', 'r', encoding='utf-8') as f:
        data = yaml.safe_load(f)
except yaml.YAMLError as e:
    print(f"Error al cargar YAML: {e}")

Resumen: Si ocurre un error, no entre en pánico, revise la sintaxis y el entorno

YAML es un formato muy manejable si se presta un poco de atención a su escritura. Si ocurre un error, revise los siguientes puntos:

• ¿La indentación es correcta (no se usan tabulaciones)?
• ¿La codificación del archivo es UTF-8?
• ¿El archivo existe?
• ¿El contenido del YAML está escrito correctamente?

7. Aplicación: Cómo leer archivos YAML con múltiples documentos (safe_load_all)

YAML puede contener varios documentos en un solo archivo

Una de las grandes características de YAML es que se pueden definir varios bloques de datos (documentos) dentro de un solo archivo. Esto permite dividir configuraciones y estructuras mientras se gestionan en un único archivo.

Los documentos se separan explícitamente con --- (tres guiones).

Ejemplo de archivo YAML con múltiples documentos (multi.yaml)

# Configuración del servidor 1
---
server:
  host: localhost
  port: 8080

# Configuración del servidor 2
---
server:
  host: example.com
  port: 443

Un archivo YAML escrito de esta manera contiene dos bloques de datos independientes, los cuales deben leerse por separado.

Uso de yaml.safe_load_all()

En PyYAML, la función safe_all() está disponible para leer varios documentos. Esta función devuelve todos los documentos YAML del archivo como un <>iterador (objeto iterable).import yaml with open('multi.yaml', 'r', encoding='utf-8') as f: documents = yaml.safe_load_all(f) for doc in documents: print(doc)

Resultado de ejecución (ejemplo de salida):

{'server': {'host': 'localhost', 'port': 8080}}
{'server': {'host': 'example.com', 'port': 443}}

De esta manera, cada documento se obtiene como un diccionario individual y puede procesarse en un bucle para un uso flexible.

Atención a la diferencia con safe_load()

La safe_load() normal solo lee el primer documento, por lo que no es adecuada para archivos con varios documentos.

También es posible convertir los documentos leídos a una lista

En algunos casos, puede que desees obtener todos los documentos como una lista. En ese caso, basta usar list() como se muestra a continuación.

with open('multi.yaml', 'r', encoding='utf-8') as f:
    documents = list(yaml.safe_load_all(f))

Esto permite procesar en bloque en formato de lista o acceder mediante índices.

Nota: No todos los archivos YAML admiten múltiples documentos

Aunque no hay problema en usar safe_load_all() en archivos YAML que no están separados por ---, el resultado será solo un documento. En otras palabras, safe_load_all() es universal, pero si no hay varios documentos se comporta igual que safe_load().

8. [Nota adicional] Puntos al usar YAML como archivo de configuración

¿Por qué YAML es adecuado para archivos de configuración?

YAML posee una sintaxis fácil de leer y escribir para humanos y una flexibilidad en la expresión de estructuras anidadas, por lo que se adopta en muchos proyectos como «archivo de configuración». En particular, para aplicaciones y herramientas desarrolladas en Python, usar YAML mejora la claridad de la configuración y también la mantenibilidad.

En los siguientes usos, YAML es muy valioso:

• Configuración de entorno de aplicaciones web (producción/desarrollo/pruebas)
• Configuración de hiperparámetros en aprendizaje automático
• Cambio de comportamiento de scripts
• Gestión de información de dependencias externas como claves API (※ Prestar atención a la gestión de información confidencial)

Ejemplo de archivo de configuración YAML práctico

app:
  name: MyApp
  mode: production

logging:
  level: INFO
  file: logs/app.log

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

De esta manera, al agrupar los elementos de configuración por secciones, se obtiene un archivo de configuración cuya estructura es clara a primera vista para cualquiera. A diferencia de JSON, la capacidad de escribir comentarios libremente es muy importante en la práctica.

Jerarquización de la configuración aprovechando la estructura anidada

En YAML, la jerarquía se expresa mediante indentación, por lo que incluso configuraciones complejas se pueden expresar de manera intuitiva. Por ejemplo, cuando se quiere dividir la configuración por entornos, es posible agruparla de la siguiente manera:

env:
  dev:
    db: dev-db.local
    debug: true
  prod:
    db: prod-db.server
    debug: false

Si se carga esta configuración en el lado de Python, se puede seleccionar automáticamente la configuración adecuada mediante variables de entorno, etc.

Se pueden explicitar las intenciones con comentarios

En YAML se pueden escribir comentarios usando #. De esta manera, se tiene la gran ventaja de poder describir directamente en el archivo de configuración información como «por qué está configurado así» o «cuándo debería cambiarse».

# Configuración del modo de la aplicación (dev, test, production cualquiera)
mode: production

En JSON no se pueden escribir comentarios, por lo que hay una limitación en cuanto a agregar tales explicaciones.

Ejemplo de código para cargar YAML en tiempo de ejecución (Aplicación)

Lo siguiente es un ejemplo de cargar la configuración YAML en el lado del script Python y aplicarla a la aplicación:

import yaml

with open('settings.yaml', 'r', encoding='utf-8') as f:
    config = yaml.safe_load(f)

app_name = config['app']['name']
mode = config['app']['mode']
db_host = config['database']['host']

De esta manera, al tratar el archivo YAML como un diccionario de Python, se puede gestionar sin escribir los valores de configuración directamente en el código.

Puntos de atención: Prestar suficiente atención al manejo de información confidencial

YAML es fácil de manejar para humanos, pero por otro lado, es un formato que se guarda en texto plano. Por lo tanto, al describir información confidencial como claves API o contraseñas en un archivo YAML, son necesarias medidas como las siguientes:

• .gitignore para prevenir el commit al repositorio
• .env archivo, etc., y solo referenciar desde YAML
• Aplicar encriptación o restricciones de acceso

9. Preguntas frecuentes (FAQ)

En esta sección, explicamos en formato de preguntas y respuestas (Q&A) las dudas más frecuentes al leer archivos YAML con Python y los puntos donde los principiantes suelen tropezar. El contenido también es útil al usarlo en proyectos reales, así que le invitamos a revisarlo.

Q1. ¿YAML o JSON, cuál es más fácil de usar con Python?

A. YAML tiene alta legibilidad y es muy útil como archivo de configuración.

En Python, JSON también está soportado por la biblioteca estándar, pero muchas personas consideran que YAML es más fácil de usar para archivos de configuración porque permite escribir comentarios, tiene una estructura más clara, entre otras razones. Sin embargo, en situaciones donde la velocidad de procesamiento o la compatibilidad de intercambio de datos son prioritarias, JSON puede ser preferido.

Q2. ¿No se debe usar yaml.load()?

A. En principio, es más seguro usar safe_load().

load() es muy flexible, pero puede reconstruir cualquier objeto de Python, lo que representa un riesgo de seguridad. Si se carga un archivo YAML malintencionado, podría ejecutarse código no deseado, por lo que se recomienda usar safe_load() como práctica básica.

Si es necesario usar load(), especifique explícitamente algo como Loader=yaml.FullLoader y diseñe la implementación teniendo en cuenta la seguridad.

Q3. ¿Por qué el contenido del YAML leído queda vacío (None)?

A. Es un comportamiento normal que ocurre cuando el archivo YAML está vacío o contiene solo comentarios.

# Este archivo aún no está configurado

Al cargar un archivo como el anterior, el valor de retorno de safe_load() será None. Esto no es un error, sino un “dato vacío” válido en YAML. Verifique que el contenido del archivo esté escrito correctamente.

Q4. ¿Se pueden reutilizar valores en un archivo YAML (como variables)?

A. YAML dispone de un mecanismo llamado “ancla” y “alias”.

default: &defaults
  timeout: 30
  retries: 3

service1:
  <<: *defaults
  host: service1.local

service2:
  <<: *defaults
  host: service2.local

De esta manera, usando & para definir un ancla y * para referenciar un alias, es posible reutilizar la misma configuración en varios lugares. Sin embargo, al usar esta sintaxis con PyYAML puede requerir una versión específica o una configuración de Loader, por lo que se recomienda verificar su funcionamiento con anticipación.

Q5. En entornos Windows, los caracteres japoneses aparecen corruptos. ¿Cómo solucionarlo?

A. Especificar la codificación al leer el archivo lo soluciona.

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

En Windows, el código de caracteres predeterminado (cp932) puede no leer correctamente archivos YAML escritos en UTF-8. Siempre indique encoding='utf-8'.

Q6. ¿Cómo leer un archivo YAML dividido en varios bloques de configuración?

A. Usando safe_load_all() se pueden cargar varios documentos.

---
app: App1
port: 3000
---
app: App2
port: 4000

Este tipo de archivo se puede procesar documento por documento con yaml.safe_load_all():

with open('multi.yaml', 'r', encoding='utf-8') as f:
    for doc in yaml.safe_load_all(f):
        print(doc)

10. Resumen | Domina la lectura de YAML con Python

Repaso de los conceptos básicos y avanzados de la lectura de YAML

En este artículo, dirigido a quienes desean leer archivos YAML con Python, hemos explicado paso a paso desde el uso básico, la solución de errores comunes, hasta ejemplos de aplicación con múltiples documentos y como archivos de configuración.

A continuación, resumimos los puntos clave del artículo：

• Instalación de PyYAML: para trabajar con YAML en Python, primero se necesita pip install pyyaml.
• Lectura básica: usando yaml.safe_load(), puedes cargar YAML de forma segura y sencilla como diccionarios o listas.
• Manejo de errores: los problemas de indentación y codificación son comunes. Es importante la verificación de sintaxis y encoding='utf-8'.
• Diferencia con load(): si priorizas la seguridad, debes usar safe_load(). load() requiere especificar un Loader adecuado.
• Soporte para múltiples documentos: con safe_load_all() puedes procesar de forma flexible varios bloques de configuración dentro de un solo archivo.
• Utilidad como archivo de configuración: YAML, con su alta legibilidad y flexibilidad, es ideal para la gestión de configuraciones en proyectos Python.

Próximos pasos: Aprovecha más YAML

Ahora que has dominado la lectura de YAML, avanzar a los siguientes pasos te permitirá aplicarlo aún más en el trabajo：

• Escritura en archivos YAML: generación automática de archivos de configuración usando yaml.dump().
• Conversión bidireccional con JSON: útil al integrar con APIs web y servicios externos.
• Uso combinado con archivos .env y variables de entorno: construcción de una gestión de configuración de alta seguridad.
• Carga automática de configuraciones: mecanismo para leer dinámicamente el archivo de configuración adecuado según el entorno al iniciar la aplicación.

Al dominar estos aspectos, el desarrollo con Python será más flexible y reutilizable.

Continuaremos presentando de forma clara técnicas y herramientas de Python útiles en el campo. Por favor, añádelo a tus marcadores y utilízalo repetidamente.

Con esto, concluimos la explicación sobre la carga de archivos YAML con Python.
Adquiere conocimientos aplicables al trabajo y, por favor, incorpora YAML en tus proyectos.