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

import numpy as np
from pandas._libs.tslibs import Timestamp
from pandas._libs.tslibs.offsets import BaseOffset
from pandas._typing import npt
from pandas.util._decorators import cache_readonly

_offset_to_period_map = ...
_need_suffix = ...
def get_period_alias(offset_str: str) -> str | None:
    """
    Alias to closest period strings BQ->Q etc.
    """
    ...

def get_offset(name: str) -> BaseOffset:
    """
    Return DateOffset object associated with rule name.

    .. deprecated:: 1.0.0

    Examples
    --------
    get_offset('EOM') --> BMonthEnd(1)
    """
    ...

def infer_freq(index, warn: bool = ...) -> str | None:
    """
    Infer the most likely frequency given the input index.

    Parameters
    ----------
    index : DatetimeIndex or TimedeltaIndex
      If passed a Series will use the values of the series (NOT THE INDEX).
    warn : bool, default True
      .. deprecated:: 1.5.0

    Returns
    -------
    str or None
        None if no discernible frequency.

    Raises
    ------
    TypeError
        If the index is not datetime-like.
    ValueError
        If there are fewer than three values.

    Examples
    --------
    >>> idx = pd.date_range(start='2020/12/01', end='2020/12/30', periods=30)
    >>> pd.infer_freq(idx)
    'D'
    """
    ...

class _FrequencyInferer:
    """
    Not sure if I can avoid the state machine here
    """
    def __init__(self, index, warn: bool = ...) -> None:
        ...
    
    @cache_readonly
    def deltas(self) -> npt.NDArray[np.int64]:
        ...
    
    @cache_readonly
    def deltas_asi8(self) -> npt.NDArray[np.int64]:
        ...
    
    @cache_readonly
    def is_unique(self) -> bool:
        ...
    
    @cache_readonly
    def is_unique_asi8(self) -> bool:
        ...
    
    def get_freq(self) -> str | None:
        """
        Find the appropriate frequency string to describe the inferred
        frequency of self.i8values

        Returns
        -------
        str or None
        """
        ...
    
    @cache_readonly
    def day_deltas(self) -> list[int]:
        ...
    
    @cache_readonly
    def hour_deltas(self) -> list[int]:
        ...
    
    @cache_readonly
    def fields(self) -> np.ndarray:
        ...
    
    @cache_readonly
    def rep_stamp(self) -> Timestamp:
        ...
    
    def month_position_check(self) -> str | None:
        ...
    
    @cache_readonly
    def mdiffs(self) -> npt.NDArray[np.int64]:
        ...
    
    @cache_readonly
    def ydiffs(self) -> npt.NDArray[np.int64]:
        ...
    


class _TimedeltaFrequencyInferer(_FrequencyInferer):
    ...


def is_subperiod(source, target) -> bool:
    """
    Returns True if downsampling is possible between source and target
    frequencies

    Parameters
    ----------
    source : str or DateOffset
        Frequency converting from
    target : str or DateOffset
        Frequency converting to

    Returns
    -------
    bool
    """
    ...

def is_superperiod(source, target) -> bool:
    """
    Returns True if upsampling is possible between source and target
    frequencies

    Parameters
    ----------
    source : str or DateOffset
        Frequency converting from
    target : str or DateOffset
        Frequency converting to

    Returns
    -------
    bool
    """
    ...

__all__ = ["Day", "get_offset", "get_period_alias", "infer_freq", "is_subperiod", "is_superperiod", "to_offset"]
