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

from dataclasses import dataclass
from typing import Any, Callable, Final, Generic, Literal, TypeVar
from typing_extensions import TypeAlias, TypeGuard

"""Functions and data structures shared by session_state.py and widgets.py."""
GENERATED_ELEMENT_ID_PREFIX: Final = ...
TESTING_KEY = ...
T = TypeVar("T")
T_co = TypeVar("T_co", covariant=True)
WidgetArgs: TypeAlias = tuple[Any, ...]
WidgetKwargs: TypeAlias = dict[str, Any]
WidgetCallback: TypeAlias = Callable[..., None]
WidgetDeserializer: TypeAlias = Callable[[Any, str], T]
WidgetSerializer: TypeAlias = Callable[[T], Any]
ArrayValueFieldName: TypeAlias = Literal["double_array_value", "int_array_value", "string_array_value",]
_ARRAY_VALUE_FIELD_NAMES: Final = ...
ValueFieldName: TypeAlias = Literal[ArrayValueFieldName, "arrow_value", "bool_value", "bytes_value", "double_value", "file_uploader_state_value", "int_value", "json_value", "string_value", "trigger_value", "string_trigger_value", "chat_input_value",]
def is_array_value_field_name(obj: object) -> TypeGuard[ArrayValueFieldName]:
    ...

@dataclass(frozen=True)
class WidgetMetadata(Generic[T]):
    """Metadata associated with a single widget. Immutable."""
    id: str
    deserializer: WidgetDeserializer[T] = ...
    serializer: WidgetSerializer[T] = ...
    value_type: ValueFieldName
    callback: WidgetCallback | None = ...
    callback_args: WidgetArgs | None = ...
    callback_kwargs: WidgetKwargs | None = ...
    fragment_id: str | None = ...
    def __repr__(self) -> str:
        ...
    


@dataclass(frozen=True)
class RegisterWidgetResult(Generic[T_co]):
    """Result returned by the `register_widget` family of functions/methods.

    Should be usable by widget code to determine what value to return, and
    whether to update the UI.

    Parameters
    ----------
    value : T_co
        The widget's current value, or, in cases where the true widget value
        could not be determined, an appropriate fallback value.

        This value should be returned by the widget call.
    value_changed : bool
        True if the widget's value is different from the value most recently
        returned from the frontend.

        Implies an update to the frontend is needed.
    """
    value: T_co
    value_changed: bool
    @classmethod
    def failure(cls, deserializer: WidgetDeserializer[T_co]) -> RegisterWidgetResult[T_co]:
        """The canonical way to construct a RegisterWidgetResult in cases
        where the true widget value could not be determined.
        """
        ...
    


def user_key_from_element_id(element_id: str) -> str | None:
    """Return the user key portion of a element id, or None if the id does not
    have a user key.

    TODO This will incorrectly indicate no user key if the user actually provides
    "None" as a key, but we can't avoid this kind of problem while storing the
    string representation of the no-user-key sentinel as part of the element id.
    """
    ...

def is_element_id(key: str) -> bool:
    """True if the given session_state key has the structure of a element ID."""
    ...

def is_keyed_element_id(key: str) -> bool:
    """True if the given session_state key has the structure of a element ID
    with a user_key.
    """
    ...

def require_valid_user_key(key: str) -> None:
    """Raise an Exception if the given user_key is invalid."""
    ...

