from __future__ import annotations  # pragma: no cover

from typing import (
    TYPE_CHECKING,  # pragma: no cover
    Any,  # pragma: no cover
    TypeVar,  # pragma: no cover
)

if TYPE_CHECKING:
    from typing import Generic, Literal, TypeAlias

    import pyarrow as pa
    from pyarrow.__lib_pxi.table import (
        AggregateOptions,  # noqa: F401
        Aggregation,  # noqa: F401
    )
    from pyarrow._stubs_typing import (  # pyright: ignore[reportMissingModuleSource]  # pyright: ignore[reportMissingModuleSource]  # pyright: ignore[reportMissingModuleSource]
        Indices,
        Mask,  # noqa: F401
        Order,  # noqa: F401
    )

    from narwhals._arrow.expr import ArrowExpr
    from narwhals._arrow.series import ArrowSeries

    IntoArrowExpr: TypeAlias = "ArrowExpr | ArrowSeries"
    TieBreaker: TypeAlias = Literal["min", "max", "first", "dense"]
    NullPlacement: TypeAlias = Literal["at_start", "at_end"]
    NativeIntervalUnit: TypeAlias = Literal[
        "year",
        "quarter",
        "month",
        "week",
        "day",
        "hour",
        "minute",
        "second",
        "millisecond",
        "microsecond",
        "nanosecond",
    ]
    PromoteOptions: TypeAlias = Literal["none", "default", "permissive"]

    ChunkedArrayAny: TypeAlias = pa.ChunkedArray[Any]
    ArrayAny: TypeAlias = pa.Array[Any]
    ArrayOrChunkedArray: TypeAlias = "ArrayAny | ChunkedArrayAny"
    ScalarAny: TypeAlias = pa.Scalar[Any]
    ArrayOrScalar: TypeAlias = "ArrayOrChunkedArray | ScalarAny"

    class DictionaryArrayAny(pa.Array[Any]):
        """`pa.DictionaryArray`, declaring the attributes the stubs are missing.

        https://arrow.apache.org/docs/python/generated/pyarrow.DictionaryArray.html
        """

        @property
        def dictionary(self) -> ArrayAny: ...
        @property
        def indices(self) -> Indices: ...

    ArrayOrScalarT1 = TypeVar("ArrayOrScalarT1", ArrayAny, ChunkedArrayAny, ScalarAny)
    ArrayOrScalarT2 = TypeVar("ArrayOrScalarT2", ArrayAny, ChunkedArrayAny, ScalarAny)
    _AsPyType = TypeVar("_AsPyType")

    class _BasicDataType(pa.DataType, Generic[_AsPyType]): ...


Incomplete: TypeAlias = Any  # pragma: no cover
"""
Marker for working code that fails on the stubs.

Common issues:
- Annotated for `Array`, but not `ChunkedArray`
- Relies on typing information that the stubs don't provide statically
- Missing attributes
- Incorrect return types
- Inconsistent use of generic/concrete types
- `_clone_signature` used on signatures that are not identical
"""
