# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405

import builtins
import typing

__all__ = [
    "MetricRecorder",
    "Scope",
    "current_scope",
]

@typing.final
class MetricRecorder:
    r"""
    Metric recorder with type invariant enforcement.

    Accessed via `scope.metrics`. Supports:
    - `scope.metrics.record(key, value, mode="replace")` — full API
    - `scope.metrics.delete(key)` — delete (required before type change)
    - `scope.metrics[key] = value` — dict-style set (replace mode)
    - `del scope.metrics[key]` — dict-style delete
    """
    def record(
        self,
        key: builtins.str,
        value: typing.Any,
        mode: typing.Optional[builtins.str] = None,
    ) -> None:
        r"""
        Record a metric value.

        Args:
            key: Metric name. Dot-separated keys (e.g. "timing.preprocess") create
                nested objects in the response.
            value: Must be bool, int, float, str, list, or dict. Once a key is set
                with a type, it cannot be changed without calling delete() first.
            mode: Accumulation mode — "replace" (default), "incr" (increment numeric),
                or "append" (push to array).
        """
    def delete(self, key: builtins.str) -> None:
        r"""
        Delete a metric key. Required before changing a metric's type.
        """
    def __setitem__(self, key: builtins.str, value: typing.Any) -> None:
        r"""
        Dict-style set: `scope.metrics["key"] = value`
        """
    def __delitem__(self, key: builtins.str) -> None:
        r"""
        Dict-style delete: `del scope.metrics["key"]`
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class Scope:
    r"""
    Prediction scope, obtained via `current_scope()`.

    Provides access to `scope.metrics` for recording metrics, and
    `scope.record_metric()` as a convenience shorthand.
    """
    @property
    def metrics(self) -> MetricRecorder:
        r"""
        The metric recorder for this prediction.
        """
    @property
    def context(self) -> dict[builtins.str, builtins.str]:
        r"""
        Per-prediction context passed in the request body.

        Returns a `dict[str, str]` (empty dict if no context was provided).
        """
    def record_metric(
        self,
        key: builtins.str,
        value: typing.Any,
        mode: typing.Optional[builtins.str] = None,
    ) -> None:
        r"""
        Convenience: record a metric value.

        Equivalent to `scope.metrics.record(key, value, mode)`.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class _SlotLogWriter:
    r"""
    A Python file-like object that routes writes via the prediction_id ContextVar.

    This is installed as sys.stdout/stderr once at worker startup.
    Each write looks up the current prediction_id from the ContextVar and routes
    to the appropriate SlotSender.

    If no prediction_id is set, or the prediction has completed (orphan task),
    writes go to tracing (logged as orphan).

    Uses line buffering: accumulates writes until a newline is received, then
    emits complete lines. This coalesces Python's print() which does separate
    writes for content and newline.
    """
    @property
    def closed(self) -> builtins.bool:
        r"""
        Whether writes should be ignored (used after errors).
        """
    @property
    def encoding(self) -> typing.Optional[builtins.str]:
        r"""
        Encoding property - needed for compatibility.
        """
    @property
    def newlines(self) -> typing.Optional[builtins.str]:
        r"""
        Newlines property - needed for compatibility.
        """
    @property
    def buffer(self) -> typing.Any:
        r"""
        Buffer property - some code checks for this.
        """
    def write(self, data: builtins.str) -> builtins.int:
        r"""
        Write data, routing to the appropriate destination.

        Uses line buffering: accumulates data until a newline is received, then
        emits complete lines. This coalesces Python's print() which does separate
        writes for content and the trailing newline.

        Priority for routing:
        1. If inside a prediction (ContextVar set), route to slot sender
        2. If setup sender registered, route to control channel
        3. Fall back to stderr (for orphan tasks or unexpected cases)
        """
    def emit_data(self, data: builtins.str) -> None:
        r"""
        Emit data to the appropriate destination.
        """
    def flush(self) -> None:
        r"""
        Flush the stream.

        Emits any buffered content that hasn't been terminated with a newline.
        """
    def readable(self) -> builtins.bool:
        r"""
        Return whether the stream is readable.
        """
    def writable(self) -> builtins.bool:
        r"""
        Return whether the stream is writable.
        """
    def seekable(self) -> builtins.bool:
        r"""
        Return whether the stream is seekable.
        """
    def isatty(self) -> builtins.bool:
        r"""
        Return whether the stream is a TTY.
        """
    def fileno(self) -> builtins.int:
        r"""
        Return the file number.
        """
    def close(self) -> None:
        r"""
        Close the stream.
        """
    def __enter__(self) -> _SlotLogWriter:
        r"""
        Context manager enter.
        """
    def __exit__(
        self,
        _exc_type: typing.Optional[typing.Any],
        _exc_val: typing.Optional[typing.Any],
        _exc_tb: typing.Optional[typing.Any],
    ) -> builtins.bool:
        r"""
        Context manager exit.
        """

@typing.final
class _TeeWriter:
    r"""
    Tee writer that sends writes to both our slot routing and user's stream.

    - inner: Our _SlotLogWriter for slot-based log routing
    - user_stream: The stream user code tried to install
    """
    @property
    def inner(self) -> typing.Any:
        r"""
        Our _SlotLogWriter (does ContextVar-based routing)
        """
    @property
    def user_stream(self) -> typing.Any:
        r"""
        User's replacement stream
        """
    @property
    def name(self) -> builtins.str:
        r"""
        Stream name (stdout or stderr)
        """
    @property
    def closed(self) -> builtins.bool:
        r"""
        Closed flag
        """
    @property
    def encoding(self) -> typing.Optional[builtins.str]: ...
    @property
    def newlines(self) -> typing.Optional[builtins.str]: ...
    def __new__(
        cls, inner: typing.Any, user_stream: typing.Any, name: builtins.str
    ) -> _TeeWriter: ...
    def write(self, data: builtins.str) -> builtins.int:
        r"""
        Write to both streams.
        """
    def flush(self) -> None:
        r"""
        Flush both streams.
        """
    def readable(self) -> builtins.bool: ...
    def writable(self) -> builtins.bool: ...
    def seekable(self) -> builtins.bool: ...
    def isatty(self) -> builtins.bool: ...
    def fileno(self) -> builtins.int: ...
    def close(self) -> None: ...
    def __enter__(self) -> _TeeWriter: ...
    def __exit__(
        self,
        _exc_type: typing.Optional[typing.Any],
        _exc_val: typing.Optional[typing.Any],
        _exc_tb: typing.Optional[typing.Any],
    ) -> builtins.bool: ...

def current_scope() -> Scope:
    r"""
    Python-callable: get the current Scope.

    Returns the active scope if inside a prediction, or a no-op scope otherwise.
    """
