tessl/pypi-types-pyyaml

Type stubs for PyYAML, a full-featured YAML framework for Python

Overview

Eval results

Files

Advanced Components

Name: tessl/pypi-types-pyyaml
Author: tessl

Internal processing components for custom loader and dumper construction, including constructors, representers, resolvers, and processing pipeline components. These components provide the building blocks for customized YAML processing.

Capabilities

Constructor Components

Constructor classes handle converting YAML nodes to Python objects with different levels of safety and functionality.

class BaseConstructor:
    """
    Base constructor class providing fundamental object construction.
    
    Attributes:
    - yaml_constructors: dict - Registry of tag constructors
    - yaml_multi_constructors: dict - Registry of tag prefix constructors
    - constructed_objects: dict - Cache of constructed objects
    - recursive_objects: dict - Tracking for recursive construction
    - state_generators: list - State generator functions
    - deep_construct: bool - Enable deep construction
    """
    
    def check_data(self) -> bool:
        """Check if more data is available for construction."""
    
    def get_data(self) -> Any:
        """Get next available data object."""
    
    def get_single_data(self) -> Any:
        """Get single document data object."""
    
    def construct_document(self, node) -> Any:
        """Construct Python object from document node."""
    
    def construct_object(self, node, deep=False) -> Any:
        """Construct Python object from any node."""
    
    def construct_scalar(self, node) -> Any:
        """Construct scalar value from scalar node."""
    
    def construct_sequence(self, node, deep=False) -> list:
        """Construct list from sequence node."""
    
    def construct_mapping(self, node, deep=False) -> dict:
        """Construct dictionary from mapping node."""
    
    def construct_pairs(self, node, deep=False) -> list:
        """Construct list of key-value pairs from mapping node."""

class SafeConstructor(BaseConstructor):
    """
    Safe constructor for standard YAML types only.
    
    Additional Attributes:
    - bool_values: dict - Boolean value mappings
    - inf_value: float - Infinity value representation
    - nan_value: float - NaN value representation  
    - timestamp_regexp: Pattern - Timestamp parsing pattern
    """
    
    def flatten_mapping(self, node):
        """Flatten mapping nodes handling merge keys."""
    
    def construct_yaml_null(self, node) -> None:
        """Construct null/None values."""
    
    def construct_yaml_bool(self, node) -> bool:
        """Construct boolean values."""
    
    def construct_yaml_int(self, node) -> int:
        """Construct integer values."""
    
    def construct_yaml_float(self, node) -> float:
        """Construct floating-point values."""
    
    def construct_yaml_binary(self, node) -> bytes:
        """Construct binary data from base64."""
    
    def construct_yaml_timestamp(self, node):
        """Construct datetime objects from timestamps."""
    
    def construct_yaml_omap(self, node):
        """Construct ordered mappings."""
    
    def construct_yaml_pairs(self, node) -> list:
        """Construct key-value pair lists."""
    
    def construct_yaml_set(self, node) -> set:
        """Construct set objects."""
    
    def construct_yaml_str(self, node) -> str:
        """Construct string values."""
    
    def construct_yaml_seq(self, node) -> list:
        """Construct sequence/list values."""
    
    def construct_yaml_map(self, node) -> dict:
        """Construct mapping/dict values."""

class FullConstructor(SafeConstructor):
    """
    Full constructor with extended Python object support.
    
    Supports Python built-in types like tuples, sets, and complex numbers
    while remaining safer than UnsafeConstructor.
    """
    
    def construct_python_str(self, node) -> str:
        """Construct Python string objects."""
    
    def construct_python_unicode(self, node) -> str:
        """Construct Unicode string objects."""
    
    def construct_python_bytes(self, node) -> bytes:
        """Construct byte string objects."""
    
    def construct_python_long(self, node) -> int:
        """Construct long integer objects."""
    
    def construct_python_complex(self, node) -> complex:
        """Construct complex number objects."""
    
    def construct_python_tuple(self, node) -> tuple:
        """Construct tuple objects."""

class UnsafeConstructor(FullConstructor):
    """
    Unsafe constructor allowing arbitrary Python object construction.
    
    WARNING: Can execute arbitrary code. Only use with trusted input.
    """

class Constructor(SafeConstructor):
    """Legacy constructor class (alias for SafeConstructor)."""

Representer Components

Representer classes handle converting Python objects to YAML nodes with different levels of type support.

class BaseRepresenter:
    """
    Base representer class for converting Python objects to YAML nodes.
    
    Class Attributes:
    - yaml_representers: dict - Registry of type representers
    - yaml_multi_representers: dict - Registry of type hierarchy representers
    
    Instance Attributes:
    - default_style: str - Default scalar style
    - sort_keys: bool - Sort mapping keys alphabetically
    - default_flow_style: bool - Default collection flow style
    - represented_objects: dict - Cache of represented objects
    - object_keeper: list - Object reference keeper
    - alias_key: int - Current alias key
    """
    
    def represent(self, data) -> str:
        """Represent data and return YAML string."""
    
    def represent_data(self, data):
        """Represent data and return YAML node."""
    
    def represent_scalar(self, tag: str, value: str, style=None):
        """Create scalar node representation."""
    
    def represent_sequence(self, tag: str, sequence, flow_style=None):
        """Create sequence node representation."""
    
    def represent_mapping(self, tag: str, mapping, flow_style=None):
        """Create mapping node representation."""
    
    def ignore_aliases(self, data) -> bool:
        """Check if aliases should be ignored for this data."""

class SafeRepresenter(BaseRepresenter):
    """
    Safe representer for standard Python types.
    
    Class Attributes:
    - inf_value: float - Infinity value
    """
    
    def represent_none(self, data) -> None:
        """Represent None values."""
    
    def represent_str(self, data):
        """Represent string values."""
    
    def represent_binary(self, data):
        """Represent binary data as base64."""
    
    def represent_bool(self, data):
        """Represent boolean values."""
    
    def represent_int(self, data):
        """Represent integer values."""
    
    def represent_float(self, data):
        """Represent floating-point values."""
    
    def represent_list(self, data):
        """Represent list objects."""
    
    def represent_dict(self, data):
        """Represent dictionary objects."""
    
    def represent_set(self, data):
        """Represent set objects."""
    
    def represent_date(self, data):
        """Represent date objects."""
    
    def represent_datetime(self, data):
        """Represent datetime objects."""

class Representer(SafeRepresenter):
    """
    Extended representer with additional Python object support.
    """
    
    def represent_complex(self, data):
        """Represent complex number objects."""
    
    def represent_tuple(self, data):
        """Represent tuple objects."""
    
    def represent_name(self, data):
        """Represent function/method names."""
    
    def represent_module(self, data):
        """Represent module objects."""
    
    def represent_object(self, data):
        """Represent arbitrary Python objects."""

Resolver Components

Resolver classes handle automatic tag detection and assignment based on scalar values and document structure.

class BaseResolver:
    """
    Base resolver for YAML tag resolution.
    
    Class Attributes:
    - DEFAULT_SCALAR_TAG: str - Default tag for scalars
    - DEFAULT_SEQUENCE_TAG: str - Default tag for sequences
    - DEFAULT_MAPPING_TAG: str - Default tag for mappings
    - yaml_implicit_resolvers: dict - Registry of implicit resolvers
    - yaml_path_resolvers: dict - Registry of path resolvers
    """
    
    def descend_resolver(self, current_node, current_index):
        """Descend into resolver tree for nested resolution."""
    
    def ascend_resolver(self):
        """Ascend from resolver tree after nested resolution."""
    
    def resolve(self, kind, value, implicit):
        """Resolve appropriate tag for a value."""

class Resolver(BaseResolver):
    """
    Standard resolver with built-in tag resolution patterns.
    
    Includes patterns for detecting integers, floats, booleans,
    null values, timestamps, and other standard YAML types.
    """

Processing Pipeline Components

Core components that handle different stages of the YAML processing pipeline.

class Reader:
    """
    YAML stream reader handling encoding and character-level input.
    
    Attributes:
    - name: str - Stream name
    - stream: Any - Input stream
    - encoding: str - Stream encoding
    - index: int - Current character index
    - line: int - Current line number
    - column: int - Current column number
    """
    
    def peek(self, index=0) -> str:
        """Peek at character at specified index."""
    
    def prefix(self, length=1) -> str:
        """Get character prefix of specified length."""
    
    def forward(self, length=1):
        """Advance position by specified length."""
    
    def get_mark(self):
        """Get current position mark."""

class Scanner:
    """
    YAML token scanner converting characters to tokens.
    
    Attributes:
    - done: bool - Scanning completion flag
    - tokens: list - Token queue
    - flow_level: int - Current flow nesting level
    - indent: int - Current indentation level
    """
    
    def check_token(self, *choices) -> bool:
        """Check if next token matches any of the given choices."""
    
    def peek_token(self):
        """Peek at next token without consuming it."""
    
    def get_token(self):
        """Get and consume next token."""

class Parser:
    """
    YAML event parser converting tokens to events.
    
    Attributes:
    - current_event: Event - Current event
    - yaml_version: tuple - YAML version
    - tag_handles: dict - Tag handle mappings
    """
    
    def check_event(self, *choices) -> bool:
        """Check if next event matches any of the given choices."""
    
    def peek_event(self):
        """Peek at next event without consuming it."""
    
    def get_event(self):
        """Get and consume next event."""

class Composer:
    """
    YAML node composer converting events to node trees.
    
    Attributes:
    - anchors: dict - Anchor to node mappings
    """
    
    def check_node(self) -> bool:
        """Check if a node is available."""
    
    def get_node(self):
        """Get next node."""
    
    def compose_node(self, parent, index):
        """Compose node with specified parent and index."""

class Serializer:
    """
    YAML serializer converting node trees to events.
    
    Attributes:
    - use_encoding: bool - Use encoding flag
    - use_explicit_start: bool - Use explicit document start
    - use_explicit_end: bool - Use explicit document end
    - serialized_nodes: dict - Cache of serialized nodes
    - anchors: dict - Node to anchor mappings
    """
    
    def open(self):
        """Open serialization session."""
    
    def close(self):
        """Close serialization session."""
    
    def serialize(self, node):
        """Serialize node to events."""

class Emitter:
    """
    YAML emitter converting events to text output.
    
    Attributes:
    - canonical: bool - Produce canonical YAML
    - indent: int - Indentation level
    - width: int - Maximum line width
    - allow_unicode: bool - Allow unicode characters
    """
    
    def emit(self, event):
        """Emit event as YAML text."""
    
    def need_more_events(self) -> bool:
        """Check if more events are needed."""

Usage Examples

Custom Loader Construction

import yaml

# Create custom loader with specific components
class CustomLoader(
    yaml.Reader,
    yaml.Scanner, 
    yaml.Parser,
    yaml.Composer,
    yaml.SafeConstructor,  # Use safe constructor
    yaml.Resolver
):
    """Custom loader with safe construction and standard resolution."""
    
    def __init__(self, stream):
        yaml.Reader.__init__(self, stream)
        yaml.Scanner.__init__(self)
        yaml.Parser.__init__(self)
        yaml.Composer.__init__(self)
        yaml.SafeConstructor.__init__(self)
        yaml.Resolver.__init__(self)

# Use custom loader
yaml_input = """
name: Custom Test
values: [1, 2, 3]
enabled: true
"""

data = yaml.load(yaml_input, Loader=CustomLoader)
print(f"Loaded with custom loader: {data}")

Custom Dumper Construction

import yaml

# Create custom dumper with specific components
class CustomDumper(
    yaml.Emitter,
    yaml.Serializer,
    yaml.SafeRepresenter,  # Use safe representer
    yaml.Resolver
):
    """Custom dumper with safe representation and standard resolution."""
    
    def __init__(self, stream, **kwargs):
        yaml.Emitter.__init__(self, stream, **kwargs)
        yaml.Serializer.__init__(self, **kwargs)
        yaml.SafeRepresenter.__init__(self, **kwargs)
        yaml.Resolver.__init__(self)

# Use custom dumper
data = {
    'name': 'Custom Output',
    'items': ['a', 'b', 'c'],
    'count': 42
}

yaml_output = yaml.dump(data, Dumper=CustomDumper, indent=4)
print(f"Dumped with custom dumper:\n{yaml_output}")

Custom Constructor Integration

import yaml
from datetime import datetime

class DateTimeConstructor(yaml.SafeConstructor):
    """Constructor with custom datetime handling."""
    
    def __init__(self):
        super().__init__()
        self.add_constructor('!datetime', self.construct_datetime)
    
    def construct_datetime(self, node):
        """Construct datetime from ISO string."""
        value = self.construct_scalar(node)
        return datetime.fromisoformat(value)

class CustomLoaderWithDateTime(
    yaml.Reader,
    yaml.Scanner,
    yaml.Parser, 
    yaml.Composer,
    DateTimeConstructor,  # Use custom constructor
    yaml.Resolver
):
    """Loader with custom datetime construction."""
    
    def __init__(self, stream):
        yaml.Reader.__init__(self, stream)
        yaml.Scanner.__init__(self)
        yaml.Parser.__init__(self)
        yaml.Composer.__init__(self)
        DateTimeConstructor.__init__(self)
        yaml.Resolver.__init__(self)

# Test custom datetime construction
yaml_input = """
created: !datetime 2024-01-15T14:30:00
modified: !datetime 2024-01-16T09:15:30
name: Test Document
"""

data = yaml.load(yaml_input, Loader=CustomLoaderWithDateTime)
print(f"Created: {data['created']} (type: {type(data['created'])})")
print(f"Modified: {data['modified']} (type: {type(data['modified'])})")

Pipeline Component Inspection

import yaml

def inspect_processing_components():
    """Inspect the components used in standard loaders."""
    
    # Inspect SafeLoader components
    print("SafeLoader MRO:")
    for i, cls in enumerate(yaml.SafeLoader.__mro__):
        print(f"  {i}: {cls.__name__}")
    
    print("\nSafeDumper MRO:")
    for i, cls in enumerate(yaml.SafeDumper.__mro__):
        print(f"  {i}: {cls.__name__}")
    
    # Check constructor registry
    print(f"\nSafeConstructor has {len(yaml.SafeConstructor.yaml_constructors)} constructors")
    print("Sample constructors:")
    for tag, constructor in list(yaml.SafeConstructor.yaml_constructors.items())[:5]:
        print(f"  {tag}: {constructor.__name__}")
    
    # Check representer registry
    print(f"\nSafeRepresenter has {len(yaml.SafeRepresenter.yaml_representers)} representers")
    print("Sample representers:")
    for type_class, representer in list(yaml.SafeRepresenter.yaml_representers.items())[:5]:
        print(f"  {type_class}: {representer.__name__}")

inspect_processing_components()

Component Customization

import yaml

class LoggingConstructor(yaml.SafeConstructor):
    """Constructor that logs construction activity."""
    
    def construct_object(self, node, deep=False):
        print(f"Constructing {type(node).__name__} with tag {node.tag}")
        return super().construct_object(node, deep)

class LoggingRepresenter(yaml.SafeRepresenter):
    """Representer that logs representation activity."""
    
    def represent_data(self, data):
        print(f"Representing {type(data).__name__}: {data}")
        return super().represent_data(data)

class LoggingLoader(
    yaml.Reader,
    yaml.Scanner,
    yaml.Parser,
    yaml.Composer,
    LoggingConstructor,
    yaml.Resolver
):
    def __init__(self, stream):
        yaml.Reader.__init__(self, stream)
        yaml.Scanner.__init__(self)
        yaml.Parser.__init__(self)
        yaml.Composer.__init__(self)
        LoggingConstructor.__init__(self)
        yaml.Resolver.__init__(self)

class LoggingDumper(
    yaml.Emitter,
    yaml.Serializer,
    LoggingRepresenter,
    yaml.Resolver
):
    def __init__(self, stream, **kwargs):
        yaml.Emitter.__init__(self, stream, **kwargs)
        yaml.Serializer.__init__(self, **kwargs)
        LoggingRepresenter.__init__(self, **kwargs)
        yaml.Resolver.__init__(self)

# Test logging components
yaml_input = """
name: Logging Test
items:
  - value: 1
  - value: 2
enabled: true
"""

print("=== LOADING ===")
data = yaml.load(yaml_input, Loader=LoggingLoader)

print("\n=== DUMPING ===")
yaml_output = yaml.dump(data, Dumper=LoggingDumper)
print(f"\nFinal output:\n{yaml_output}")

Install with Tessl CLI