"""Type stubs for the yaml-edit native extension."""

from typing import Iterator, Optional, Union

ScalarValue = Union[str, int, float, bool]

class Node:
    """A YAML node returned from a getter."""

    @property
    def kind(self) -> str: ...
    def is_scalar(self) -> bool: ...
    def is_mapping(self) -> bool: ...
    def is_sequence(self) -> bool: ...
    def as_scalar(self) -> Optional[Scalar]: ...
    def as_mapping(self) -> Optional[Mapping]: ...
    def as_sequence(self) -> Optional[Sequence]: ...
    def as_int(self) -> Optional[int]: ...
    def as_float(self) -> Optional[float]: ...
    def as_bool(self) -> Optional[bool]: ...
    def __str__(self) -> str: ...

class Scalar:
    """A scalar YAML value (string, number, boolean)."""

    def value(self) -> str:
        """The raw scalar text, preserving any surrounding quotes."""

    def as_string(self) -> str:
        """The scalar's value with quotes stripped if present."""
    def is_quoted(self) -> bool: ...
    def unquoted_value(self) -> str: ...
    def is_null(self) -> bool: ...
    def as_int(self) -> Optional[int]: ...
    def as_float(self) -> Optional[float]: ...
    def as_bool(self) -> Optional[bool]: ...
    def set_value(self, value: str) -> None: ...
    def __str__(self) -> str: ...

class Entry:
    """A single key/value entry in a mapping.

    The fine-grained handle for mappings with repeated keys: each occurrence is
    a distinct entry that can be inspected and mutated individually.
    """

    def key(self) -> Optional[Node]: ...
    def value(self) -> Optional[Node]: ...
    def key_matches(self, key: str) -> bool: ...
    def set_value(self, value: ScalarValue) -> None: ...
    def remove(self) -> None: ...

class Mapping:
    """A YAML mapping (key/value block)."""

    def __len__(self) -> int: ...
    def is_empty(self) -> bool: ...
    def is_flow_style(self) -> bool: ...
    def contains_key(self, key: str) -> bool: ...
    def __contains__(self, key: str) -> bool: ...
    def get(self, key: str) -> Optional[Node]: ...
    def __getitem__(self, key: str) -> Node: ...
    def get_mapping(self, key: str) -> Optional[Mapping]: ...
    def get_sequence(self, key: str) -> Optional[Sequence]: ...
    def set(self, key: str, value: ScalarValue) -> None: ...
    def __setitem__(self, key: str, value: ScalarValue) -> None: ...
    def remove(self, key: str) -> bool: ...
    def __delitem__(self, key: str) -> None: ...
    def rename_key(self, old_key: str, new_key: str) -> bool: ...
    def clear(self) -> None: ...
    def keys(self) -> list[str]: ...
    def values(self) -> list[Node]: ...
    def items(self) -> list[tuple[str, Node]]: ...
    def __iter__(self) -> Iterator[str]: ...
    def entries(self) -> list[Entry]: ...
    def find_entry(self, key: str) -> Optional[Entry]: ...
    def find_all_entries(self, key: str) -> list[Entry]: ...
    def count_key(self, key: str) -> int: ...
    def remove_nth(self, key: str, n: int) -> bool: ...
    def __str__(self) -> str: ...

class MergedMapping:
    """A read-only mapping view with aliases and merge keys (``<<``) resolved.

    Has no ``__str__``: a merged view has no single source span, so read its
    resolved contents through ``items``/``get`` rather than ``str()``.
    """

    def __len__(self) -> int: ...
    def is_empty(self) -> bool: ...
    def contains_key(self, key: str) -> bool: ...
    def __contains__(self, key: str) -> bool: ...
    def get(self, key: str) -> Optional[Node]: ...
    def __getitem__(self, key: str) -> Node: ...
    def get_merged(self, key: str) -> Optional[MergedMapping]: ...
    def keys(self) -> list[str]: ...
    def values(self) -> list[Node]: ...
    def items(self) -> list[tuple[str, Node]]: ...
    def __iter__(self) -> Iterator[str]: ...

class Sequence:
    """A YAML sequence (list)."""

    def __len__(self) -> int: ...
    def is_empty(self) -> bool: ...
    def is_flow_style(self) -> bool: ...
    def get(self, index: int) -> Optional[Node]: ...
    def __getitem__(self, index: int) -> Node: ...
    def first(self) -> Optional[Node]: ...
    def last(self) -> Optional[Node]: ...
    def push(self, value: ScalarValue) -> None: ...
    def insert(self, index: int, value: ScalarValue) -> None: ...
    def set(self, index: int, value: ScalarValue) -> bool: ...
    def __setitem__(self, index: int, value: ScalarValue) -> None: ...
    def __delitem__(self, index: int) -> None: ...
    def remove(self, index: int) -> Optional[Node]: ...
    def pop(self) -> Optional[Node]: ...
    def clear(self) -> None: ...
    def values(self) -> list[Node]: ...
    def __iter__(self) -> Iterator[Node]: ...
    def __str__(self) -> str: ...

class Document:
    """A single YAML document."""

    def __init__(self) -> None: ...
    @staticmethod
    def parse(text: str) -> Document: ...
    @staticmethod
    def from_file(path: str) -> Document: ...
    def to_file(self, path: str) -> None: ...
    def is_empty(self) -> bool: ...
    def as_mapping(self) -> Optional[Mapping]: ...
    def as_sequence(self) -> Optional[Sequence]: ...
    def as_scalar(self) -> Optional[Scalar]: ...
    def merged(self) -> Optional[MergedMapping]: ...
    def contains_key(self, key: str) -> bool: ...
    def __contains__(self, key: str) -> bool: ...
    def get(self, key: str) -> Optional[Node]: ...
    def __getitem__(self, key: str) -> Node: ...
    def get_string(self, key: str) -> Optional[str]: ...
    def set(self, key: str, value: ScalarValue) -> None: ...
    def __setitem__(self, key: str, value: ScalarValue) -> None: ...
    def remove(self, key: str) -> bool: ...
    def __delitem__(self, key: str) -> None: ...
    def rename_key(self, old_key: str, new_key: str) -> bool: ...
    def keys(self) -> list[str]: ...
    def __str__(self) -> str: ...

class YamlFile:
    """A YAML stream, which may hold multiple documents and directives."""

    def __init__(self) -> None: ...
    @staticmethod
    def parse(text: str) -> YamlFile: ...
    @staticmethod
    def from_file(path: str) -> YamlFile: ...
    def __len__(self) -> int: ...
    def is_empty(self) -> bool: ...
    def documents(self) -> list[Document]: ...
    def document(self) -> Optional[Document]: ...
    def ensure_document(self) -> Document: ...
    def push_document(self, document: Document) -> None: ...
    def directives(self) -> list[str]: ...
    def add_directive(self, directive_text: str) -> None: ...
    def __str__(self) -> str: ...
