
    Eg                       d dl mZ d dlmZ d dlZd dlmZmZmZm	Z	m
Z
mZmZ d dlZd dlZd dlmZmZ d dlmZ d dlmZmZmZmZmZmZmZmZm Z m!Z!m"Z#m$Z$ d dl%m&Z&m'Z'm(Z( d d	l)m*Z* d d
l+m,Z,m-Z- d dl.m/Z/m0Z0m1Z1m2Z2m3Z3 d dl4m5Z5m6Z6 d dl7m8Z8 d dl9m:Z:m;Z; d dl<m=Z=m>Z> d dl?m@Z@mAZAmBZBmCZC d dlDmEZE d dlFmGZH d dlImJc mKZL er(d dlMmNZN d dlOmPZPmQZQmRZRmSZSmTZTmUZUmVZVmWZW d dlFmXZXmYZY d dlZm[Z[  e
de          Z\ddiZ]d<d=dZ^ G d  deHj_        e#j`                  Zad>d#Zb	 	 d?d@d+ZcedAd,            ZdedBd/            ZddCd1Zd	 d<dDd3ZdEdFd7Ze	 	 	 	 	 	 	 	 dGdHd9ZfdId;ZgdS )J    )annotations)	timedeltaN)TYPE_CHECKINGAnyCallableLiteralTypeVarcastoverload)algoslib)NDArrayBacked)
BaseOffsetNaTNaTType	Timedeltaadd_overflowsafeastype_overflowsafedt64arr_to_periodarrget_unit_from_dtypeiNaTparsingperiod	to_offset)	FreqGroupPeriodDtypeBasefreq_to_period_freqstr)isleapyear_arr)Tickdelta_to_tick)DIFFERENT_FREQIncompatibleFrequencyPeriodget_period_field_arrperiod_asfreq_arr)cache_readonlydoc)find_stack_level)ensure_objectpandas_dtype)DatetimeTZDtypePeriodDtype)ABCIndexABCPeriodIndex	ABCSeriesABCTimedeltaArray)isna)datetimelike)Sequence)AnyArrayLikeDtypeFillnaOptionsNpDtypeNumpySorterNumpyValueArrayLikeSelfnpt)DatetimeArrayTimedeltaArray)ExtensionArrayBaseOffsetT)boundklassPeriodArraynamestr	docstring
str | Nonec                H      fd} |_         ||_        t          |          S )Nc                L    | j         j        }t          | j        |          }|S N)dtype_dtype_coder$   asi8)selfbaseresultrC   s      N/var/www/sysmax/venv/lib/python3.11/site-packages/pandas/core/arrays/period.pyfz_field_accessor.<locals>.fm   s%    z%%dDIt<<    )__name____doc__property)rC   rE   rQ   s   `  rP   _field_accessorrV   l   s8        
 AJAIA;;rR   c                      e Zd ZU dZdZdZ ej        e          Z	e
fZd ZdZedd            Zg Zd	ed
<   dgZd	ed<   g dZd	ed<   g dZd	ed<   eez   ez   Zd	ed<   g dZd	ed<   ded<   	 dddZedd!            Zeddd"dd#            Zeddd"dd$            Zeddd%            Zed&             Zedd)            Zdd-Zdd0Z dd3Z!e"dd4            Z#edd6            Z$edd7            Z%ddd:Z&dd;Z' e(d<d=          Z) e(d>d?          Z* e(d@dA          Z+ e(dBdC          Z, e(dDdE          Z- e(dFdG          Z. e(dHdI          Z/e/Z0 e(dJdK          Z1e1Z2e2Z3 e(dLdM          xZ4Z5 e(dNdO          Z6 e(dP          Z7 e(dQdR          Z8e8Z9eddT            Z:dddXZ;ddYZ< e=di e>dZdZd[ddd]            Z?ddd_Z@d`ddaddeZAdd fdgZB	 	 dddoZCdddfdpddwZD	 dd fdxZEdd|ZFdd}ZG fd~ZHddZId ZJ xZKS )rB   a  
    Pandas ExtensionArray for storing Period data.

    Users should use :func:`~pandas.array` to create new instances.

    Parameters
    ----------
    values : Union[PeriodArray, Series[period], ndarray[int], PeriodIndex]
        The data to store. These should be arrays that can be directly
        converted to ordinals without inference or copy (PeriodArray,
        ndarray[int64]), or a box around such an array (Series[period],
        PeriodIndex).
    dtype : PeriodDtype, optional
        A PeriodDtype instance from which to extract a `freq`. If both
        `freq` and `dtype` are specified, then the frequencies must match.
    freq : str or DateOffset
        The `freq` to use for the array. Mostly applicable when `values`
        is an ndarray of integers, when `freq` is required. When `values`
        is a PeriodArray (or box around), it's checked that ``values.freq``
        matches `freq`.
    copy : bool, default False
        Whether to copy the ordinals before storing.

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

    Methods
    -------
    None

    See Also
    --------
    Period: Represents a period of time.
    PeriodIndex : Immutable Index for period data.
    period_range: Create a fixed-frequency PeriodArray.
    array: Construct a pandas array.

    Notes
    -----
    There are two components to a PeriodArray

    - ordinals : integer ndarray
    - freq : pd.tseries.offsets.Offset

    The values are physically stored as a 1-D ndarray of integers. These are
    called "ordinals" and represent some kind of offset from a base.

    The `freq` indicates the span covered by each element of the array.
    All elements in the PeriodArray have the same `freq`.

    Examples
    --------
    >>> pd.arrays.PeriodArray(pd.PeriodIndex(['2023-01-01',
    ...                                       '2023-01-02'], freq='D'))
    <PeriodArray>
    ['2023-01-01', '2023-01-02']
    Length: 2, dtype: period[D]
    i  periodarrayc                ,    t          | t                    S rI   )
isinstancer,   )xs    rP   <lambda>zPeriodArray.<lambda>   s    Z	;& & rR   )r   returntype[Period]c                    t           S rI   )r#   rM   s    rP   _scalar_typezPeriodArray._scalar_type   s    rR   z	list[str]
_other_opsis_leap_year	_bool_ops)
start_timeend_timefreq_object_ops)yearmonthdayhourminutesecond
weekofyearweekdayweek	dayofweekday_of_week	dayofyearday_of_yearquarterqyeardays_in_monthdaysinmonth
_field_ops_datetimelike_ops)strftimeto_timestampasfreq_datetimelike_methodsr,   _dtypeNFrJ   Dtype | NonecopyboolNonec                   |Gt          j        dt          t                                 t	          ||          }t          |          }|7t          |          }t          |t
                    st          d| d          t          |t                    r4|j
        }t          |t          |                     st          d          nt          |t                    r|j
        }t          |t          |                     r0| ||j        k    rt          ||j                  |j        |j        }}t%          j        |d|          }|t          d          t)          t
          |          }t+          j        | ||           d S )	Nz}The 'freq' keyword in the PeriodArray constructor is deprecated and will be removed in a future version. Pass 'dtype' instead)
stacklevelzInvalid dtype z for PeriodArrayzIncorrect dtypeint64rJ   r   z-dtype is not specified and cannot be inferred)warningswarnFutureWarningr(   validate_dtype_freqr,   r*   rZ   
ValueErrorr/   _valuestype	TypeErrorr.   rJ   raise_on_incompatiblerg   _ndarraynparrayr
   r   __init__)rM   valuesrJ   rg   r   s        rP   r   zPeriodArray.__init__   s    MP+--	    'ud33D%%E ''Ee[11 K !I%!I!I!IJJJfi(( 	$^Ffd4jj11 3 12223 // 	$^Ffd4jj)) 	: Ufl%:%:+FEJ???"OV\EF&d;;;=LMMM[%((tVU33333rR   r   npt.NDArray[np.int64]r:   c                ~    d}t          |t          j                  r|j        dk    s
J |             | ||          S )Nz Should be numpy array of type i8i8rJ   )rZ   r   ndarrayrJ   )clsr   rJ   assertion_msgs       rP   _simple_newzPeriodArray._simple_new
  sJ     ;&"*--U&,$2F2F2F2F2F2Fs6''''rR   r   c                  |t          |          }|rt          |t                    r|j        }nd }t          ||           r-t	          |j        |           |r|                                }|S t          j        |t                    }|pt          j        |          }t          j        ||          }t          |          } | ||          S )Nr   )r*   rZ   r,   rg   r   rJ   r   r   asarrayobject	libperiodextract_freqextract_ordinals)r   scalarsrJ   r   rg   periodsordinalss          rP   _from_sequencezPeriodArray._from_sequence  s      ''E 	Z{33 	:DDDgs## 	t444 )!,,..N*WF3336y-g66-gt<<D!!s85))))rR   c               2    |                      |||          S )Nr   )r   )r   stringsrJ   r   s       rP   _from_sequence_of_stringsz%PeriodArray._from_sequence_of_strings1  s     !!'T!BBBrR   c                    t          |t                    rt          |j        |j                  }t          |||          \  }}t          |          } | ||          S )a  
        Construct a PeriodArray from a datetime64 array

        Parameters
        ----------
        data : ndarray[datetime64[ns], datetime64[ns, tz]]
        freq : str or Tick
        tz : tzinfo, optional

        Returns
        -------
        PeriodArray[freq]
        r   )rZ   r   r   nrC   r   r,   )r   datarg   tzrJ   s        rP   _from_datetime64zPeriodArray._from_datetime647  s`     dJ'' 	=)$&$)<<D)$b99
dD!!s4u%%%%rR   c                    t          j        |          }|t          j        |          }||t	          ||||          \  }}nt          d          ||fS )Nz/Not enough parameters to construct Period range)dtlvalidate_periodsr#   _maybe_convert_freq_get_ordinal_ranger   )r   startendr   rg   subarrs         rP   _generate_rangezPeriodArray._generate_rangeL  sd    &w//-d33D-eS'4HHLFDDNOOOt|rR   fieldsdictc               p    t          dd|i|\  }}t          |          }|                     ||          S )Nrg   r    )_range_from_fieldsr,   r   )r   r   rg   r   rJ   s        rP   _from_fieldszPeriodArray._from_fieldsZ  sA    )>>t>v>>D!!vU333rR   valuePeriod | NaTTypenp.int64c                    |t           u rt          j        |j                  S t	          || j                  r.|                     |           t          j        |j                  S t          d| d          )Nz!'value' should be a Period. Got 'z
' instead.)	r   r   r   _valuerZ   ra   _check_compatible_withordinalr   rM   r   s     rP   _unbox_scalarzPeriodArray._unbox_scalarf  su     C<<8EL)))t011 	T''...8EM***RRRRSSSrR   rD   r#   c                .    t          || j                  S )N)rg   )r#   rg   r   s     rP   _scalar_from_stringzPeriodArray._scalar_from_strings  s    e$),,,,rR   otherPeriod | NaTType | PeriodArrayc                P    |t           u rd S |                     |j                   d S rI   )r   _require_matching_freqrg   rM   r   s     rP   r   z"PeriodArray._check_compatible_withy  s.    C<<F 	##EJ/////rR   c                    | j         S rI   )r   r`   s    rP   rJ   zPeriodArray.dtype  s
    {rR   r   c                    | j         j        S )zC
        Return the frequency object for this PeriodArray.
        rJ   rg   r`   s    rP   rg   zPeriodArray.freq  s    
 zrR   c                J    t          | j        j        | j        j                  S rI   )r   rg   r   rC   r`   s    rP   freqstrzPeriodArray.freqstr  s    %dik49>BBBrR   NpDtype | None
np.ndarrayc                    |dk    r| j         S |t          k    r| j         S t          j        t          |           t                    S )Nr   r   )rL   r   _isnanr   r   listr   )rM   rJ   s     rP   	__array__zPeriodArray.__array__  sC    D==9d]]K< xT

&1111rR   c                   ddl }ddlm} ||j                            |          r/|                    | j        |                                 |          S t          ||          r1| j	        |j
        k    r t          d| j	         d|j
         d          nt          d| d	           || j	                  }|                    | j        |                                 d
          }|j                            ||          S )z6
        Convert myself into a pyarrow Array.
        r   N)ArrowPeriodType)maskr   zENot supported to convert PeriodArray to array with different 'freq' (z vs )z)Not supported to convert PeriodArray to 'z' typer   )pyarrow(pandas.core.arrays.arrow.extension_typesr   types
is_integerr   r   r1   rZ   r   rg   r   r>   from_storage)rM   r   r   r   period_typestorage_arrays         rP   __arrow_array__zPeriodArray.__arrow_array__  s4    	LLLLLL}''-- }}T]4}PPPD/22 
<49,,#B#'<B B59YB B B   -  LLLL   &odl33dm$))++GTT%22;NNNrR   ri   z
        The year of the period.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
        >>> idx.year
        Index([2023, 2024, 2025], dtype='int64')
        rj   z
        The month as January=1, December=12.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
        >>> idx.month
        Index([1, 2, 3], dtype='int64')
        rk   z
        The days of the period.

        Examples
        --------
        >>> idx = pd.PeriodIndex(['2020-01-31', '2020-02-28'], freq='D')
        >>> idx.day
        Index([31, 28], dtype='int64')
        rl   z
        The hour of the period.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01-01 10:00", "2023-01-01 11:00"], freq='h')
        >>> idx.hour
        Index([10, 11], dtype='int64')
        rm   a  
        The minute of the period.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01-01 10:30:00",
        ...                       "2023-01-01 11:50:00"], freq='min')
        >>> idx.minute
        Index([30, 50], dtype='int64')
        rn   a	  
        The second of the period.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01-01 10:00:30",
        ...                       "2023-01-01 10:00:31"], freq='s')
        >>> idx.second
        Index([30, 31], dtype='int64')
        rq   a   
        The week ordinal of the year.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
        >>> idx.week  # It can be written `weekofyear`
        Index([5, 9, 13], dtype='int64')
        rs   z
        The day of the week with Monday=0, Sunday=6.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01-01", "2023-01-02", "2023-01-03"], freq="D")
        >>> idx.weekday
        Index([6, 0, 1], dtype='int64')
        ru   a  
        The ordinal day of the year.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01-10", "2023-02-01", "2023-03-01"], freq="D")
        >>> idx.dayofyear
        Index([10, 32, 60], dtype='int64')

        >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
        >>> idx
        PeriodIndex(['2023', '2024', '2025'], dtype='period[Y-DEC]')
        >>> idx.dayofyear
        Index([365, 366, 365], dtype='int64')
        rv   z
        The quarter of the date.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
        >>> idx.quarter
        Index([1, 1, 1], dtype='int64')
        rw   rx   a  
        The number of days in the month.

        Examples
        --------
        For Series:

        >>> period = pd.period_range('2020-1-1 00:00', '2020-3-1 00:00', freq='M')
        >>> s = pd.Series(period)
        >>> s
        0   2020-01
        1   2020-02
        2   2020-03
        dtype: period[M]
        >>> s.dt.days_in_month
        0    31
        1    29
        2    31
        dtype: int64

        For PeriodIndex:

        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
        >>> idx.days_in_month   # It can be also entered as `daysinmonth`
        Index([31, 28, 31], dtype='int64')
        npt.NDArray[np.bool_]c                N    t          t          j        | j                            S )z
        Logical indicating if the date belongs to a leap year.

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
        >>> idx.is_leap_year
        array([False,  True, False])
        )r   r   r   ri   r`   s    rP   rc   zPeriodArray.is_leap_year]  s     bj33444rR   r   howr<   c                ~   ddl m} t          j        |          }|dk    }|r||dk    s| j        dk    r:t          dd          t          dd          z
  }|                     d	          |z   S t          dd          }| | j        z                       d	          |z
  S |3| j                                        }t          |d          }|j
        }|}nt          j        |          }|j        }|                     ||	          }	t          j        |	j        |          }
 |j        |
          }| j        j        dk    rjt'          j        | j                  }t+          |          dk    r<|d         }|| j        j        k    r| j        |_        n|dk    r| j        j        |_        |S |                    d          S )a  
        Cast to DatetimeArray/Index.

        Parameters
        ----------
        freq : str or DateOffset, optional
            Target frequency. The default is 'D' for week or longer,
            's' otherwise.
        how : {'s', 'e', 'start', 'end'}
            Whether to use the start or end of the time period being converted.

        Returns
        -------
        DatetimeArray/Index

        Examples
        --------
        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
        >>> idx.to_timestamp()
        DatetimeIndex(['2023-01-01', '2023-02-01', '2023-03-01'],
        dtype='datetime64[ns]', freq='MS')
        r   )r<   EB   Dnsr   )r   Ninfer)pandas.core.arraysr<   r   validate_end_aliasrg   r   r}   r   _get_to_timestamp_baser   _freqstrr#   r   _period_dtype_coder~   periodarr_to_dt64arrrL   r   rC   libalgosunique_deltaslenrJ   _n_freqrN   
_with_freq)rM   rg   r   r<   r   adjust	freq_coderJ   rN   new_parrnew_datadtadiffsdiffs                 rP   r}   zPeriodArray.to_timestampj  s   . 	544444*3//Sj 	Ms{{di3.."1c**Yq$-?-??((W(55>>"1d++ty(6676CCfLL<::<<I#Iq11E>DDD-d33D*D;;t;--1(-FF*m*8449>S   *4955E5zzQQx4:=(( $	CIIQYY $	CIJ>>'***rR   c                8    t          j        || j                  S )N)r   rg   )r#   _from_ordinalrg   )rM   r[   s     rP   	_box_funczPeriodArray._box_func  s    #ADI>>>>rR   PeriodIndex)r   
other_namer   c                   t          j        |          }t          |t                    r$t	          |d          rt          |          j        }t          j        |          }| j	        j
        }|j        }| j        }|dk    }|r|| j        j        z   dz
  }n|}t          ||||          }| j        rt"          || j        <   t          |          }	 t'          |           ||	          S )a  
        Convert the {klass} to the specified frequency `freq`.

        Equivalent to applying :meth:`pandas.Period.asfreq` with the given arguments
        to each :class:`~pandas.Period` in this {klass}.

        Parameters
        ----------
        freq : str
            A frequency.
        how : str {{'E', 'S'}}, default 'E'
            Whether the elements should be aligned to the end
            or start within pa period.

            * 'E', 'END', or 'FINISH' for end,
            * 'S', 'START', or 'BEGIN' for start.

            January 31st ('END') vs. January 1st ('START') for example.

        Returns
        -------
        {klass}
            The transformed {klass} with the new frequency.

        See Also
        --------
        {other}.asfreq: Convert each Period in a {other_name} to the given frequency.
        Period.asfreq : Convert a :class:`~pandas.Period` object to the given frequency.

        Examples
        --------
        >>> pidx = pd.period_range('2010-01-01', '2015-01-01', freq='Y')
        >>> pidx
        PeriodIndex(['2010', '2011', '2012', '2013', '2014', '2015'],
        dtype='period[Y-DEC]')

        >>> pidx.asfreq('M')
        PeriodIndex(['2010-12', '2011-12', '2012-12', '2013-12', '2014-12',
        '2015-12'], dtype='period[M]')

        >>> pidx.asfreq('M', how='S')
        PeriodIndex(['2010-01', '2011-01', '2012-01', '2013-01', '2014-01',
        '2015-01'], dtype='period[M]')
        r   r   r   r   )r   r   rZ   r   hasattrr,   r   r#   r   r   rK   r   rL   rJ   r   r%   _hasnar   r   r   )
rM   rg   r   base1base2rL   r   r   r   rJ   s
             rP   r~   zPeriodArray.asfreq  s    \ *3//dJ'' 	.GD:N,O,O 	.t$$-D)$//''ySj 	TZ]*Q.GGG$WeUC@@; 	)$(HT[!D!!tDzz(%0000rR   boxedc                "    |rt           S dj        S )Nz'{}')rD   format)rM   r  s     rP   
_formatterzPeriodArray._formatter  s     	J}rR   r   )na_repdate_formatr  str | floatnpt.NDArray[np.object_]c               N    t          j        | j        | j        j        ||          S )z3
        actually format my specific types
        )r   period_array_strftimerL   rJ   rK   )rM   r  r  kwargss       rP   _format_native_typesz PeriodArray._format_native_types  s)     .Itz-v{
 
 	
rR   Tc                   t          |          }|| j        k    r|s| S |                                 S t          |t                    r|                     |j                  S t          j        |d          st          |t                    r_t          |dd           }t          j        |          }|                                                     |                              |          S t!                                          ||          S )NMr   r   )r*   r   r   rZ   r,   r~   rg   r   is_np_dtyper+   getattrr   dtype_to_unitr}   tz_localizeas_unitsuperastype)rM   rJ   r   r   unit	__class__s        rP   r#  zPeriodArray.astype  s     U##DK #yy{{"e[)) 	+;;uz***?5#&& 	E*UO*L*L 	Ed++B$U++D$$&&22266>>tDDDww~~e$~///rR   left$NumpyValueArrayLike | ExtensionArraysideLiteral['left', 'right']sorterNumpySorter | Nonenpt.NDArray[np.intp] | np.intpc                    |                      |                              d          }| j                            d          }|                    |||          S )NM8[ns])r(  r*  )_validate_setitem_valueviewr   searchsorted)rM   r   r(  r*  npvaluem8arrs         rP   r1  zPeriodArray.searchsorted  sW     ..u55::8DD ""8,,!!'V!DDDrR   )limit
limit_arear   methodr6   r4  
int | Noner5  #Literal['inside', 'outside'] | Nonec                   |                      d          }|                    ||||          }|r(t          d|                     | j                            S | S )Nr.  )r6  r4  r5  r   r:   )r0  _pad_or_backfillr
   rJ   )rM   r6  r4  r5  r   r  rO   s          rP   r:  zPeriodArray._pad_or_backfill,  se     ii!!%%:D & 
 
  	DJ 7 7888KrR   c                    |H|                      d          }|                    ||||          }|                     | j                  S t                                          ||||          S )Nr.  )r   r6  r4  r   )r0  fillnarJ   r"  )rM   r   r6  r4  r   r  rO   r%  s          rP   r<  zPeriodArray.fillna?  sk      ))H%%CZZeF%dZSSF ;;tz***ww~~E&D~QQQrR   np.ndarray | intopCallable[[Any, Any], Any]c                    |t           j        t           j        fv sJ |t           j        u r| }t          | j        t          j        |d                    } t          |           || j                  S )z
        Add or subtract array of integers.

        Parameters
        ----------
        other : np.ndarray[int64] or int
        op : {operator.add, operator.sub}

        Returns
        -------
        result : PeriodArray
        r   r   )	operatoraddsubr   rL   r   r   r   rJ   )rM   r   r>  
res_valuess       rP   _addsub_int_array_or_scalarz'PeriodArray._addsub_int_array_or_scalarO  so     hlHL11111FE%diE1N1N1NOO
tDzz*DJ7777rR   c                    t          |t                    rJ |                     |d           |                     |j        t
          j                  S )NT)rN   )rZ   r   r   rE  r   rA  rB  r   s     rP   _add_offsetzPeriodArray._add_offsetd  sK    eT*****##E#555//FFFrR   c                .   t          | j        t                    st          | |          t	          |          r!t                                          |          S t          j        t          |          j
                  }|                     |          S )z
        Parameters
        ----------
        other : timedelta, Tick, np.timedelta64

        Returns
        -------
        PeriodArray
        )rZ   rg   r   r   r1   r"  _add_timedeltalike_scalarr   r   r   asm8_add_timedelta_arraylike)rM   r   tdr%  s      rP   rI  z%PeriodArray._add_timedeltalike_scalark  s}     $)T** 	5'e444;; 	<7744U;;;Z	%((-..,,R000rR   ,TimedeltaArray | npt.NDArray[np.timedelta64]c                   | j                                         st          d| j                    t          j         d| j         j         d          }	 t          t          j        |          |dd          }n"# t          $ r}t          d          |d}~ww xY wt          | j
        t          j        |                    d                              } t          |           || j         	          S )
z
        Parameters
        ----------
        other : TimedeltaArray or ndarray[timedelta64]

        Returns
        -------
        PeriodArray
        z2Cannot add or subtract timedelta64[ns] dtype from m8[]FrJ   r   round_okznCannot add/subtract timedelta-like from PeriodArray that is not an integer multiple of the PeriodArray's freq.Nr   r   )rJ   _is_tick_liker   r   
_td64_unitr   r   r   r"   r   rL   r0  r   )rM   r   rJ   deltaerrrD  s         rP   rK  z$PeriodArray._add_timedelta_arraylike  s    z'')) 	QTZQQ   7tz477788
	'
5!!UU  EE  	 	 	 (E  	 &diEJJt<L<L1M1MNN
tDzz*DJ7777s   %A: :
BBBc                   | j                                         sJ t          j         d| j         j         d          }t	          |t
          t          j        t          f          r't          j        t          |          j
                  }nt          j        |          }	 t          ||dd          }n## t          $ r}t          | |          |d}~ww xY w|                    d          }t          j        |          S )a<  
        Arithmetic operations with timedelta-like scalars or array `other`
        are only valid if `other` is an integer multiple of `self.freq`.
        If the operation is valid, find that integer multiple.  Otherwise,
        raise because the operation is invalid.

        Parameters
        ----------
        other : timedelta, np.timedelta64, Tick,
                ndarray[timedelta64], TimedeltaArray, TimedeltaIndex

        Returns
        -------
        multiple : int or ndarray[int64]

        Raises
        ------
        IncompatibleFrequency
        rO  rP  FrQ  Nr   )rJ   rS  r   rT  rZ   r   timedelta64r   r   r   rJ  r   r   r   r0  r   item_from_zerodim)rM   r   rJ   rL  rU  rV  s         rP    _check_timedeltalike_freq_compatz,PeriodArray._check_timedeltalike_freq_compat  s    ( z'')))))7tz477788ei>?? 	#Ie,,122BBE""B	>'%eeTTTEE 	> 	> 	>'e44#=	> 

4  $U+++s   !B5 5
C?CC)r]   r^   )NNF)rJ   r   r   r   r]   r   )r   r   rJ   r,   r]   r:   )rJ   r   r   r   r]   r:   rI   )r]   r:   )r   r   r]   r:   )r   r   r]   r   )r   rD   r]   r#   )r   r   r]   r   )r]   r,   )r]   r   )r]   rD   )rJ   r   r]   r   )r]   r   )Nr   )r   rD   r]   r<   )r]   r   r   )Nr   )r   rD   r]   r:   )F)r  r   )r  r  r]   r  )T)r   r   )r&  N)r   r'  r(  r)  r*  r+  r]   r,  )
r6  r6   r4  r7  r5  r8  r   r   r]   r:   )NNNT)r4  r7  r   r   r]   r:   )r   r=  r>  r?  r]   r:   )r   r   )r   rM  r]   r:   )LrS   
__module____qualname__rT   __array_priority___typr   r   r   _internal_fill_valuer#   _recognized_scalars_is_recognized_dtype_infer_matchesrU   ra   rb   __annotations__rd   rh   rz   r{   r   r   classmethodr   r   r   r   r   r   r   r   r   r&   rJ   rg   r   r   r   rV   ri   rj   rk   rl   rm   rn   ro   rq   rs   rr   rp   rt   ru   rv   rw   rx   ry   rc   r}   r  r'   _shared_doc_kwargsr~   r  r  r#  r1  r:  r<  rE  rG  rI  rK  rZ  __classcell__)r%  s   @rP   rB   rB   y   s@        : :z D#28D>>!)  !N   X J*+I++++???K????  J    & $.#;i#GGGGG'M'M'MMMMM KP$4 $4 $4 $4 $4N ( ( ( [( 
 #* * * * * [*6 /3%C C C C C [C
 & & & & [&(   [ 4 4 4 [4T T T T- - - -0 0 0 0    ^    X C C C XC2 2 2 2 2O O O O< ?	 D O	 E /	 C ?	 D _		 F _		 F !	 J D!/	 K IG-o	  I$ o	 G OG$$E#O	 M:  K
5 
5 
5 X
5@+ @+ @+ @+ @+H? ? ? ? 	SMMM]}MMMMC1 C1 C1 C1 NMC1P     (-$
 
 
 
 
 
0 0 0 0 0 0 0. *0%)	E E E E E" !:>     ( OSR R R R R R R 8 8 8 8*G G G G1 1 1 1 1*#8 #8 #8 #8J#, #, #, #, #, #, #,rR   r]   r"   c                   t          |t          j        t          f          s|d}n{t          |t                    rt          |j        |j                  }nKt          |t          t          t          f          r|j        }n!t          t          |                    j        }t          | j        j        | j        j                  }t          j        t#          |           j        ||          }t'          |          S )a>  
    Helper function to render a consistent error message when raising
    IncompatibleFrequency.

    Parameters
    ----------
    left : PeriodArray
    right : None, DateOffset, Period, ndarray, or timedelta-like

    Returns
    -------
    IncompatibleFrequency
        Exception to be raised by the caller.
    N)r   own_freq
other_freq)rZ   r   r   r0   r   r   r   rC   r.   rB   r#   r   r    r   rg   r!   r  r   rS   r"   )r&  rightri  rh  msgs        rP   r   r     s      %"*&7899 =U]

	E:	&	& =+EGUZ@@

	ENK@	A	A =]

"9U#3#344<
%dik49>BBH

JJ(z  C !%%%rR   Fr   ,Sequence[Period | str | None] | AnyArrayLikerg   str | Tick | BaseOffset | Noner   r   c                   t          | dd          }t          j        |d          rt                              | |          S t          |t                    r5t          |           }|"||j        k    r|S |                    |          S |S t          | t          j
        t          t          t          f          st          |           } t          j        |           }|rt          |          }nd}|j        j        dk    r"t#          |          dk    rt%          d          |j        j        dv rG|                    t          j        d	          }t+          j        ||          }t          ||
          S t/          |          } |t+          j        |           }t          |          }t                              | |
          S )a  
    Construct a new PeriodArray from a sequence of Period scalars.

    Parameters
    ----------
    data : Sequence of Period objects
        A sequence of Period objects. These are required to all have
        the same ``freq.`` Missing values can be indicated by ``None``
        or ``pandas.NaT``.
    freq : str, Tick, or Offset
        The frequency of every element of the array. This can be specified
        to avoid inferring the `freq` from `data`.
    copy : bool, default False
        Whether to ensure a copy of the data is made.

    Returns
    -------
    PeriodArray

    See Also
    --------
    PeriodArray
    pandas.PeriodIndex

    Examples
    --------
    >>> period_array([pd.Period('2017', freq='Y'),
    ...               pd.Period('2018', freq='Y')])
    <PeriodArray>
    ['2017', '2018']
    Length: 2, dtype: period[Y-DEC]

    >>> period_array([pd.Period('2017', freq='Y'),
    ...               pd.Period('2018', freq='Y'),
    ...               pd.NaT])
    <PeriodArray>
    ['2017', '2018', 'NaT']
    Length: 3, dtype: period[Y-DEC]

    Integers that look like years are handled

    >>> period_array([2000, 2001, 2002], freq='D')
    <PeriodArray>
    ['2000-01-01', '2001-01-01', '2002-01-01']
    Length: 3, dtype: period[D]

    Datetime-like strings may also be passed

    >>> period_array(['2000-Q1', '2000-Q2', '2000-Q3', '2000-Q4'], freq='Q')
    <PeriodArray>
    ['2000Q1', '2000Q2', '2000Q3', '2000Q4']
    Length: 4, dtype: period[Q-DEC]
    rJ   Nr  rQ   r   z9PeriodIndex does not allow floating point in constructioniuFr  r   )r  r   r  rB   r   rZ   r,   rg   r~   r   r   r   tupler/   r   rJ   kindr   r   r#  r   r   from_ordinalsr)   r   r   )	r   rg   r   
data_dtypeoutarrdatarJ   arrr   s	            rP   period_arrayrw    s   t w--J
z3'' 8++D$777*k** $z&&
::d###
 dRZui@AA DzzjG  D!!}S  S\\A%5%5STTT}T!!nnRXEn22 *355851111!!D|%d++E%%d%%888rR   c                    d S rI   r   r   s     rP   r   r   R      CrR   timedelta | str | Noner   c                    d S rI   r   r   s     rP   r   r   W  ry  rR   1BaseOffsetT | BaseOffset | timedelta | str | Nonec                    |t          |d          }| Wt          |           } t          | t                    st	          d          || j        }n|| j        k    rt          d          |S )at  
    If both a dtype and a freq are available, ensure they match.  If only
    dtype is available, extract the implied freq.

    Parameters
    ----------
    dtype : dtype
    freq : DateOffset or None

    Returns
    -------
    freq : DateOffset

    Raises
    ------
    ValueError : non-period dtype
    IncompatibleFrequency : mismatch between dtype and freq
    NT	is_periodzdtype must be PeriodDtypez&specified freq and dtype are different)r   r*   rZ   r,   r   rg   r"   r   s     rP   r   r   \  s    * ...U##%-- 	:8999<:DDUZ'(PQQQ KrR   (tuple[npt.NDArray[np.int64], BaseOffset]c                    t          | j        t          j                  r| j        j        dk    rt	          d| j                   |Mt          | t
                    r| j        | j        }} nLt          | t                    r| j        | j	        j        }} n#t          | t
          t          f          r| j        } t          | j                  }t          j        |          }|j        }t          |                     d          |||          |fS )a  
    Convert an datetime-like array to values Period ordinals.

    Parameters
    ----------
    data : Union[Series[datetime64[ns]], DatetimeIndex, ndarray[datetime64ns]]
    freq : Optional[Union[str, Tick]]
        Must match the `freq` on the `data` if `data` is a DatetimeIndex
        or Series.
    tz : Optional[tzinfo]

    Returns
    -------
    ordinals : ndarray[int64]
    freq : Tick
        The frequency extracted from the Series or DatetimeIndex if that's
        used.

    r  zWrong dtype: Nr   )reso)rZ   rJ   r   rq  r   r-   r   rg   r/   dtr   r#   r   r   c_dt64arr_to_periodarrr0  )r   rg   r   r  rN   s        rP   r   r     s    , dj"(++ 7tz#/E/E555666|dH%% 	4ty$DDi(( 	4tw|$D	D8Y/	0	0 |tz**D%d++D"D!$))D//4$GGGMMrR   r   multintc                H   t          j        | ||          dk    rt          d          |t          |d          }|j        }| t          | |          } |t          ||          }t          | t
                    }t          |t
                    }|r!|r| j        |j        k    rt          d          | t          u s	|t          u rt          d          |*|r| j        }n|r|j        }nt          d          |j        }|m||z  }| 6t          j
        |j        |z
  |z   |j        dz   |t          j        	          }n_t          j
        | j        | j        |z   |t          j        	          }n/t          j
        | j        |j        dz   |t          j        	          }||fS )
N   zOOf the three parameters: start, end, and periods, exactly two must be specifiedTr~  z!start and end must have same freqzstart and end must not be NaTz#Could not infer freq from start/endr   r   )comcount_not_noner   r   r   r#   rZ   rg   r   r   aranger   r   )r   r   r   rg   r  is_start_per
is_end_perr   s           rP   r   r     s   
%g..!33,
 
 	

 ...vud##
S$eV,,LC((J >
 >uzSX'='=<===||sczz8999| 	D:DD 	D8DDBCCCvD.=9g%,ckAot28  DD 9u}w6BH  DD yaRXNNN:rR   tuple[np.ndarray, BaseOffset]c                6   |d}|d}|d}|d}g }||#t          dd          }t          j        j        }	nIt          |d          }t	          j        |          }	|	t          j        j        k    rt          d          |j        }
t          | |          \  } }t          | |          D ]O\  }}t          j        |||
          \  }}t	          j        ||dddddd|		  	        }|                    |           Pn{t          |d          }t	          j        |          }	t          | |||||          }t          | D ]8\  }}}}}}|                    t	          j        ||||||dd|		  	                   9t          j        |t          j                  |fS )Nr   r   QTr~  zbase must equal FR_QTRr   )r   r   FR_QTRr   r   freq_to_dtype_codeAssertionErrorr   _make_field_arrayszipr   quarter_to_myearperiod_ordinalappendr   r   r   )ri   rj   rv   rk   rl   rm   rn   rg   r   rN   r   yqcalendar_yearcalendar_monthvalarraysmthdhmnss                         rP   r   r     s    |~~
{H<SD111D#)DDTT222D/55Dy'---$%=>>>,*499gg&& 	! 	!DAq,3,DQ7,S,S)M>*~q!Q1a C OOC    	! ...+D11#D%dFFKK#&< 	W 	WAsAq"aOOI4QQ2q!QPTUUVVVV8HBH---t33rR   list[np.ndarray]c                     d | D ]^}t          |t          t          j        t          f          r5"t          |          k    rt          d          t          |          _fd| D             S )NzMismatched Period array lengthsc                    g | ]R}t          |t          j        t          t          f          rt          j        |          nt          j        |          SS r   )rZ   r   r   r   r/   r   repeat).0r[   lengths     rP   
<listcomp>z&_make_field_arrays.<locals>.<listcomp>  s^         a"*dI677	"
1Yq&!!  rR   )rZ   r   r   r   r/   r   r   )r   r[   r  s     @rP   r  r    s    F    a$
I677 	 !c!ff&6&6 !BCCC~Q
    	   rR   rI   )rC   rD   rE   rF   )r]   r"   )NF)r   rl  rg   rm  r   r   r]   rB   )rg   r?   r]   r?   )rg   rz  r]   r   )rg   r|  r]   r?   )r]   r  )r   )r  r  )NNNNNNNN)r]   r  )r]   r  )h
__future__r   datetimer   rA  typingr   r   r   r   r	   r
   r   r   numpyr   pandas._libsr   r   r   pandas._libs.arraysr   pandas._libs.tslibsr   r   r   r   r   r   r   r  r   r   r   r   r   r   pandas._libs.tslibs.dtypesr   r   r   pandas._libs.tslibs.fieldsr   pandas._libs.tslibs.offsetsr   r    pandas._libs.tslibs.periodr!   r"   r#   r$   r%   pandas.util._decoratorsr&   r'   pandas.util._exceptionsr(   pandas.core.dtypes.commonr)   r*   pandas.core.dtypes.dtypesr+   r,   pandas.core.dtypes.genericr-   r.   r/   r0   pandas.core.dtypes.missingr1   r   r2   r   pandas.core.commoncorecommonr  collections.abcr3   pandas._typingr4   r5   r6   r7   r8   r9   r:   r;   r<   r=   pandas.core.arrays.baser>   r?   re  rV   DatelikeOpsPeriodMixinrB   r   rw  r   r   r   r  r   rR   rP   <module>r     s{   " " " " " "                                     . - - - - -                                    
 6 5 5 5 5 5                            5 4 4 4 4 4                          , + + + + + 2 2 2 2 2 2                   7((((((	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	        766666 gm:666 ] 
    O, O, O, O, O,#/9#8 O, O, O,d& & & &L ,0`9 `9 `9 `9 `9F 
   
 
   
" " " "L %N %N %N %N %NP. . . . .d 

		.4 .4 .4 .4 .4b     rR   