Comprehensive Guide to Using PyYAML for YAML Processing in Python

PyYAML is a popular Python library for handling YAML configuration files, a human‑readable data‑serialization format.

Installation

First, ensure PyYAML is installed:

pip install pyyaml

1. Read a YAML file

Use case: Load configuration from a YAML file.

import yaml
with open('config.yaml', 'r') as file:
    config = yaml.safe_load(file)
    print(config)

# config.yaml:
# database:
#   host: localhost
#   port: 3306
#   username: user
#   password: secret

Output:

{
    'database': {
        'host': 'localhost',
        'port': 3306,
        'username': 'user',
        'password': 'secret'
    }
}

2. Write a YAML file

Use case: Save data as a YAML configuration file.

import yaml
data = {
    'database': {
        'host': 'localhost',
        'port': 3306,
        'username': 'user',
        'password': 'secret'
    }
}
with open('config.yaml', 'w') as file:
    yaml.safe_dump(data, file)

Resulting config.yaml :

database:
  host: localhost
  port: 3306
  username: user
  password: secret

3. Load a YAML string

Use case: Parse configuration from a YAML‑formatted string.

import yaml
yaml_string = """

database:
  host: localhost
  port: 3306
  username: user
  password: secret
"""
config = yaml.safe_load(yaml_string)
print(config)

Output:

{
    'database': {
        'host': 'localhost',
        'port': 3306,
        'username': 'user',
        'password': 'secret'
    }
}

4. Generate a YAML string

Use case: Convert a Python object to a YAML string.

import yaml
data = {
    'database': {
        'host': 'localhost',
        'port': 3306,
        'username': 'user',
        'password': 'secret'
    }
}
yaml_string = yaml.safe_dump(data)
print(yaml_string)

Result:

database:
  host: localhost
  port: 3306
  username: user
  password: secret

5. Handle lists

Use case: Process list data inside a YAML file.

import yaml
with open('list.yaml', 'r') as file:
    data = yaml.safe_load(file)
    print(data)
# list.yaml:
# fruits:
#   - apple
#   - banana
#   - cherry

Output:

{'fruits': ['apple', 'banana', 'cherry']}

6. Handle nested structures

Use case: Work with nested mappings in YAML.

import yaml
with open('nested.yaml', 'r') as file:
    data = yaml.safe_load(file)
    print(data)
# nested.yaml:
# user:
#   name: John Doe
#   age: 30
#   address:
#     street: 123 Main St
#     city: Anytown
#     state: CA

Output:

{
    'user': {
        'name': 'John Doe',
        'age': 30,
        'address': {
            'street': '123 Main St',
            'city': 'Anytown',
            'state': 'CA'
        }
    }
}

7. Handle complex data types

Use case: Parse YAML containing dictionaries and lists together.

import yaml
with open('complex.yaml', 'r') as file:
    data = yaml.safe_load(file)
    print(data)
# complex.yaml:
# employees:
#   - name: Alice
#     position: Developer
#     skills:
#       - Python
#       - JavaScript
#   - name: Bob
#     position: Designer
#     skills:
#       - Photoshop
#       - Illustrator

Output:

{
    'employees': [
        {'name': 'Alice', 'position': 'Developer', 'skills': ['Python', 'JavaScript']},
        {'name': 'Bob', 'position': 'Designer', 'skills': ['Photoshop', 'Illustrator']}
    ]
}

8. Use tags

Use case: Represent specific data types with YAML tags.

import yaml
yaml_string = """
!!python/object:datetime.datetime
2024-08-15T12:42:00Z
"""
data = yaml.safe_load(yaml_string)
print(data)

Output:

2024-08-15 12:42:00+00:00

9. Use anchors and aliases

Use case: Avoid duplication by referencing the same structure.

import yaml
yaml_string = """
company:
  name: Example Corp
  employees:
    - &employee
      name: Alice
      position: Developer
    - <<: *employee
      name: Bob
      position: Designer
"""
data = yaml.safe_load(yaml_string)
print(data)

Output:

{
    'company': {
        'name': 'Example Corp',
        'employees': [
            {'name': 'Alice', 'position': 'Developer'},
            {'name': 'Bob', 'position': 'Designer'}
        ]
    }
}

10. Use YAML tags to represent Python classes

Use case: Deserialize a YAML document into a custom Python class.

import yaml
class User:
    def __init__(self, name, age):
        self.name = name
        self.age = age

yaml_string = """
!!python/object:__main__.User
- Alice
- 30
"""
user = yaml.safe_load(yaml_string)
print(user.name, user.age)

Output:

Alice 30

11. Process YAML streams

Use case: Read multiple documents from a single YAML stream.

import yaml
yaml_stream = """
--- # Document 1
name: Alice
age: 30
--- # Document 2
name: Bob
age: 25
"""
for doc in yaml.safe_load_all(yaml_stream):
    print(doc)

Output:

{'name': 'Alice', 'age': 30}
{'name': 'Bob', 'age': 25}

12. Use environment variables

Use case: Dynamically replace values in a YAML file with environment variables.

import os
import yaml
with open('env.yaml', 'r') as file:
    data = yaml.safe_load(file)
    data['database']['password'] = os.getenv('DB_PASSWORD')
    print(data)
# env.yaml:
# database:
#   host: localhost
#   port: 3306
#   username: user
#   password: ${DB_PASSWORD}

Assuming DB_PASSWORD is set to mysecretpassword , the printed result is:

{
    'database': {
        'host': 'localhost',
        'port': 3306,
        'username': 'user',
        'password': 'mysecretpassword'
    }
}