"""
This type stub file was generated by pyright.
"""

import io
from typing import Iterable, TYPE_CHECKING
from .default_handlers import BaseHandler

"""
Python Frontmatter: Parse and manage posts with YAML frontmatter
"""
if TYPE_CHECKING: ...
__all__ = ["parse", "load", "loads", "dump", "dumps"]
handlers = ...

def detect_format(text: str, handlers: Iterable[BaseHandler]) -> BaseHandler | None:
    """
    Figure out which handler to use, based on metadata.
    Returns a handler instance or None.

    ``text`` should be unicode text about to be parsed.

    ``handlers`` is a dictionary where keys are opening delimiters
    and values are handler instances.
    """
    ...

def parse(
    text: str,
    encoding: str = ...,
    handler: BaseHandler | None = ...,
    **defaults: object,
) -> tuple[dict[str, object], str]:
    """
    Parse text with frontmatter, return metadata and content.
    Pass in optional metadata defaults as keyword args.

    If frontmatter is not found, returns an empty metadata dictionary
    (or defaults) and original text content.

    .. testsetup:: *

        >>> import frontmatter

    .. doctest::

        >>> with open('tests/yaml/hello-world.txt') as f:
        ...     metadata, content = frontmatter.parse(f.read())
        >>> print(metadata['title'])
        Hello, world!

    """
    ...

def check(fd: str | io.IOBase, encoding: str = ...) -> bool:
    """
    Check if a file-like object or filename has a frontmatter,
    return True if exists, False otherwise.

    If it contains a frontmatter but it is empty, return True as well.

    .. doctest::

        >>> frontmatter.check('tests/yaml/hello-world.txt')
        True

    """
    ...

def checks(text: str, encoding: str = ...) -> bool:
    """
    Check if a text (binary or unicode) has a frontmatter,
    return True if exists, False otherwise.

    If it contains a frontmatter but it is empty, return True as well.

    .. doctest::

        >>> with open('tests/yaml/hello-world.txt') as f:
        ...     frontmatter.checks(f.read())
        True

    """
    ...

def load(
    fd: str | io.IOBase,
    encoding: str = ...,
    handler: BaseHandler | None = ...,
    **defaults: object,
) -> Post:
    """
    Load and parse a file-like object or filename,
    return a :py:class:`post <frontmatter.Post>`.

    .. doctest::

        >>> post = frontmatter.load('tests/yaml/hello-world.txt')
        >>> with open('tests/yaml/hello-world.txt') as f:
        ...     post = frontmatter.load(f)

    """
    ...

def loads(
    text: str,
    encoding: str = ...,
    handler: BaseHandler | None = ...,
    **defaults: object,
) -> Post:
    """
    Parse text (binary or unicode) and return a :py:class:`post <frontmatter.Post>`.

    .. doctest::

        >>> with open('tests/yaml/hello-world.txt') as f:
        ...     post = frontmatter.loads(f.read())

    """
    ...

def dump(
    post: Post,
    fd: str | io.IOBase,
    encoding: str = ...,
    handler: BaseHandler | None = ...,
    **kwargs: object,
) -> None:
    """
    Serialize :py:class:`post <frontmatter.Post>` to a string and write to a file-like object.
    Text will be encoded on the way out (utf-8 by default).

    ::

        >>> from io import BytesIO
        >>> post = frontmatter.load('tests/yaml/hello-world.txt')
        >>> f = BytesIO()
        >>> frontmatter.dump(post, f)
        >>> print(f.getvalue().decode('utf-8'))
        ---
        layout: post
        title: Hello, world!
        ---
        <BLANKLINE>
        Well, hello there, world.


    .. testcode::

        from io import BytesIO
        post = frontmatter.load('tests/yaml/hello-world.txt')
        f = BytesIO()
        frontmatter.dump(post, f)
        print(f.getvalue().decode('utf-8'))

    .. testoutput::

        ---
        layout: post
        title: Hello, world!
        ---
        <BLANKLINE>
        Well, hello there, world.

    """
    ...

def dumps(post: Post, handler: BaseHandler | None = ..., **kwargs: object) -> str:
    """
    Serialize a :py:class:`post <frontmatter.Post>` to a string and return text.
    This always returns unicode text, which can then be encoded.

    Passing ``handler`` will change how metadata is turned into text. A handler
    passed as an argument will override ``post.handler``, with
    :py:class:`YAMLHandler <frontmatter.default_handlers.YAMLHandler>` used as
    a default.

    ::

        >>> post = frontmatter.load('tests/yaml/hello-world.txt')
        >>> print(frontmatter.dumps(post)) # doctest: +NORMALIZE_WHITESPACE
        ---
        layout: post
        title: Hello, world!
        ---
        <BLANKLINE>
        Well, hello there, world.

    .. testcode::

        post = frontmatter.load('tests/yaml/hello-world.txt')
        print(frontmatter.dumps(post))

    .. testoutput::

        ---
        layout: post
        title: Hello, world!
        ---

        Well, hello there, world.

    """
    ...

class Post:
    """
    A post contains content and metadata from Front Matter. This is what gets
    returned by :py:func:`load <frontmatter.load>` and :py:func:`loads <frontmatter.loads>`.
    Passing this to :py:func:`dump <frontmatter.dump>` or :py:func:`dumps <frontmatter.dumps>`
    will turn it back into text.

    For convenience, metadata values are available as proxied item lookups.
    """
    def __init__(
        self, content: str, handler: BaseHandler | None = ..., **metadata: object
    ) -> None: ...
    def __getitem__(self, name: str) -> object:
        "Get metadata key"
        ...

    def __contains__(self, item: object) -> bool:
        "Check metadata contains key"
        ...

    def __setitem__(self, name: str, value: object) -> None:
        "Set a metadata key"
        ...

    def __delitem__(self, name: str) -> None:
        "Delete a metadata key"
        ...

    def __bytes__(self) -> bytes: ...
    def __str__(self) -> str: ...
    def get(self, key: str, default: object = ...) -> object:
        "Get a key, fallback to default"
        ...

    def keys(self) -> Iterable[str]:
        "Return metadata keys"
        ...

    def values(self) -> Iterable[object]:
        "Return metadata values"
        ...

    def to_dict(self) -> dict[str, object]:
        "Post as a dict, for serializing"
        ...
