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

import numpy as np
import pyarrow as pa
from typing import Any, TYPE_CHECKING, TypeVar
from pandas._libs import lib
from pandas._typing import Dtype, PositionalIndexer, TakeIndexer, npt
from pandas.compat import pa_version_under1p01
from pandas.util._decorators import deprecate_nonkeyword_arguments, doc
from pandas.core.arraylike import OpsMixin
from pandas.core.arrays.base import ExtensionArray
from pandas.core.arrays.arrow.dtype import ArrowDtype
from pandas import Series

if notpa_version_under1p01:
    ARROW_CMP_FUNCS = ...
    ARROW_LOGICAL_FUNCS = ...
    def cast_for_truediv(arrow_array: pa.ChunkedArray, pa_object: pa.Array | pa.Scalar) -> pa.ChunkedArray:
        ...
    
    def floordiv_compat(left: pa.ChunkedArray | pa.Array | pa.Scalar, right: pa.ChunkedArray | pa.Array | pa.Scalar) -> pa.ChunkedArray:
        ...
    
    ARROW_ARITHMETIC_FUNCS = ...
if TYPE_CHECKING:
    ...
ArrowExtensionArrayT = TypeVar("ArrowExtensionArrayT", bound="ArrowExtensionArray")
def to_pyarrow_type(dtype: ArrowDtype | pa.DataType | Dtype | None) -> pa.DataType | None:
    """
    Convert dtype to a pyarrow type instance.
    """
    ...

class ArrowExtensionArray(OpsMixin, ExtensionArray):
    """
    Pandas ExtensionArray backed by a PyArrow ChunkedArray.

    .. warning::

       ArrowExtensionArray is considered experimental. The implementation and
       parts of the API may change without warning.

    Parameters
    ----------
    values : pyarrow.Array or pyarrow.ChunkedArray

    Attributes
    ----------
    None

    Methods
    -------
    None

    Returns
    -------
    ArrowExtensionArray

    Notes
    -----
    Most methods are implemented using `pyarrow compute functions. <https://arrow.apache.org/docs/python/api/compute.html>`__
    Some methods may either raise an exception or raise a ``PerformanceWarning`` if an
    associated compute function is not available based on the installed version of PyArrow.

    Please install the latest version of PyArrow to enable the best functionality and avoid
    potential bugs in prior versions of PyArrow.

    Examples
    --------
    Create an ArrowExtensionArray with :func:`pandas.array`:

    >>> pd.array([1, 1, None], dtype="int64[pyarrow]")
    <ArrowExtensionArray>
    [1, 1, <NA>]
    Length: 3, dtype: int64[pyarrow]
    """
    _data: pa.ChunkedArray
    _dtype: ArrowDtype
    def __init__(self, values: pa.Array | pa.ChunkedArray) -> None:
        ...
    
    def __getitem__(self, item: PositionalIndexer): # -> Self@ArrowExtensionArray | ArrowExtensionArray | NAType:
        """Select a subset of self.

        Parameters
        ----------
        item : int, slice, or ndarray
            * int: The position in 'self' to get.
            * slice: A slice object, where 'start', 'stop', and 'step' are
              integers or None
            * ndarray: A 1-d boolean NumPy ndarray the same length as 'self'

        Returns
        -------
        item : scalar or ExtensionArray

        Notes
        -----
        For scalar ``item``, return a scalar value suitable for the array's
        type. This should be an instance of ``self.dtype.type``.
        For slice ``key``, return an instance of ``ExtensionArray``, even
        if the slice is length 0 or 1.
        For a boolean mask, return an instance of ``ExtensionArray``, filtered
        to the values where ``item`` is True.
        """
        ...
    
    def __arrow_array__(self, type=...):
        """Convert myself to a pyarrow ChunkedArray."""
        ...
    
    def __invert__(self: ArrowExtensionArrayT) -> ArrowExtensionArrayT:
        ...
    
    def __neg__(self: ArrowExtensionArrayT) -> ArrowExtensionArrayT:
        ...
    
    def __pos__(self: ArrowExtensionArrayT) -> ArrowExtensionArrayT:
        ...
    
    def __abs__(self: ArrowExtensionArrayT) -> ArrowExtensionArrayT:
        ...
    
    def equals(self, other) -> bool:
        ...
    
    @property
    def dtype(self) -> ArrowDtype:
        """
        An instance of 'ExtensionDtype'.
        """
        ...
    
    @property
    def nbytes(self) -> int:
        """
        The number of bytes needed to store this object in memory.
        """
        ...
    
    def __len__(self) -> int:
        """
        Length of this array.

        Returns
        -------
        length : int
        """
        ...
    
    def isna(self) -> npt.NDArray[np.bool_]:
        """
        Boolean NumPy array indicating if each value is missing.

        This should return a 1-D array the same length as 'self'.
        """
        ...
    
    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self"])
    def argsort(self, ascending: bool = ..., kind: str = ..., na_position: str = ..., *args, **kwargs) -> np.ndarray:
        ...
    
    def argmin(self, skipna: bool = ...) -> int:
        ...
    
    def argmax(self, skipna: bool = ...) -> int:
        ...
    
    def copy(self: ArrowExtensionArrayT) -> ArrowExtensionArrayT:
        """
        Return a shallow copy of the array.

        Underlying ChunkedArray is immutable, so a deep copy is unnecessary.

        Returns
        -------
        type(self)
        """
        ...
    
    def dropna(self: ArrowExtensionArrayT) -> ArrowExtensionArrayT:
        """
        Return ArrowExtensionArray without NA values.

        Returns
        -------
        ArrowExtensionArray
        """
        ...
    
    def isin(self, values) -> npt.NDArray[np.bool_]:
        ...
    
    @doc(ExtensionArray.factorize)
    def factorize(self, na_sentinel: int | lib.NoDefault = ..., use_na_sentinel: bool | lib.NoDefault = ...) -> tuple[np.ndarray, ExtensionArray]:
        ...
    
    def reshape(self, *args, **kwargs):
        ...
    
    def take(self, indices: TakeIndexer, allow_fill: bool = ..., fill_value: Any = ...) -> ArrowExtensionArray:
        """
        Take elements from an array.

        Parameters
        ----------
        indices : sequence of int or one-dimensional np.ndarray of int
            Indices to be taken.
        allow_fill : bool, default False
            How to handle negative values in `indices`.

            * False: negative values in `indices` indicate positional indices
              from the right (the default). This is similar to
              :func:`numpy.take`.

            * True: negative values in `indices` indicate
              missing values. These values are set to `fill_value`. Any other
              other negative values raise a ``ValueError``.

        fill_value : any, optional
            Fill value to use for NA-indices when `allow_fill` is True.
            This may be ``None``, in which case the default NA value for
            the type, ``self.dtype.na_value``, is used.

            For many ExtensionArrays, there will be two representations of
            `fill_value`: a user-facing "boxed" scalar, and a low-level
            physical NA value. `fill_value` should be the user-facing version,
            and the implementation should handle translating that to the
            physical version for processing the take if necessary.

        Returns
        -------
        ExtensionArray

        Raises
        ------
        IndexError
            When the indices are out of bounds for the array.
        ValueError
            When `indices` contains negative values other than ``-1``
            and `allow_fill` is True.

        See Also
        --------
        numpy.take
        api.extensions.take

        Notes
        -----
        ExtensionArray.take is called by ``Series.__getitem__``, ``.loc``,
        ``iloc``, when `indices` is a sequence of values. Additionally,
        it's called by :meth:`Series.reindex`, or any other method
        that causes realignment, with a `fill_value`.
        """
        ...
    
    def unique(self: ArrowExtensionArrayT) -> ArrowExtensionArrayT:
        """
        Compute the ArrowExtensionArray of unique values.

        Returns
        -------
        ArrowExtensionArray
        """
        ...
    
    def value_counts(self, dropna: bool = ...) -> Series:
        """
        Return a Series containing counts of each unique value.

        Parameters
        ----------
        dropna : bool, default True
            Don't include counts of missing values.

        Returns
        -------
        counts : Series

        See Also
        --------
        Series.value_counts
        """
        ...
    
    def __setitem__(self, key: int | slice | np.ndarray, value: Any) -> None:
        """Set one or more values inplace.

        Parameters
        ----------
        key : int, ndarray, or slice
            When called from, e.g. ``Series.__setitem__``, ``key`` will be
            one of

            * scalar int
            * ndarray of integers.
            * boolean ndarray
            * slice object

        value : ExtensionDtype.type, Sequence[ExtensionDtype.type], or object
            value or values to be set of ``key``.

        Returns
        -------
        None
        """
        ...
    


