{"record":{"id":"20759286d1cd2afa","repo":"pandas-dev/pandas","slug":"cannot-add-period-to-a-type-self-name","errorCode":null,"errorMessage":"cannot add Period to a {type(self).__name__}","messagePattern":"cannot add Period to a (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/datetimelike.py","lineNumber":1140,"sourceCode":"\n        from pandas.core.arrays import TimedeltaArray\n\n        try:\n            self._assert_tzawareness_compat(other)\n        except TypeError as err:\n            new_message = str(err).replace(\"compare\", \"subtract\")\n            raise type(err)(new_message) from err\n\n        other_i8, o_mask = self._get_i8_values_and_mask(other)\n        res_values = add_overflowsafe(self.asi8, np.asarray(-other_i8, dtype=\"i8\"))\n        res_m8 = res_values.view(f\"timedelta64[{self.unit}]\")\n\n        return TimedeltaArray._simple_new(res_m8, dtype=res_m8.dtype)\n\n    @final\n    def _add_period(self, other: Period) -> PeriodArray:\n        if not lib.is_np_dtype(self.dtype, \"m\"):\n            raise TypeError(f\"cannot add Period to a {type(self).__name__}\")\n\n        # We will wrap in a PeriodArray and defer to the reversed operation\n        from pandas.core.arrays.period import PeriodArray\n\n        i8vals = np.broadcast_to(other.ordinal, self.shape)\n        dtype = PeriodDtype(other.freq)\n        parr = PeriodArray(i8vals, dtype=dtype)\n        return parr + self\n\n    def _add_offset(self, offset):\n        raise AbstractMethodError(self)\n\n    def _add_timedeltalike_scalar(self, other):\n        \"\"\"\n        Add a delta of a timedeltalike\n\n        Returns\n        -------","sourceCodeStart":1122,"sourceCodeEnd":1158,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/datetimelike.py#L1122-L1158","documentation":"Raised by _add_period when self.dtype is not timedelta64. Only TimedeltaArray + Period -> PeriodArray is defined (a duration shifts a period); adding a Period to a DatetimeArray or to another PeriodArray is rejected.","triggerScenarios":"DatetimeArray + Period(...); PeriodArray + Period(...); adding a pd.Period scalar to a non-timedelta datetimelike array.","commonSituations":"Period arithmetic confusion: assuming Period + Period composes; mixing Period and Timestamp semantics in financial/calendar code.","solutions":["Add the Period to a TimedeltaArray/TimedeltaIndex, or use PeriodArray + Timedelta.","Convert the Period to a Timestamp via .to_timestamp() if you need datetime arithmetic.","For Period-on-Period differences, subtract instead of add to get an int frequency count."],"exampleFix":"// before\nres = dta + pd.Period('2020', freq='D')  # TypeError\n\n// after\nres = tda + pd.Period('2020', freq='D')   # TimedeltaArray + Period\n# or\nres = dta + pd.Timedelta(days=1)","handlingStrategy":"type-guard","validationCode":"import pandas as pd\n\ndef add_period(arr, period):\n    if not isinstance(period, pd.Period):\n        raise TypeError('expected a pd.Period')\n    if arr.dtype.kind != 'm':\n        raise TypeError('Period can only be added to a TimedeltaArray')\n    return arr + period","typeGuard":"import pandas as pd\n\ndef is_period(v) -> bool:\n    return isinstance(v, pd.Period)","tryCatchPattern":"try:\n    res = arr + other\nexcept TypeError as e:\n    if 'cannot add Period' in str(e):\n        res = arr + pd.Timedelta(other.freq)  # only if a timedelta equivalent exists\n    else:\n        raise","preventionTips":["Add Period only to TimedeltaArray/TimedeltaIndex.","Use .to_timestamp() for Period->datetime conversion when datetime arithmetic is needed.","Subtract Periods (don't add them) to get integer frequency counts."],"tags":["datetime","arithmetic","period","type-error"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}