"""JSON-lines logging, and a request id that follows the request — not the process."""

import contextvars  # noqa: F401  — you need it for the request id
import json  # noqa: F401
import logging
import sys  # noqa: F401
from collections.abc import Iterator
from contextlib import contextmanager
from datetime import UTC, datetime  # noqa: F401

# TODO: the request id's storage. It must hold ONE value per thread / asyncio task — two
# requests in flight at the same time must never see each other's id. Outside any request,
# reading it gives "-".


@contextmanager
def request_scope(request_id: str) -> Iterator[None]:
    """Every line logged inside the with-block carries ``request_id`` — in this thread/task only.

    On exit the previous value is restored, even when the block raises.
    """
    ...


def current_request_id() -> str:
    """The id of the request this thread/task is serving, or ``"-"`` outside any request."""
    ...


class JsonFormatter(logging.Formatter):
    """One JSON object per record, on one line: ts, level, logger, msg, request_id.

    ``ts`` is the record's creation time in UTC, ISO 8601 with milliseconds
    (``2026-09-10T18:40:00.123+00:00``); ``msg`` is the message with its %-args filled in.
    """

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


# Provided: the line format when --json is NOT given.
TEXT_FORMAT = "%(levelname)s %(name)s: %(message)s"


def configure_logging(*, json_lines: bool, level: str) -> logging.Logger:
    """Point the ``askcli`` logger at stderr — JSON lines or plain text — at ``level``.

    Idempotent: calling it twice leaves ONE handler, not two. Set ``propagate = False`` so the
    root logger's handlers cannot print each line a second time, and look ``sys.stderr`` up
    inside this call (pytest's capsys replaces it per test).
    """
    ...