or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

customization.mddumping-serialization.mderror-handling.mdindex.mdloaders-dumpers.mdloading-parsing.mdsafe-operations.md
tile.json

tessl/pypi-pyyaml

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyyaml@6.0.x

To install, run

npx @tessl/cli install tessl/pypi-pyyaml@6.0.0

index.mddocs/

PyYAML

A comprehensive YAML processing framework for Python that provides complete YAML 1.1 parsing and emission capabilities with Unicode support, pickle integration, and extensible API. The library features both pure Python and high-performance C extension implementations through LibYAML bindings, offering developers flexibility between portability and speed.

Package Information

  • Package Name: PyYAML
  • Language: Python
  • Installation: pip install PyYAML
  • C Extensions: Optional LibYAML bindings for high performance

Core Imports

import yaml

Most commonly used functions are available directly from the main module:

from yaml import safe_load, safe_dump, load, dump

For advanced usage with specific loaders/dumpers:

from yaml import SafeLoader, SafeDumper, FullLoader, Loader, UnsafeLoader

Basic Usage

import yaml

# Safe loading (recommended for untrusted input)
data = yaml.safe_load("""
name: John Doe
age: 30
skills:
  - Python
  - YAML
  - JSON
""")

print(data['name'])  # John Doe
print(data['skills'])  # ['Python', 'YAML', 'JSON']

# Safe dumping
yaml_string = yaml.safe_dump(data, default_flow_style=False)
print(yaml_string)

# Loading multiple documents
documents = yaml.safe_load_all("""
---
document: 1
name: First
---
document: 2
name: Second
""")

for doc in documents:
    print(f"Document {doc['document']}: {doc['name']}")

Architecture

PyYAML follows a multi-stage processing pipeline:

  • Reader: Handles input stream encoding and character validation
  • Scanner: Converts character stream to tokens (lexical analysis)
  • Parser: Converts tokens to events (syntactic analysis)
  • Composer: Converts events to representation tree (semantic analysis)
  • Constructor: Converts representation tree to Python objects
  • Representer: Converts Python objects to representation tree
  • Serializer: Converts representation tree to events
  • Emitter: Converts events to YAML text

This modular design allows for extensive customization at each processing stage through inheritance and configuration.

Capabilities

Safe Operations

High-level functions designed for safe processing of YAML data, recommended for handling untrusted input. These operations use restricted loaders that only handle basic YAML types.

def safe_load(stream: str | bytes | IO) -> Any
def safe_load_all(stream: str | bytes | IO) -> Iterator[Any]
def safe_dump(data: Any, stream: IO = None, **kwds) -> str | None
def safe_dump_all(documents: Iterable[Any], stream: IO = None, **kwds) -> str | None

Safe Operations

Loading and Parsing

Comprehensive YAML loading capabilities with multiple security levels and processing stages. Includes low-level parsing functions for advanced use cases.

def load(stream: str | bytes | IO, Loader: type) -> Any
def load_all(stream: str | bytes | IO, Loader: type) -> Iterator[Any]
def full_load(stream: str | bytes | IO) -> Any
def full_load_all(stream: str | bytes | IO) -> Iterator[Any]
def parse(stream: str | bytes | IO, Loader: type = Loader) -> Iterator[Event]
def compose(stream: str | bytes | IO, Loader: type = Loader) -> Node | None

Loading and Parsing

Dumping and Serialization

YAML output generation with extensive formatting options and multiple dumper classes for different security levels and feature sets.

def dump(data: Any, stream: IO = None, Dumper: type = Dumper, **kwds) -> str | None
def dump_all(documents: Iterable[Any], stream: IO = None, Dumper: type = Dumper, **kwds) -> str | None
def emit(events: Iterable[Event], stream: IO = None, Dumper: type = Dumper, **kwds) -> str | None
def serialize(node: Node, stream: IO = None, Dumper: type = Dumper, **kwds) -> str | None

Dumping and Serialization

Loaders and Dumpers

Comprehensive set of loader and dumper classes providing different security levels and performance characteristics, including optional C-based implementations.

class BaseLoader: ...
class SafeLoader: ...
class FullLoader: ...  
class Loader: ...
class UnsafeLoader: ...
class BaseDumper: ...
class SafeDumper: ...
class Dumper: ...
# C Extensions (when LibYAML available)
class CBaseLoader: ...
class CSafeLoader: ...
class CFullLoader: ...
class CLoader: ...
class CUnsafeLoader: ...
class CBaseDumper: ...
class CSafeDumper: ...
class CDumper: ...

Loaders and Dumpers

Customization and Extension

Advanced customization capabilities for extending YAML processing with custom constructors, representers, and resolvers.

def add_constructor(tag: str, constructor: Callable, Loader: type = None) -> None
def add_representer(data_type: type, representer: Callable, Dumper: type = Dumper) -> None
def add_implicit_resolver(tag: str, regexp: Pattern, first: str = None, Loader: type = None, Dumper: type = Dumper) -> None

Customization and Extension

Error Handling

Comprehensive exception hierarchy for handling different types of YAML processing errors with detailed position information.

class YAMLError(Exception): ...
class MarkedYAMLError(YAMLError): ...
class ReaderError(YAMLError): ...
class ScannerError(MarkedYAMLError): ...
class ParserError(MarkedYAMLError): ...

Error Handling

Utility Functions

Legacy and utility functions for compatibility and special use cases.

def warnings(settings: dict = None) -> dict:
    """
    Deprecated warnings control function.
    
    This function is deprecated and no longer functional. It returns an empty
    dictionary for backwards compatibility but does not affect YAML processing.
    
    Args:
        settings (dict, optional): Ignored settings parameter
        
    Returns:
        dict: Empty dictionary
        
    Note:
        This function is deprecated and will be removed in a future version.
    """

Types

Core Types

# Type aliases for common input/output types
from typing import Union, Type, IO, Any, Iterator
from re import Pattern

Stream = Union[str, bytes, IO[str], IO[bytes]]
LoaderType = Union[Type[BaseLoader], Type[SafeLoader], Type[FullLoader], Type[Loader], Type[UnsafeLoader]]
DumperType = Union[Type[BaseDumper], Type[SafeDumper], Type[Dumper]]

# Position tracking for error reporting
class Mark:
    """Position marker for error reporting and debugging."""
    name: str      # Source name (filename, etc.)
    index: int     # Character index in stream
    line: int      # Line number (0-based)
    column: int    # Column number (0-based) 
    buffer: str    # Buffer content around position
    pointer: int   # Pointer position in buffer

# Low-level processing components  
class Token:
    """Base class for lexical tokens."""
    start_mark: Mark
    end_mark: Mark

class Event:
    """Base class for parsing events."""
    start_mark: Mark
    end_mark: Mark

class Node:
    """Base class for representation tree nodes."""
    tag: str
    value: Any
    start_mark: Mark
    end_mark: Mark

Module Constants

__version__: str  # '6.0.2'
__with_libyaml__: bool  # True if C extensions available