from __future__ import annotations from datetime import timedelta import operator from typing import ( TYPE_CHECKING, Any, Literal, Self, TypeVar, cast, ) import warnings import numpy as np from pandas._libs import ( algos as libalgos, lib, ) from pandas._libs.arrays import NDArrayBacked from pandas._libs.tslibs import ( BaseOffset, Day, NaT, NaTType, Resolution, Timedelta, add_overflowsafe, astype_overflowsafe, dt64arr_to_periodarr as c_dt64arr_to_periodarr, get_unit_from_dtype, iNaT, parsing, period as libperiod, to_offset, ) from pandas._libs.tslibs.ccalendar import MONTH_NUMBERS from pandas._libs.tslibs.dtypes import ( FreqGroup, PeriodDtypeBase, ) from pandas._libs.tslibs.offsets import ( Tick, delta_to_tick, ) from pandas._libs.tslibs.period import ( DIFFERENT_FREQ, INT_TO_PERIOD_DEPR_MSG, IncompatibleFrequency, Period, get_period_field_arr, period_asfreq_arr, ) from pandas.errors import Pandas4Warning from pandas.util._decorators import ( cache_readonly, set_module, ) from pandas.util._exceptions import find_stack_level from pandas.core.dtypes.common import ( ensure_object, pandas_dtype, ) from pandas.core.dtypes.dtypes import ( DatetimeTZDtype, PeriodDtype, ) from pandas.core.dtypes.generic import ( ABCIndex, ABCPeriodIndex, ABCSeries, ABCTimedeltaArray, ) from pandas.core.dtypes.missing import isna from pandas.core.arrays import ( ExtensionArray, datetimelike as dtl, ) import pandas.core.common as com from pandas.core.construction import extract_array if TYPE_CHECKING: from collections.abc import ( Callable, Sequence, ) from pandas._typing import ( AnyArrayLike, Dtype, DtypeObj, FillnaOptions, NpDtype, NumpySorter, NumpyValueArrayLike, npt, ) from pandas.core.dtypes.dtypes import ExtensionDtype from pandas.core.arrays import ( DatetimeArray, TimedeltaArray, ) BaseOffsetT = TypeVar("BaseOffsetT", bound=BaseOffset) def _field_accessor(name: str, docstring: str | None = None): def f(self): base = self.dtype._dtype_code result = get_period_field_arr(name, self.asi8, base) return result f.__name__ = name f.__doc__ = docstring return property(f) @set_module("pandas.arrays") class PeriodArray(dtl.DatelikeOps, libperiod.PeriodMixin): """ 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. 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] """ # array priority higher than numpy scalars __array_priority__ = 1000 _typ = "periodarray" # ABCPeriodArray _internal_fill_value = np.int64(iNaT) _recognized_scalars = (Period,) _is_recognized_dtype: Callable[[DtypeObj], bool] = lambda x: isinstance( x, PeriodDtype ) # check_compatible_with checks freq match @property def _scalar_type(self) -> type[Period]: return Period # Names others delegate to us _other_ops: list[str] = [] _bool_ops: list[str] = ["is_leap_year"] _object_ops: list[str] = ["start_time", "end_time", "freq"] _field_ops: list[str] = [ "year", "month", "day", "hour", "minute", "second", "weekofyear", "week", "day_of_week", "day_of_year", "quarter", "qyear", "days_in_month", ] _datetimelike_ops: list[str] = _field_ops + _object_ops + _bool_ops _datetimelike_methods: list[str] = ["strftime", "to_timestamp", "asfreq"] _dtype: PeriodDtype # -------------------------------------------------------------------- # Constructors def __init__(self, values, dtype: Dtype | None = None, copy: bool = False) -> None: if dtype is not None: dtype = pandas_dtype(dtype) if not isinstance(dtype, PeriodDtype): raise ValueError(f"Invalid dtype {dtype} for PeriodArray") if isinstance(values, ABCSeries): values = values._values if not isinstance(values, type(self)): raise TypeError("Incorrect dtype") elif isinstance(values, ABCPeriodIndex): values = values._values if isinstance(values, type(self)): if dtype is not None and dtype != values.dtype: raise raise_on_incompatible(values, dtype.freq) values, dtype = values._ndarray, values.dtype if not copy: values = np.asarray(values, dtype="int64") else: values = np.array(values, dtype="int64", copy=copy) if dtype is None: raise ValueError("dtype is not specified and cannot be inferred") dtype = cast("PeriodDtype", dtype) NDArrayBacked.__init__(self, values, dtype) # error: Signature of "_simple_new" incompatible with supertype "NDArrayBacked" @classmethod def _simple_new( # type: ignore[override] cls, values: npt.NDArray[np.int64], dtype: PeriodDtype, ) -> Self: # alias for PeriodArray.__init__ assertion_msg = "Should be numpy array of type i8" assert isinstance(values, np.ndarray) and values.dtype == "i8", assertion_msg return cls(values, dtype=dtype) @classmethod def _from_sequence( cls, scalars, *, dtype: Dtype | None = None, copy: bool = False, ) -> Self: if dtype is not None: dtype = pandas_dtype(dtype) # Note: we can't do extract_array until after from_datetime64 path # bc of GH#64241 data_dtype = getattr(scalars, "dtype", None) if lib.is_np_dtype(data_dtype, "M"): freq = dtype._freq if dtype is not None else None # type: ignore[union-attr] return cls._from_datetime64(scalars, freq) scalars = extract_array(scalars, extract_numpy=True) if isinstance(scalars, cls): if dtype is not None: return scalars.astype(dtype, copy=copy) elif copy: return scalars.copy() return scalars if not isinstance( scalars, (np.ndarray, list, tuple, ABCSeries, ABCIndex, ExtensionArray) ): # test_constructor_empty_special has a case with an iter object scalars = list(scalars) if isinstance(scalars, ExtensionArray) and scalars.dtype.kind in "iu": # e.g. masked or arrow-backed integer array; np.asarray would cast # integers-with-NA to float and raise a misleading "floating point" # error below, so route through object dtype to keep the integers. scalars = scalars.to_numpy(dtype=object, na_value=NaT) arrdata = np.asarray(scalars) if ( arrdata.dtype.kind == "u" and arrdata.size and arrdata.max() > np.iinfo(np.int64).max ): # GH#64231 the int64 cast below would wrap these silently; read # them through the object path, which rejects them the way the # Period(int) scalar constructor does. arrdata = arrdata.astype(object) if arrdata.dtype.kind == "f" and len(arrdata) > 0: if not lib.all_nans(arrdata): raise TypeError( "PeriodArray does not allow floating point in construction" ) ordinals = np.full(arrdata.shape, iNaT, dtype=np.int64) return cls(ordinals, dtype=dtype) elif arrdata.dtype.kind in "iu": # GH#64227 enforcing means dropping from_calendar_ordinals here and # reading arrdata as ordinals; the object-dtype and Period-scalar # paths in tslibs.period must be enforced at the same time or the # two interpretations diverge again. warnings.warn( INT_TO_PERIOD_DEPR_MSG, Pandas4Warning, stacklevel=find_stack_level(), ) arr = arrdata.astype(np.int64, copy=False) ordinals = libperiod.from_calendar_ordinals(arr, dtype) # type: ignore[arg-type] return cls(ordinals, dtype=dtype) else: periods = ensure_object(arrdata) if dtype is None: dtype_base = libperiod.extract_period_unit(periods) dtype = PeriodDtype(dtype_base) ordinals = libperiod.extract_ordinals(periods, dtype) # type: ignore[arg-type] return cls(ordinals, dtype=dtype) @classmethod def _from_sequence_of_strings( cls, strings, *, dtype: ExtensionDtype, copy: bool = False ) -> Self: return cls._from_sequence(strings, dtype=dtype, copy=copy) @classmethod def _from_datetime64(cls, data, freq, tz=None) -> Self: """ 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] """ if isinstance(freq, BaseOffset): freq = PeriodDtype(freq)._freqstr data, freq = dt64arr_to_periodarr(data, freq, tz) dtype = PeriodDtype(freq) return cls(data, dtype=dtype) @classmethod def _generate_range(cls, start, end, periods, freq): periods = dtl.validate_periods(periods) if freq is not None: freq = Period._maybe_convert_freq(freq) if start is not None or end is not None: subarr, freq = _get_ordinal_range(start, end, periods, freq) else: raise ValueError("Not enough parameters to construct Period range") return subarr, freq @classmethod def _from_fields(cls, *, fields: dict[str, Any], freq) -> Self: subarr, freq = _range_from_fields(freq=freq, **fields) dtype = PeriodDtype(freq) return cls._simple_new(subarr, dtype=dtype) # ----------------------------------------------------------------- # DatetimeLike Interface def _unbox_scalar( self, # error: Argument 1 of "_unbox_scalar" is incompatible with supertype # "pandas.core.arrays.datetimelike.DatetimeLikeArrayMixin"; supertype # defines the argument type as "Period | Timestamp | Timedelta | NaTType" value: Period | NaTType, # type: ignore[override] ) -> np.int64: if value is NaT: return np.int64(value._value) elif isinstance(value, self._scalar_type): self._check_compatible_with(value) return np.int64(value.ordinal) else: raise ValueError(f"'value' should be a Period. Got '{value}' instead.") def _scalar_from_string(self, value: str) -> Period: return Period(value, freq=self.freq) def _check_compatible_with( self, # error: Argument 1 of "_check_compatible_with" is incompatible with # supertype "pandas.core.arrays.datetimelike.DatetimeLikeArrayMixin"; # supertype defines the argument type as "Period | Timestamp | Timedelta # | NaTType" other: Period | NaTType | PeriodArray, # type: ignore[override] ) -> None: if other is NaT: return elif isinstance(other, Period): self._require_matching_unit(other._dtype._freqstr) else: # error: Item "NaTType" of "NaTType | PeriodArray" has no # attribute "freq" self._require_matching_unit(other.dtype._freqstr) # type: ignore[union-attr] # -------------------------------------------------------------------- # Data / Attributes @cache_readonly def dtype(self) -> PeriodDtype: return self._dtype @property def freq(self) -> BaseOffset: """ Return the frequency object for this PeriodArray. """ return self.dtype.freq @property def freqstr(self) -> str: return PeriodDtype(self.freq)._freqstr @property # NB: override with cache_readonly in immutable subclasses def _resolution_obj(self) -> Resolution: freqstr = self.freqstr try: return Resolution.get_reso_from_freqstr(freqstr) except KeyError: return None # type: ignore[return-value] def __array__( self, dtype: NpDtype | None = None, copy: bool | None = None ) -> np.ndarray: if dtype == "i8": # For NumPy 1.x compatibility we cannot use copy=None. And # `copy=False` has the meaning of `copy=None` here: if not copy: result = np.asarray(self.asi8, dtype=dtype) if self._readonly: result = result.view() result.flags.writeable = False return result else: return np.array(self.asi8, dtype=dtype) if copy is False: raise ValueError( "Unable to avoid copy while creating an array as requested." ) if dtype == bool: return ~self._isnan # This will raise TypeError for non-object dtypes return np.array(list(self), dtype=object) def __arrow_array__(self, type=None): """ Convert myself into a pyarrow Array. """ import pyarrow from pandas.core.arrays.arrow.extension_types import ArrowPeriodType if type is not None: if pyarrow.types.is_integer(type): return pyarrow.array(self._ndarray, mask=self.isna(), type=type) elif isinstance(type, ArrowPeriodType): # ensure we have the same freq if self.freqstr != type.freq: raise TypeError( "Not supported to convert PeriodArray to array with different " f"'freq' ({self.freqstr} vs {type.freq})" ) else: raise TypeError( f"Not supported to convert PeriodArray to '{type}' type" ) period_type = ArrowPeriodType(self.freqstr) storage_array = pyarrow.array(self._ndarray, mask=self.isna(), type="int64") return pyarrow.ExtensionArray.from_storage(period_type, storage_array) # -------------------------------------------------------------------- # Vectorized analogues of Period properties year = _field_accessor( "year", """ The year of the period. Returns the year component for each period in the index. See Also -------- PeriodIndex.day_of_year : The ordinal day of the year. PeriodIndex.dayofyear : The ordinal day of the year. PeriodIndex.is_leap_year : Logical indicating if the date belongs to a leap year. PeriodIndex.weekofyear : The week ordinal of the year. PeriodIndex.year : The year of the period. Examples -------- >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y") >>> idx.year Index([2023, 2024, 2025], dtype='int64') """, ) month = _field_accessor( "month", """ The month as January=1, December=12. Returns the month component for each period in the index as an integer, where January is 1 and December is 12. See Also -------- PeriodIndex.days_in_month : The number of days in the month. PeriodIndex.daysinmonth : The number of days in the month. Examples -------- >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M") >>> idx.month Index([1, 2, 3], dtype='int64') """, ) day = _field_accessor( "day", """ The days of the period. Returns the day-of-month component for each period in the index. See Also -------- PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6. PeriodIndex.day_of_year : The ordinal day of the year. PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6. PeriodIndex.dayofyear : The ordinal day of the year. PeriodIndex.days_in_month : The number of days in the month. PeriodIndex.daysinmonth : The number of days in the month. PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6. Examples -------- >>> idx = pd.PeriodIndex(['2020-01-31', '2020-02-28'], freq='D') >>> idx.day Index([31, 28], dtype='int64') """, ) hour = _field_accessor( "hour", """ The hour of the period. Returns the hour component for each period in the index. See Also -------- PeriodIndex.minute : The minute of the period. PeriodIndex.second : The second of the period. PeriodIndex.to_timestamp : Cast to DatetimeArray/Index. Examples -------- >>> idx = pd.PeriodIndex(["2023-01-01 10:00", "2023-01-01 11:00"], freq='h') >>> idx.hour Index([10, 11], dtype='int64') """, ) minute = _field_accessor( "minute", """ The minute of the period. Returns the minute component for each period in the index. See Also -------- PeriodIndex.hour : The hour of the period. PeriodIndex.second : The second of the period. PeriodIndex.to_timestamp : Cast to DatetimeArray/Index. 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') """, ) second = _field_accessor( "second", """ The second of the period. Returns the second component for each period in the index. See Also -------- PeriodIndex.hour : The hour of the period. PeriodIndex.minute : The minute of the period. PeriodIndex.to_timestamp : Cast to DatetimeArray/Index. 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') """, ) weekofyear = _field_accessor( "week", """ The week ordinal of the year. Returns the week number (1 through 53) for each period in the index. See Also -------- PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6. PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6. PeriodIndex.week : The week ordinal of the year. PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6. PeriodIndex.year : The year of the period. 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') """, ) week = weekofyear day_of_week = _field_accessor( "day_of_week", """ The day of the week with Monday=0, Sunday=6. Returns the day-of-week component for each period, following the Python convention where Monday is 0 and Sunday is 6. See Also -------- PeriodIndex.day : The days of the period. PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6. PeriodIndex.day_of_year : The ordinal day of the year. PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6. PeriodIndex.dayofyear : The ordinal day of the year. PeriodIndex.week : The week ordinal of the year. PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6. PeriodIndex.weekofyear : The week ordinal of the year. Examples -------- >>> idx = pd.PeriodIndex(["2023-01-01", "2023-01-02", "2023-01-03"], freq="D") >>> idx.day_of_week Index([6, 0, 1], dtype='int64') """, ) @property def weekday(self): """ The day of the week with Monday=0, Sunday=6. .. deprecated:: 3.1.0 Use :attr:`PeriodArray.day_of_week` instead. """ # GH#12816 warnings.warn( "PeriodArray.weekday is deprecated and will be removed " "in a future version. Use PeriodArray.day_of_week instead.", Pandas4Warning, stacklevel=find_stack_level(), ) return self.day_of_week @property def dayofweek(self): """ The day of the week with Monday=0, Sunday=6. .. deprecated:: 3.1.0 Use :attr:`PeriodArray.day_of_week` instead. """ warnings.warn( "PeriodArray.dayofweek is deprecated and will be removed in a " "future version. Use PeriodArray.day_of_week instead.", Pandas4Warning, stacklevel=find_stack_level(), ) return self.day_of_week day_of_year = _field_accessor( "day_of_year", """ The ordinal day of the year. Returns the day-of-year component for each period, ranging from 1 (January 1st) to 365 or 366 for leap years. See Also -------- PeriodIndex.day : The days of the period. PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6. PeriodIndex.day_of_year : The ordinal day of the year. PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6. PeriodIndex.dayofyear : The ordinal day of the year. PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6. PeriodIndex.weekofyear : The week ordinal of the year. PeriodIndex.year : The year of the period. Examples -------- >>> idx = pd.PeriodIndex(["2023-01-10", "2023-02-01", "2023-03-01"], freq="D") >>> idx.day_of_year Index([10, 32, 60], dtype='int64') >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y") >>> idx PeriodIndex(['2023', '2024', '2025'], dtype='period[Y-DEC]') >>> idx.day_of_year Index([365, 366, 365], dtype='int64') """, ) @property def dayofyear(self): """ The ordinal day of the year. .. deprecated:: 3.1.0 Use :attr:`PeriodArray.day_of_year` instead. """ warnings.warn( "PeriodArray.dayofyear is deprecated and will be removed in a " "future version. Use PeriodArray.day_of_year instead.", Pandas4Warning, stacklevel=find_stack_level(), ) return self.day_of_year quarter = _field_accessor( "quarter", """ The quarter of the date. Returns the quarter (1 through 4) for each period in the index. See Also -------- PeriodIndex.qyear : Fiscal year the Period lies in according to its starting-quarter. Examples -------- >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M") >>> idx.quarter Index([1, 1, 1], dtype='int64') """, ) qyear = _field_accessor( "qyear", """ Fiscal year the Period lies in according to its starting-quarter. The `year` and the `qyear` of the period will be the same if the fiscal and calendar years are the same. When they are not, the fiscal year can be different from the calendar year of the period. Returns ------- int The fiscal year of the period. See Also -------- PeriodIndex.quarter : The quarter of the date. PeriodIndex.year : The year of the period. Examples -------- If the natural and fiscal year are the same, `qyear` and `year` will be the same. >>> per = pd.Period('2018Q1', freq='Q') >>> per.qyear 2018 >>> per.year 2018 If the fiscal year starts in April (`Q-MAR`), the first quarter of 2018 will start in April 2017. `year` will then be 2017, but `qyear` will be the fiscal year, 2018. >>> per = pd.Period('2018Q1', freq='Q-MAR') >>> per.start_time Timestamp('2017-04-01 00:00:00') >>> per.qyear 2018 >>> per.year 2017 """, ) days_in_month = _field_accessor( "days_in_month", """ The number of days in the month. Returns the total number of days in the month of each period, accounting for leap years. See Also -------- PeriodIndex.day : The days of the period. PeriodIndex.days_in_month : The number of days in the month. PeriodIndex.daysinmonth : The number of days in the month. PeriodIndex.month : The month as January=1, December=12. 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') """, ) @property def daysinmonth(self): """ The number of days in the month. .. deprecated:: 3.1.0 Use :attr:`PeriodArray.days_in_month` instead. """ warnings.warn( "PeriodArray.daysinmonth is deprecated and will be removed in a " "future version. Use PeriodArray.days_in_month instead.", Pandas4Warning, stacklevel=find_stack_level(), ) return self.days_in_month @property def is_leap_year(self) -> npt.NDArray[np.bool_]: """ Logical indicating if the date belongs to a leap year. Returns a boolean array where ``True`` indicates the period's year is a leap year. See Also -------- PeriodIndex.qyear : Fiscal year the Period lies in according to its starting-quarter. PeriodIndex.year : The year of the period. Examples -------- >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y") >>> idx.is_leap_year array([False, True, False]) """ # NaT gives year == -1, which the modulo below reports as not-leap year = np.asarray(self.year) return (year % 400 == 0) | ((year % 4 == 0) & (year % 100 > 0)) def to_timestamp(self, freq=None, how: str = "start") -> DatetimeArray: """ Cast to DatetimeArray/Index. If possible, gives microsecond-unit DatetimeArray/Index. Otherwise gives nanosecond unit. On the ``Series.dt`` accessor, this is only available for period-typed Series. Parameters ---------- freq : str or DateOffset, optional Target frequency. The default is 'D' for week or longer, 's' otherwise. how : {'start', 'end', 's', 'e'}, default 'start' Whether to use the start or end of the time period being converted. Case-insensitive. Returns ------- DatetimeArray/Index Timestamp representation of given Period-like object. See Also -------- PeriodIndex.day : The days of the period. PeriodIndex.from_fields : Construct a PeriodIndex from fields (year, month, day, etc.). PeriodIndex.from_ordinals : Construct a PeriodIndex from ordinals. PeriodIndex.hour : The hour of the period. PeriodIndex.minute : The minute of the period. PeriodIndex.month : The month as January=1, December=12. PeriodIndex.second : The second of the period. PeriodIndex.year : The year of the period. 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[us]', freq='MS') The frequency will not be inferred if the index contains less than three elements, or if the values of index are not strictly monotonic: >>> idx = pd.PeriodIndex(["2023-01", "2023-02"], freq="M") >>> idx.to_timestamp() DatetimeIndex(['2023-01-01', '2023-02-01'], dtype='datetime64[us]', freq=None) >>> idx = pd.PeriodIndex( ... ["2023-01", "2023-02", "2023-02", "2023-03"], freq="2M" ... ) >>> idx.to_timestamp() DatetimeIndex(['2023-01-01', '2023-02-01', '2023-02-01', '2023-03-01'], dtype='datetime64[us]', freq=None) """ from pandas.core.arrays import DatetimeArray how = libperiod.validate_end_alias(how) end = how == "E" if end: if freq is not None: # GH#63760 normalize so e.g. "1ns" is recognized as nanosecond freq = Period._maybe_convert_freq(freq) ns_target = freq is not None and freq.base == "ns" if freq == "B" or self.freq == "B": # roll forward to ensure we land on B date stamp = self.to_timestamp(how="start") unit = "ns" if ns_target else stamp.unit adjust = Timedelta(1, unit="D") - Timedelta(1, unit=unit) return stamp + adjust else: stamp = (self + self.freq).to_timestamp(how="start") unit = "ns" if ns_target else stamp.unit return stamp - Timedelta(1, unit=unit) if freq is None: freq_code = self._dtype._get_to_timestamp_base() dtype = PeriodDtypeBase(freq_code, 1) freq = dtype._freqstr base = freq_code else: freq = Period._maybe_convert_freq(freq) base = freq._period_dtype_code new_parr = self.asfreq(freq, how=how) new_data = libperiod.periodarr_to_dt64arr(new_parr.asi8, base) # GH#63760 periodarr_to_dt64arr gives nanoseconds only for the # nanosecond target base and microseconds otherwise, so new_data # already carries the correct resolution. dta = DatetimeArray._from_sequence(new_data, dtype=new_data.dtype) return dta def _to_timestamp_freq( self, dta: DatetimeArray, target_freq, how: str ) -> BaseOffset | None: """ Determine the freq to stamp on the DatetimeArray returned by ``self.to_timestamp(target_freq, how)``. Called by ``PeriodIndex.to_timestamp`` so the array-level ``to_timestamp`` can return a bare DatetimeArray. """ how = libperiod.validate_end_alias(how) if how == "E": # For the "end" case, to_timestamp routes through arithmetic that # does not preserve freq; match that behavior here. return None if self.freq.rule_code == "B": # See if we can retain BDay instead of Day in cases where # len(self) is too small for infer_freq to distinguish between them diffs = libalgos.unique_deltas(self.asi8) if len(diffs) == 1: diff = diffs[0] if diff == self.dtype._n: return self.freq elif diff == 1: return self.freq.base # TODO: other cases? return None result_freq = to_offset(dta._inferred_freq_str) if target_freq is not None: # match the normalization applied in to_timestamp target_freq = Period._maybe_convert_freq(target_freq) if ( isinstance(result_freq, Day) and not isinstance(target_freq, Day) and Timedelta(target_freq) == Timedelta(days=result_freq.n) ): result_freq = target_freq return result_freq # -------------------------------------------------------------------- def _box_func(self, x) -> Period | NaTType: return Period._from_ordinal(ordinal=x, dtype=self.dtype) def asfreq(self, freq=None, how: str = "E") -> Self: """ Convert the PeriodArray to the specified frequency `freq`. Equivalent to applying :meth:`pandas.Period.asfreq` with the given arguments to each :class:`~pandas.Period` in this PeriodArray. Parameters ---------- freq : str A frequency. how : {'end', 'start', 'e', 's'}, default 'end' Whether the elements should be aligned to the end or start of each period, e.g. January 31st vs. January 1st. Case-insensitive. Returns ------- PeriodArray The transformed PeriodArray with the new frequency. See Also -------- PeriodIndex.asfreq: Convert each Period in a PeriodIndex 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]') """ how = libperiod.validate_end_alias(how) if isinstance(freq, BaseOffset) and hasattr(freq, "_period_dtype_code"): freq = PeriodDtype(freq)._freqstr freq = Period._maybe_convert_freq(freq) base1 = self._dtype._dtype_code base2 = freq._period_dtype_code asi8 = self.asi8 # self.freq.n can't be negative or 0 end = how == "E" if end: ordinal = asi8 + self.dtype._n - 1 else: ordinal = asi8 new_data = period_asfreq_arr(ordinal, base1, base2, end) if self._hasna: new_data[self._isnan] = iNaT dtype = PeriodDtype(freq) return type(self)(new_data, dtype=dtype) # ------------------------------------------------------------------ # Rendering Methods def _formatter(self, boxed: bool = False) -> Callable[[object], str]: if boxed: return str return "'{}'".format def _format_native_types( self, *, na_rep: str | float = "NaT", date_format=None, **kwargs ) -> npt.NDArray[np.object_]: """ actually format my specific types """ return libperiod.period_array_strftime( self.asi8, self.dtype._dtype_code, na_rep, date_format ) # ------------------------------------------------------------------ def astype(self, dtype, copy: bool = True): # We handle Period[T] -> Period[U] # Our parent handles everything else. dtype = pandas_dtype(dtype) if dtype == self._dtype: if not copy: return self else: return self.copy() if isinstance(dtype, PeriodDtype): return self.asfreq(dtype.freq) if lib.is_np_dtype(dtype, "M") or isinstance(dtype, DatetimeTZDtype): # GH#45038 match PeriodIndex behavior. tz = getattr(dtype, "tz", None) unit = dtl.dtype_to_unit(dtype) # error: Argument 1 to "as_unit" of "TimelikeOps" has incompatible # type "str"; expected "Literal['s', 'ms', 'us', 'ns']" [arg-type] return self.to_timestamp().tz_localize(tz).as_unit(unit) # type: ignore[arg-type] return super().astype(dtype, copy=copy) def searchsorted( self, value: NumpyValueArrayLike | ExtensionArray, side: Literal["left", "right"] = "left", sorter: NumpySorter | None = None, ) -> npt.NDArray[np.intp] | np.intp: npvalue = self._validate_setitem_value(value).view("M8[ns]") # Cast to M8 to get datetime-like NaT placement, # similar to dtl._period_dispatch m8arr = self._ndarray.view("M8[ns]") return m8arr.searchsorted(npvalue, side=side, sorter=sorter) def _pad_or_backfill( self, *, method: FillnaOptions, limit: int | None = None, limit_area: Literal["inside", "outside"] | None = None, copy: bool = True, ) -> Self: # view as dt64 so we get treated as timelike in core.missing, # similar to dtl._period_dispatch dta = self.view("M8[ns]") result = dta._pad_or_backfill( method=method, limit=limit, limit_area=limit_area, copy=copy ) if copy: return cast("Self", result.view(self.dtype)) else: return self # ------------------------------------------------------------------ # Arithmetic Methods def _addsub_int_array_or_scalar( self, other: np.ndarray | int, op: Callable[[Any, Any], Any] ) -> Self: """ Add or subtract array of integers. Parameters ---------- other : np.ndarray[int64] or int op : {operator.add, operator.sub} Returns ------- result : PeriodArray """ assert op in [operator.add, operator.sub] if op is operator.sub: other = -other res_values = add_overflowsafe(self.asi8, np.asarray(other, dtype="i8")) return type(self)(res_values, dtype=self.dtype) def _add_offset(self, other: BaseOffset): assert not isinstance(other, Tick) if isinstance(other, Day): return self + np.timedelta64(other.n, "D") self._require_matching_unit(other._period_unit, base=True) return self._addsub_int_array_or_scalar(other.n, operator.add) # TODO: can we de-duplicate with Period._add_timedeltalike_scalar? def _add_timedeltalike_scalar(self, other): """ Parameters ---------- other : timedelta, Tick, np.timedelta64 Returns ------- PeriodArray """ if not isinstance(self.freq, (Tick, Day)): # We cannot add timedelta-like to non-tick PeriodArray raise raise_on_incompatible(self, other) if isna(other): # i.e. np.timedelta64("NaT") return super()._add_timedeltalike_scalar(other) if isinstance(other, Day): td = np.asarray(Timedelta(days=other.n).asm8) else: td = np.asarray(Timedelta(other).asm8) return self._add_timedelta_arraylike(td) def _add_timedelta_arraylike( self, other: TimedeltaArray | npt.NDArray[np.timedelta64] ) -> Self: """ Parameters ---------- other : TimedeltaArray or ndarray[timedelta64] Returns ------- PeriodArray """ if not self.dtype._is_tick_like(): # We cannot add timedelta-like to non-tick PeriodArray raise TypeError( f"Cannot add or subtract timedelta64[ns] dtype from {self.dtype}" ) dtype = np.dtype(f"m8[{self.dtype._td64_unit}]") # Similar to _check_timedeltalike_freq_compat, but we raise with a # more specific exception message if necessary. try: delta = astype_overflowsafe( np.asarray(other), dtype=dtype, copy=False, round_ok=False ) except ValueError as err: # e.g. if we have minutes freq and try to add 30s # "Cannot losslessly convert units" raise IncompatibleFrequency( "Cannot add/subtract timedelta-like from PeriodArray that is " "not an integer multiple of the PeriodArray's freq." ) from err res_values = add_overflowsafe(self.asi8, np.asarray(delta.view("i8"))) return type(self)(res_values, dtype=self.dtype) def _check_timedeltalike_freq_compat(self, other): """ 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 """ assert self.dtype._is_tick_like() # checked by calling function dtype = np.dtype(f"m8[{self.dtype._td64_unit}]") if isinstance(other, (timedelta, np.timedelta64, Tick)): td = np.asarray(Timedelta(other).asm8) else: td = np.asarray(other) try: delta = astype_overflowsafe(td, dtype=dtype, copy=False, round_ok=False) except ValueError as err: raise raise_on_incompatible(self, other) from err delta = delta.view("i8") return lib.item_from_zerodim(delta) # ------------------------------------------------------------------ # Reductions def _reduce( self, name: str, *, skipna: bool = True, keepdims: bool = False, **kwargs ): result = super()._reduce(name, skipna=skipna, keepdims=keepdims, **kwargs) if keepdims and isinstance(result, np.ndarray): return self._from_sequence(result, dtype=self.dtype) return result def raise_on_incompatible(left, right) -> IncompatibleFrequency: """ 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. """ # GH#24283 error message format depends on whether right is scalar if isinstance(right, (np.ndarray, ABCTimedeltaArray)) or right is None: other_freq = None elif isinstance(right, BaseOffset): with warnings.catch_warnings(): warnings.filterwarnings( "ignore", r"PeriodDtype\[B\] is deprecated", category=FutureWarning ) other_freq = PeriodDtype(right)._freqstr elif isinstance(right, (ABCPeriodIndex, PeriodArray, Period)): other_freq = right.freqstr else: other_freq = delta_to_tick(Timedelta(right)).freqstr own_freq = PeriodDtype(left.freq)._freqstr msg = DIFFERENT_FREQ.format( cls=type(left).__name__, own_freq=own_freq, other_freq=other_freq ) return IncompatibleFrequency(msg) # ------------------------------------------------------------------- # Constructor Helpers def period_array( data: Sequence[Period | str | None] | AnyArrayLike, dtype: PeriodDtype | None = None, ) -> PeriodArray: """ 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``. dtype : PeriodDtype or None, default None The dtype for the array. If not specified, is inferred from the data. 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] Datetime-like strings may also be passed >>> period_array( ... ["2000-Q1", "2000-Q2", "2000-Q3", "2000-Q4"], dtype=PeriodDtype("Q") ... ) ['2000Q1', '2000Q2', '2000Q3', '2000Q4'] Length: 4, dtype: period[Q-DEC] """ return PeriodArray._from_sequence(data, dtype=dtype) def validate_dtype_freq( dtype: DtypeObj | None, dtype2: DtypeObj | None ) -> PeriodDtype | None: """ If a dtype is specified both directly and indirectly via a `freq` (dtype2), ensure they match. If only the latter is available, return the indirect dtype. Parameters ---------- dtype : dtype dtype2 : PeriodDtype or None Dtype derived from a `freq` passed to the caller. Returns ------- PeriodDtype or None Raises ------ ValueError : non-period dtype IncompatibleFrequency : mismatch between dtype and freq """ if dtype is not None: if not isinstance(dtype, PeriodDtype): raise ValueError("dtype must be PeriodDtype") if dtype2 is not None and dtype != dtype2: raise IncompatibleFrequency("specified freq and dtype are different") elif dtype2 is not None: if not isinstance(dtype2, PeriodDtype): raise ValueError("dtype must be PeriodDtype") dtype = dtype2 return dtype def dt64arr_to_periodarr( data, freq, tz=None ) -> tuple[npt.NDArray[np.int64], BaseOffset]: """ Convert a 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. """ if not isinstance(data.dtype, np.dtype) or data.dtype.kind != "M": raise ValueError(f"Wrong dtype: {data.dtype}") if freq is None: if isinstance(data, ABCIndex): data, freq = data._values, data.freq elif isinstance(data, ABCSeries): # freq is always None for DatetimeArray inside a Series, so we # fall back to the inferred freq. inferred_freq = data._values._inferred_freq_str if inferred_freq is not None: warnings.warn( "Constructing PeriodArray from a Series of datetime64 data " "will stop inferring the frequency in a future version. " "Pass `freq` explicitly instead.", Pandas4Warning, stacklevel=find_stack_level(), ) freq = inferred_freq data = data._values elif isinstance(data, (ABCIndex, ABCSeries)): data = data._values reso = get_unit_from_dtype(data.dtype) freq = Period._maybe_convert_freq(freq) base = freq._period_dtype_code return c_dt64arr_to_periodarr(data.view("i8"), base, tz, reso=reso), freq def _get_ordinal_range(start, end, periods, freq, mult: int = 1): if com.count_not_none(start, end, periods) != 2: raise ValueError( "Of the three parameters: start, end, and periods, " "exactly two must be specified" ) if freq is not None: freq = to_offset(freq, is_period=True) mult = freq.n if start is not None: start = Period(start, freq) if end is not None: end = Period(end, freq) is_start_per = isinstance(start, Period) is_end_per = isinstance(end, Period) if is_start_per and is_end_per and start.freq != end.freq: raise ValueError("start and end must have same freq") if start is NaT or end is NaT: raise ValueError("start and end must not be NaT") if freq is None: if is_start_per: freq = start.freq elif is_end_per: freq = end.freq else: # pragma: no cover raise ValueError("Could not infer freq from start/end") mult = freq.n if periods is not None: periods = periods * mult if start is None: data = np.arange( end.ordinal - periods + mult, end.ordinal + 1, mult, dtype=np.int64 ) else: data = np.arange( start.ordinal, start.ordinal + periods, mult, dtype=np.int64 ) else: data = np.arange(start.ordinal, end.ordinal + 1, mult, dtype=np.int64) return data, freq def _range_from_fields( year=None, month=None, quarter=None, day=None, hour=None, minute=None, second=None, freq=None, ) -> tuple[np.ndarray, BaseOffset]: if hour is None: hour = 0 if minute is None: minute = 0 if second is None: second = 0 if day is None: day = 1 if quarter is not None: if freq is None: freq = to_offset("Q", is_period=True) base = FreqGroup.FR_QTR.value else: freq = to_offset(freq, is_period=True) base = libperiod.freq_to_dtype_code(freq) if FreqGroup.from_period_dtype_code(base) != FreqGroup.FR_QTR: raise ValueError("freq must be a quarterly frequency") freqstr = freq.freqstr year, quarter = _make_field_arrays(year, quarter) year = _field_to_int64(year) quarter = _field_to_int64(quarter) if (quarter < 1).any() or (quarter > 4).any(): raise ValueError("Quarter must be 1 <= q <= 4") # Vectorized quarter_to_myear mnum = MONTH_NUMBERS[parsing.get_rule_month(freqstr)] + 1 months = (mnum + (quarter - 1) * 3) % 12 + 1 years = np.where(months > mnum, year - 1, year) length = len(years) ones = np.ones(length, dtype=np.int64) zeros = np.zeros(length, dtype=np.int64) ordinals = libperiod.period_ordinals_from_fields( years, months, ones, zeros, zeros, zeros, base ) else: freq = to_offset(freq, is_period=True) base = libperiod.freq_to_dtype_code(freq) arrays = _make_field_arrays(year, month, day, hour, minute, second) ordinals = libperiod.period_ordinals_from_fields( _field_to_int64(arrays[0]), _field_to_int64(arrays[1]), _field_to_int64(arrays[2]), _field_to_int64(arrays[3]), _field_to_int64(arrays[4]), _field_to_int64(arrays[5]), base, ) return ordinals, freq def _field_to_int64(values) -> np.ndarray: values = np.asarray(values) if values.dtype.kind == "f" and np.isnan(values).any(): # Match the error raised by the scalar Period constructor; casting # NaN to int64 would otherwise silently produce garbage ordinals. raise ValueError("cannot convert float NaN to integer") return values.astype(np.int64, copy=False) def _make_field_arrays(*fields) -> list[np.ndarray]: length = None for x in fields: if isinstance(x, (list, tuple, np.ndarray, ABCSeries)): if length is not None and len(x) != length: raise ValueError("Mismatched Period array lengths") if length is None: length = len(x) # error: Argument 2 to "repeat" has incompatible type "Optional[int]"; expected # "Union[Union[int, integer[Any]], Union[bool, bool_], ndarray, Sequence[Union[int, # integer[Any]]], Sequence[Union[bool, bool_]], Sequence[Sequence[Any]]]" return [ ( np.asarray(x) if isinstance(x, (np.ndarray, list, tuple, ABCSeries)) else np.repeat(x, length) # type: ignore[arg-type] ) for x in fields ]