tessl/pypi-pyyaml

YAML parser and emitter for Python with complete YAML 1.1 support, Unicode handling, and optional LibYAML bindings for high performance

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Dumping and Serialization

Name: tessl/pypi-pyyaml
Author: tessl

YAML output generation with extensive formatting options and multiple dumper classes for different security levels and feature sets. Convert Python objects to YAML text with fine-grained control over output format.

Capabilities

High-Level Dumping

Convert Python objects to YAML strings or streams with comprehensive formatting control.

def dump(data, stream=None, Dumper=Dumper, **kwds):
    """
    Serialize a Python object into a YAML stream.
    
    Args:
        data (Any): Python object to serialize
        stream (IO, optional): Output stream. If None, return as string
        Dumper (type, optional): Dumper class to use (default: Dumper)
        **kwds: Formatting options
        
    Keyword Arguments:
        default_style (str): Default scalar style (None, '"', "'", '|', '>')
        default_flow_style (bool): Use flow style for collections (default: False)
        canonical (bool): Produce canonical YAML (default: False)
        indent (int): Number of spaces for indentation (default: 2)
        width (int): Maximum line width (default: 80)
        allow_unicode (bool): Allow unicode characters (default: True)
        line_break (str): Line break character(s) (default: platform default)
        encoding (str): Output encoding for byte streams (default: 'utf-8')
        explicit_start (bool): Write document start marker --- (default: False)
        explicit_end (bool): Write document end marker ... (default: False)
        version (tuple): YAML version to use (default: (1, 1))
        tags (dict): Custom tag mappings
        sort_keys (bool): Sort dictionary keys (default: True)
        
    Returns:
        str | None: YAML string if stream is None, otherwise None
        
    Raises:
        RepresenterError: If an object cannot be represented
        EmitterError: If output cannot be generated
    """

def dump_all(documents, stream=None, Dumper=Dumper, **kwds):
    """
    Serialize a sequence of Python objects into a YAML stream.
    
    Args:
        documents (Iterable[Any]): Sequence of Python objects to serialize
        stream (IO, optional): Output stream. If None, return as string
        Dumper (type, optional): Dumper class to use
        **kwds: Formatting options (same as dump)
        
    Returns:
        str | None: YAML string if stream is None, otherwise None
        
    Raises:
        RepresenterError: If any object cannot be represented
        EmitterError: If output cannot be generated
    """

Usage Examples

import yaml
from datetime import datetime, date

data = {
    'application': 'MyApp',
    'version': '2.1.0',
    'release_date': date(2023, 12, 15),
    'last_updated': datetime(2023, 12, 15, 14, 30, 0),
    'features': ['authentication', 'api', 'dashboard'],
    'settings': {
        'debug': False,
        'max_connections': 100,
        'timeout': 30.0
    },
    'servers': [
        {'name': 'web1', 'ip': '192.168.1.10'},
        {'name': 'web2', 'ip': '192.168.1.11'}
    ]
}

# Basic dumping
yaml_output = yaml.dump(data)
print(yaml_output)

# Pretty formatted output
yaml_pretty = yaml.dump(
    data,
    default_flow_style=False,
    indent=4,
    width=120,
    sort_keys=False
)

# Canonical YAML (strict format)
yaml_canonical = yaml.dump(data, canonical=True)

# With explicit document markers
yaml_explicit = yaml.dump(
    data,
    explicit_start=True,
    explicit_end=True
)

# Multiple documents
documents = [
    {'config': 'development', 'debug': True},
    {'config': 'production', 'debug': False}
]

yaml_multi = yaml.dump_all(
    documents,
    explicit_start=True,
    default_flow_style=False
)

# Output to file
with open('output.yaml', 'w') as f:
    yaml.dump(data, f, default_flow_style=False, sort_keys=False)

# Output to binary file with encoding
with open('output.yaml', 'wb') as f:
    yaml.dump(data, f, encoding='utf-8')

Low-Level Serialization

Access lower-level serialization stages for advanced output control.

def serialize_all(nodes, stream=None, Dumper=Dumper, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None):
    """
    Serialize a sequence of representation trees into a YAML stream.
    
    Args:
        nodes (Iterable[Node]): Sequence of representation tree nodes
        stream (IO, optional): Output stream. If None, return as string
        Dumper (type, optional): Dumper class to use
        canonical (bool, optional): Produce canonical YAML
        indent (int, optional): Indentation width
        width (int, optional): Maximum line width
        allow_unicode (bool, optional): Allow unicode characters
        line_break (str, optional): Line break character(s)
        encoding (str, optional): Output encoding for byte streams
        explicit_start (bool, optional): Write document start marker
        explicit_end (bool, optional): Write document end marker
        version (tuple, optional): YAML version to use
        tags (dict, optional): Custom tag mappings
        
    Returns:
        str | None: YAML string if stream is None, otherwise None
    """

def serialize(node, stream=None, Dumper=Dumper, **kwds):
    """
    Serialize a representation tree into a YAML stream.
    
    Args:
        node (Node): Root node of representation tree
        stream (IO, optional): Output stream. If None, return as string
        Dumper (type, optional): Dumper class to use
        **kwds: Formatting options
        
    Returns:
        str | None: YAML string if stream is None, otherwise None
    """

def emit(events, stream=None, Dumper=Dumper, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None):
    """
    Emit YAML parsing events into a stream.
    
    Args:
        events (Iterable[Event]): Sequence of YAML events
        stream (IO, optional): Output stream. If None, return as string
        Dumper (type, optional): Dumper class to use for emission
        canonical (bool, optional): Produce canonical YAML
        indent (int, optional): Indentation width
        width (int, optional): Maximum line width
        allow_unicode (bool, optional): Allow unicode characters
        line_break (str, optional): Line break character(s)
        
    Returns:
        str | None: YAML string if stream is None, otherwise None
    """

Usage Examples

import yaml
from yaml import SafeLoader, Dumper
from yaml.nodes import ScalarNode, MappingNode

# Create representation tree manually
key_node = ScalarNode(tag='tag:yaml.org,2002:str', value='name')
value_node = ScalarNode(tag='tag:yaml.org,2002:str', value='John')
mapping_node = MappingNode(tag='tag:yaml.org,2002:map', value=[(key_node, value_node)])

# Serialize the node
yaml_output = yaml.serialize(mapping_node)
print(yaml_output)  # name: John

# Work with events from parsing
yaml_content = "name: John\nage: 30"
events = list(yaml.parse(yaml_content, SafeLoader))

# Re-emit the events
yaml_recreated = yaml.emit(events)
print(yaml_recreated)  # Recreates original YAML

Output Formatting Options

Scalar Styles

Control how scalar values are formatted in the output:

data = {'multiline': 'Line 1\nLine 2\nLine 3', 'simple': 'value'}

# Literal style (preserves newlines)
yaml.dump(data, default_style='|')
# multiline: |
#   Line 1
#   Line 2
#   Line 3

# Folded style (folds newlines to spaces)
yaml.dump(data, default_style='>')
# multiline: >
#   Line 1 Line 2 Line 3

# Quoted styles
yaml.dump(data, default_style='"')  # Double quoted
yaml.dump(data, default_style="'")  # Single quoted

Collection Styles

Control how collections (lists and dictionaries) are formatted:

data = {
    'list': [1, 2, 3],
    'dict': {'a': 1, 'b': 2}
}

# Block style (default)
yaml.dump(data, default_flow_style=False)
# list:
# - 1
# - 2
# - 3
# dict:
#   a: 1
#   b: 2

# Flow style  
yaml.dump(data, default_flow_style=True)
# {dict: {a: 1, b: 2}, list: [1, 2, 3]}

Indentation and Width

data = {'nested': {'deep': {'value': 'test'}}, 'list': [1, 2, 3, 4, 5]}

# Custom indentation
yaml.dump(data, indent=4)

# Line width control
yaml.dump(data, width=40)  # Shorter lines
yaml.dump(data, width=200)  # Longer lines allowed

Dumper Classes

SafeDumper

Outputs only basic YAML types
Safe for any consumer to read
Recommended for configuration files

Dumper

Full Python object support
Can output Python-specific tags
May not be readable by non-Python YAML parsers

Custom Dumpers

# Create custom dumper with specific behavior
class CustomDumper(yaml.SafeDumper):
    pass

# Use custom dumper
yaml.dump(data, Dumper=CustomDumper)

Performance Considerations

C Extensions

When LibYAML is available, use C-based dumpers for better performance:

import yaml

if yaml.__with_libyaml__:
    # Use C dumper for better performance
    yaml_output = yaml.dump(data, Dumper=yaml.CDumper)
else:
    # Fall back to pure Python
    yaml_output = yaml.dump(data, Dumper=yaml.Dumper)

Memory Management

For large documents:

Use streaming output with file objects
Process documents in chunks when possible
Consider memory limits for very large data structures

# Stream directly to file to avoid memory buildup
with open('large_output.yaml', 'w') as f:
    yaml.dump_all(large_document_sequence, f)

Error Handling

Dumping operations can raise several types of errors:

try:
    result = yaml.dump(data)
except yaml.RepresenterError as e:
    print(f"Cannot represent object: {e}")
except yaml.EmitterError as e:
    print(f"Cannot emit YAML: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Common error scenarios: