o Tj@sddlmZddlmZddlZddlmZmZmZm Z m Z m Z m Z ddl Z ddlZddlmZmZddlmZddlmZmZmZmZmZmZmZmZm Z m!Z!m"Z#m$Z$ddl%m&Z&m'Z'm(Z(dd l)m*Z*dd l+m,Z,m-Z-dd l.m/Z/m0Z0m1Z1m2Z2m3Z3dd l4m5Z5m6Z6dd l7m8Z8ddl9m:Z:m;Z;ddlZ>ddl?m@Z@mAZAmBZBmCZCddlDmEZEddlFmGZHddlImJmKZLerddlMmNZNddlOmPZPmQZQmRZRmSZSmTZTmUZUmVZVmWZWddlFmXZXmYZYddlZm[Z[e dedZ\ddiZ]dDdEdd Z^Gd!ddeHj_e#j`ZadFd$d%Zb  &dGdHd-d.Zce dId/d0Zde dJd3d0ZddKd5d0Zd dDdLd7d8ZdMdNd.f)__name____doc__property)rBrDrPrNrMrO_field_accessorls rTcseZdZUdZdZdZeeZ e fZ ddZ dZ edd d ZgZd ed <d gZd ed<gdZd ed<gdZd ed<eeeZd ed<gdZd ed<ded< dddd Zedd$d%Zeddd&dd'd(Zeddd&dd)d*Zeddd+d,Zed-d.Zedd1d2Zdd6d7Zdd:d;Z dd>d?Z!e"dd@dAZ#eddCdDZ$eddEdFZ% dddJdKZ&ddLdMZ'e(dNdOZ)e(dPdQZ*e(dRdSZ+e(dTdUZ,e(dVdWZ-e(dXdYZ.e(dZd[Z/e/Z0e(d\d]Z1e1Z2e2Z3e(d^d_Z4Z5e(d`daZ6e(dbZ7e(dcddZ8e8Z9eddfdgZ:dddkdlZ;ddmdnZdododpdddrdsZ?dddudvZ@dwddxdd|d}ZAddfdd ZB ddddZCddd~ddddZD ~ddÇfdd ZEdddZFdddZGfddZHdddZIddZJZKS)rAa 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')) ['2023-01-01', '2023-01-02'] Length: 2, dtype: period[D] i periodarraycCs t|tSrF) isinstancer+)xrNrNrOszPeriodArray.)rreturn type[Period]cCstSrF)r"rJrNrNrO _scalar_typezPeriodArray._scalar_typez list[str] _other_ops is_leap_year _bool_ops) start_timeend_timefreq _object_ops)yearmonthdayhourminutesecond weekofyearweekdayweek dayofweek day_of_week dayofyear day_of_yearquarterqyear days_in_month daysinmonth _field_ops_datetimelike_ops)strftime to_timestampasfreq_datetimelike_methodsr+_dtypeNFrG Dtype | NonecopyboolNonecCs|durtjdttdt||}t|}|dur+t|}t|ts+td|dt|t r?|j }t|t |s>t dnt|t rG|j }t|t |rd|dur]||jkr]t||j|j|j}}|sntj|dd}ntj|d|d}|dur~td tt|}t|||dS) Nz}The 'freq' keyword in the PeriodArray constructor is deprecated and will be removed in a future version. Pass 'dtype' instead stacklevelzInvalid dtype z for PeriodArrayzIncorrect dtypeint64rGrGr~z-dtype is not specified and cannot be inferred)warningswarn FutureWarningr'validate_dtype_freqr+r)rV ValueErrorr._valuestype TypeErrorr-rGraise_on_incompatiblerc_ndarraynpasarrayarrayr r __init__)rJvaluesrGrcr~rNrNrOrs<      zPeriodArray.__init__rnpt.NDArray[np.int64]r9cCs.d}t|tjr |jdksJ||||dS)Nz Should be numpy array of type i8i8r)rVrndarrayrG)clsrrG assertion_msgrNrNrO _simple_new s zPeriodArray._simple_newrcCs|durt|}|rt|tr|j}nd}t||r(t|j||r&|}|Stj|t d}|p5t |}t ||}t|}|||dS)Nr) r)rVr+rcrrGr~rrobject libperiod extract_freqextract_ordinals)rscalarsrGr~rcperiodsordinalsrNrNrO_from_sequences    zPeriodArray._from_sequencecCs|j|||dS)Nr)r)rstringsrGr~rNrNrO_from_sequence_of_strings4sz%PeriodArray._from_sequence_of_stringscCs<t|tr t|j|j}t|||\}}t|}|||dS)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)rVrrnrBrr+)rdatarctzrGrNrNrO_from_datetime64:s  zPeriodArray._from_datetime64cCsNt|}|durt|}|dus|dur#t||||\}}||fStd)Nz/Not enough parameters to construct Period range)dtlvalidate_periodsr"_maybe_convert_freq_get_ordinal_ranger)rstartendrrcsubarrrNrNrO_generate_rangeOs  zPeriodArray._generate_rangefieldsdictcCs,tdd|i|\}}t|}|j||dS)NrcrrN)_range_from_fieldsr+r)rrrcrrGrNrNrO _from_fields]szPeriodArray._from_fieldsvaluePeriod | NaTTypenp.int64cCsF|tur t|jSt||jr||t|jStd|d)Nz!'value' should be a Period. Got 'z ' instead.) rrr_valuerVr\_check_compatible_withordinalrrJrrNrNrO _unbox_scalaris     zPeriodArray._unbox_scalarrCr"cCst||jdS)N)rc)r"rcrrNrNrO_scalar_from_stringvszPeriodArray._scalar_from_stringotherPeriod | NaTType | PeriodArraycCs|turdS||jdSrF)r_require_matching_freqrcrJrrNrNrOr|sz"PeriodArray._check_compatible_withcCs|jSrF)r|r[rNrNrOrGszPeriodArray.dtypercCs|jjS)zC Return the frequency object for this PeriodArray. rGrcr[rNrNrOrcszPeriodArray.freqcCst|jj|jjSrF)rrcrrBr[rNrNrOfreqstrszPeriodArray.freqstrNpDtype | None bool | None np.ndarraycCsh|dkr|stj|j|dStj|j|dS|dur#tjdttd|tkr+|j Stjt |t dS)NrrFaSStarting with NumPy 2.0, the behavior of the 'copy' keyword has changed and passing 'copy=False' raises an error when returning a zero-copy NumPy array is not possible. pandas will follow this behavior starting with pandas 3.0. This conversion to NumPy requires a copy, but 'copy=False' was passed. Consider using 'np.asarray(..)' instead.r) rrrIrrrrr'r_isnanlistr)rJrGr~rNrNrO __array__s zPeriodArray.__array__cCsddl}ddlm}|dur@|j|r|j|j||dSt||r8|j |j kr7t d|j d|j dnt d|d ||j }|j|j|d d}|j ||S) z6 Convert myself into a pyarrow Array. rN)ArrowPeriodType)maskrzENot 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_typesrtypes is_integerrrr0rVrrcrr= from_storage)rJrrr period_type storage_arrayrNrNrO__arrow_array__s*      zPeriodArray.__arrow_array__rez The year of the period. Examples -------- >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y") >>> idx.year Index([2023, 2024, 2025], dtype='int64') rfz 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') rgz The days of the period. Examples -------- >>> idx = pd.PeriodIndex(['2020-01-31', '2020-02-28'], freq='D') >>> idx.day Index([31, 28], dtype='int64') rhz 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') ria  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') rja  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') rma 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') roz 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') rqa 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') rrz 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') rsrta 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_]cCstt|jS)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]) )rrrrer[rNrNrOr_ts zPeriodArray.is_leap_yearrhowr;cCs:ddlm}t|}|dk}|r<|dks|jdkr,tddtdd}|jdd |Stdd}||jjdd |S|d urP|j}t |d}|j }|}nt |}|j }|j||d } t| j|} || } |jjdkrt|j} t| dkr| d} | |jjkr|j| _| S| dkr|jj| _| 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;EBDnsr)rNinfer)pandas.core.arraysr;rvalidate_end_aliasrcrryr|_get_to_timestamp_baser_freqstrr"r_period_dtype_coderzperiodarr_to_dt64arrrIrrBlibalgos unique_deltaslenrG_n_freqrK _with_freq)rJrcrr;radjust freq_coderGrKnew_parrnew_datadtadiffsdiffrNrNrOrys<             zPeriodArray.to_timestampcCstj||jdS)N)rrc)r" _from_ordinalrc)rJrWrNrNrO _box_funcszPeriodArray._box_func PeriodIndex)r other_namerc Cst|}t|trt|drt|j}t|}|j j }|j }|j }|dk}|r2||j jd}n|}t||||}|jrCt||j<t|} t||| dS)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]') rrrr)rrrVrhasattrr+rr"rr|rHrrIrGrr$_hasnarrr) rJrcrbase1base2rIrrrrGrNrNrOrzs .   zPeriodArray.asfreqboxedcCs|rtSdjS)Nz'{}')rCformat)rJrrNrNrO _formatterszPeriodArray._formatterr)na_rep date_formatr str | floatnpt.NDArray[np.object_]cKst|j|jj||S)z3 actually format my specific types )rperiod_array_strftimerIrGrH)rJrrkwargsrNrNrO_format_native_typessz PeriodArray._format_native_typesTcst|}||jkr|s |S|St|tr||jSt|ds't|t r 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)rown_freq other_freq)rVrrr/rrrrBr-rAr"rrrrcr rrrQr!)rrightrHrGmsgrNrNrOrs  rFr,Sequence[Period | str | None] | AnyArrayLikercstr | Tick | BaseOffset | Noner~rc Cst|dd}t|drt||St|tr-t|}|dur+||jkr&|S||S|St|t j t t t fs;t |}t |}|rGt|}nd}|jjdkrYt|dkrYtd|jjdvrs|jt jdd }t||}t||d St|}|durt|}t|}tj||d 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')]) ['2017', '2018'] Length: 2, dtype: period[Y-DEC] >>> period_array([pd.Period('2017', freq='Y'), ... pd.Period('2018', freq='Y'), ... pd.NaT]) ['2017', '2018', 'NaT'] Length: 3, dtype: period[Y-DEC] Integers that look like years are handled >>> period_array([2000, 2001, 2002], freq='D') ['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') ['2000Q1', '2000Q2', '2000Q3', '2000Q4'] Length: 4, dtype: period[Q-DEC] rGNrrPrz9PeriodIndex does not allow floating point in constructioniuFrr)rr rrArrVr+rcrzrrrtupler.rrGkindrrr rr from_ordinalsr(rr) rrcr~ data_dtypeoutarrdatarGarrrrNrNrO period_arrays6 :           rUcCdSrFrNrrNrNrOrir]rtimedelta | str | NonercCrVrFrNrrNrNrOrnr]1BaseOffsetT | BaseOffset | timedelta | str | NonecCs^|dur t|dd}|dur-t|}t|tstd|dur$|j}|S||jkr-td|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_periodzdtype must be PeriodDtypez&specified freq and dtype are different)rr)rVr+rrcr!rrNrNrOrss   (tuple[npt.NDArray[np.int64], BaseOffset]cCst|jtjr |jjdkrtd|j|dur4t|tr&|j|j}}nt|tr3|j|j j}}n t|ttfr>|j}t |j}t |}|j }t|d|||d|fS)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. rz Wrong dtype: Nr)reso)rVrGrrOrr,rrcr.dtrr"rrc_dt64arr_to_periodarrr)rrcrr\rKrNrNrOrs    rrmultintcCsZt|||dkr td|durt|dd}|j}|dur#t||}|dur,t||}t|t}t|t}|rD|rD|j|jkrDtd|tusL|turPtd|durg|rZ|j}n |r`|j}ntd|j}|dur||}|durt j |j |||j d|t j d }||fSt j |j |j ||t j d }||fSt j |j |j d|t j d }||fS) NzOOf the three parameters: start, end, and periods, exactly two must be specifiedTrYz!start and end must have same freqzstart and end must not be NaTz#Could not infer freq from start/endrr) comcount_not_nonerrrr"rVrcrrarangerr)rrrrcr_ is_start_per is_end_perrrNrNrOrsJ      rtuple[np.ndarray, BaseOffset]cCsZ|durd}|dur d}|durd}|durd}g}|durr|dur-tddd}tjj} nt|dd}t|} | tjjkrBtd|j} t||\}}t ||D]\} } t | | | \} }t | |dddddd| }| |qQn1t|dd}t|} t||||||}t |D]\} }}}}}| t | |||||dd| qtj|tjd|fS)NrrQTrYzbase must equal FR_QTRr)rrFR_QTRrrfreq_to_dtype_codeAssertionErrorr_make_field_arraysziprquarter_to_myearperiod_ordinalappendrrr)rerfrrrgrhrirjrcrrKryq calendar_yearcalendar_monthvalarraysmthdhmnsrNrNrOrs@         "rlist[np.ndarray]cs^d|D]!}t|ttjtfr%durt|krtddur%t|qfdd|DS)NzMismatched Period array lengthscs4g|]}t|tjttfrt|nt|qSrN)rVrrrr.rrepeat).0rWlengthrNrO .s  z&_make_field_arrays..)rVrrrr.rr)rrWrNrrOrl"s rlrF)rBrCrDrE)rYr!)NF)rrKrcrLr~rrYrA)rcr>rYr>)rcrWrYr)rcrXrYr>)rYr[)r)r_r`)NNNNNNNN)rYrg)rYr|)h __future__rdatetimerr%typingrrrrrr r rnumpyr pandas._libsr rr pandas._libs.arraysr pandas._libs.tslibsrrrrrrrr^rrrrrrpandas._libs.tslibs.dtypesrrrpandas._libs.tslibs.fieldsrpandas._libs.tslibs.offsetsrrpandas._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.r/pandas.core.dtypes.missingr0rr1rpandas.core.commoncorecommonrbcollections.abcr2pandas._typingr3r4r5r6r7r8r9r:r;r<pandas.core.arrays.baser=r>rErT DatelikeOps PeriodMixinrArrUrrrrlrNrNrNrOsv $  8     (     o& c   & (2 1