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

import logging
import logging.handlers
from collections import defaultdict
from contextlib import contextmanager
from typing import Any, IO, TYPE_CHECKING
from collections.abc import Generator
from docutils.nodes import Node
from sphinx.application import Sphinx

"""Logging utility functions for Sphinx."""
if TYPE_CHECKING:
    ...
NAMESPACE = ...
VERBOSE = ...
LEVEL_NAMES: defaultdict[str, int] = ...
VERBOSITY_MAP: defaultdict[int, int] = ...
COLOR_MAP: defaultdict[int, str] = ...
def getLogger(name: str) -> SphinxLoggerAdapter:
    """Get logger wrapped by :class:`sphinx.util.logging.SphinxLoggerAdapter`.

    Sphinx logger always uses ``sphinx.*`` namespace to be independent from
    settings of root logger.  It ensures logging is consistent even if a
    third-party extension or imported application resets logger settings.

    Example usage::

        >>> from sphinx.util import logging
        >>> logger = logging.getLogger(__name__)
        >>> logger.info('Hello, this is an extension!')
        Hello, this is an extension!
    """
    ...

def convert_serializable(records: list[logging.LogRecord]) -> None:
    """Convert LogRecord serializable."""
    ...

class SphinxLogRecord(logging.LogRecord):
    """Log record class supporting location"""
    prefix = ...
    location: Any = ...
    def getMessage(self) -> str:
        ...
    


class SphinxInfoLogRecord(SphinxLogRecord):
    """Info log record class supporting location"""
    prefix = ...


class SphinxWarningLogRecord(SphinxLogRecord):
    """Warning log record class supporting location"""
    @property
    def prefix(self) -> str:
        ...
    


class SphinxLoggerAdapter(logging.LoggerAdapter):
    """LoggerAdapter allowing ``type`` and ``subtype`` keywords."""
    KEYWORDS = ...
    logger: logging.Logger
    def log(self, level: int | str, msg: str, *args: Any, **kwargs: Any) -> None:
        ...
    
    def verbose(self, msg: str, *args: Any, **kwargs: Any) -> None:
        ...
    
    def process(self, msg: str, kwargs: dict) -> tuple[str, dict]:
        ...
    
    def handle(self, record: logging.LogRecord) -> None:
        ...
    


class WarningStreamHandler(logging.StreamHandler):
    """StreamHandler for warnings."""
    ...


class NewLineStreamHandler(logging.StreamHandler):
    """StreamHandler which switches line terminator by record.nonl flag."""
    def emit(self, record: logging.LogRecord) -> None:
        ...
    


class MemoryHandler(logging.handlers.BufferingHandler):
    """Handler buffering all logs."""
    buffer: list[logging.LogRecord]
    def __init__(self) -> None:
        ...
    
    def shouldFlush(self, record: logging.LogRecord) -> bool:
        ...
    
    def flush(self) -> None:
        ...
    
    def flushTo(self, logger: logging.Logger) -> None:
        ...
    
    def clear(self) -> list[logging.LogRecord]:
        ...
    


@contextmanager
def pending_warnings() -> Generator[logging.Handler, None, None]:
    """Context manager to postpone logging warnings temporarily.

    Similar to :func:`pending_logging`.
    """
    ...

@contextmanager
def suppress_logging() -> Generator[MemoryHandler, None, None]:
    """Context manager to suppress logging all logs temporarily.

    For example::

        >>> with suppress_logging():
        >>>     logger.warning('Warning message!')  # suppressed
        >>>     some_long_process()
        >>>
    """
    ...

@contextmanager
def pending_logging() -> Generator[MemoryHandler, None, None]:
    """Context manager to postpone logging all logs temporarily.

    For example::

        >>> with pending_logging():
        >>>     logger.warning('Warning message!')  # not flushed yet
        >>>     some_long_process()
        >>>
        Warning message!  # the warning is flushed here
    """
    ...

@contextmanager
def skip_warningiserror(skip: bool = ...) -> Generator[None, None, None]:
    """Context manager to skip WarningIsErrorFilter temporarily."""
    ...

@contextmanager
def prefixed_warnings(prefix: str) -> Generator[None, None, None]:
    """Context manager to prepend prefix to all warning log records temporarily.

    For example::

        >>> with prefixed_warnings("prefix:"):
        >>>     logger.warning('Warning message!')  # => prefix: Warning message!

    .. versionadded:: 2.0
    """
    ...

class LogCollector:
    def __init__(self) -> None:
        ...
    
    @contextmanager
    def collect(self) -> Generator[None, None, None]:
        ...
    


class InfoFilter(logging.Filter):
    """Filter error and warning messages."""
    def filter(self, record: logging.LogRecord) -> bool:
        ...
    


def is_suppressed_warning(type: str, subtype: str, suppress_warnings: list[str]) -> bool:
    """Check whether the warning is suppressed or not."""
    ...

class WarningSuppressor(logging.Filter):
    """Filter logs by `suppress_warnings`."""
    def __init__(self, app: Sphinx) -> None:
        ...
    
    def filter(self, record: logging.LogRecord) -> bool:
        ...
    


class WarningIsErrorFilter(logging.Filter):
    """Raise exception if warning emitted."""
    def __init__(self, app: Sphinx) -> None:
        ...
    
    def filter(self, record: logging.LogRecord) -> bool:
        ...
    


class DisableWarningIsErrorFilter(logging.Filter):
    """Disable WarningIsErrorFilter if this filter installed."""
    def filter(self, record: logging.LogRecord) -> bool:
        ...
    


class MessagePrefixFilter(logging.Filter):
    """Prepend prefix to all log records."""
    def __init__(self, prefix: str) -> None:
        ...
    
    def filter(self, record: logging.LogRecord) -> bool:
        ...
    


class OnceFilter(logging.Filter):
    """Show the message only once."""
    def __init__(self, name: str = ...) -> None:
        ...
    
    def filter(self, record: logging.LogRecord) -> bool:
        ...
    


class SphinxLogRecordTranslator(logging.Filter):
    """Converts a log record to one Sphinx expects

    * Make a instance of SphinxLogRecord
    * docname to path if location given
    """
    LogRecordClass: type[logging.LogRecord]
    def __init__(self, app: Sphinx) -> None:
        ...
    
    def filter(self, record: SphinxWarningLogRecord) -> bool:
        ...
    


class InfoLogRecordTranslator(SphinxLogRecordTranslator):
    """LogRecordTranslator for INFO level log records."""
    LogRecordClass = SphinxInfoLogRecord


class WarningLogRecordTranslator(SphinxLogRecordTranslator):
    """LogRecordTranslator for WARNING level log records."""
    LogRecordClass = SphinxWarningLogRecord


def get_node_location(node: Node) -> str | None:
    ...

class ColorizeFormatter(logging.Formatter):
    def format(self, record: logging.LogRecord) -> str:
        ...
    


class SafeEncodingWriter:
    """Stream writer which ignores UnicodeEncodeError silently"""
    def __init__(self, stream: IO) -> None:
        ...
    
    def write(self, data: str) -> None:
        ...
    
    def flush(self) -> None:
        ...
    


class LastMessagesWriter:
    """Stream writer storing last 10 messages in memory to save trackback"""
    def __init__(self, app: Sphinx, stream: IO) -> None:
        ...
    
    def write(self, data: str) -> None:
        ...
    


def setup(app: Sphinx, status: IO, warning: IO) -> None:
    """Setup root logger for Sphinx"""
    ...

