from __future__ import annotations import datetime as dt import operator from typing import ( TYPE_CHECKING, Self, ) import warnings import numpy as np from pandas._libs import ( NaT, Period, Timestamp, index as libindex, lib, ) from pandas._libs.tslibs import ( Resolution, Tick, Timedelta, periods_per_day, timezones, to_offset, ) from pandas._libs.tslibs.dtypes import abbrev_to_npy_unit from pandas._libs.tslibs.offsets import ( DateOffset, prefix_mapping, ) 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 is_scalar from pandas.core.dtypes.dtypes import ( ArrowDtype, DatetimeTZDtype, ) from pandas.core.dtypes.generic import ABCSeries from pandas.core.dtypes.missing import is_valid_na_for_dtype from pandas.core.arrays.datetimes import ( DatetimeArray, tz_to_dtype, ) import pandas.core.common as com from pandas.core.indexes.base import ( Index, maybe_extract_name, ) from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin from pandas.core.tools.times import to_time if TYPE_CHECKING: from collections.abc import Hashable from pandas._typing import ( Dtype, DtypeObj, Frequency, IntervalClosedType, TimeAmbiguous, TimeNonexistent, TimeUnit, npt, ) from pandas.core.api import ( DataFrame, PeriodIndex, ) from pandas._libs.tslibs.dtypes import OFFSET_TO_PERIOD_FREQSTR def _new_DatetimeIndex(cls, d): """ This is called upon unpickling, rather than the default which doesn't have arguments and breaks __new__ """ if "data" in d and not isinstance(d["data"], DatetimeIndex): # Avoid need to verify integrity by calling simple_new directly data = d.pop("data") if not isinstance(data, DatetimeArray): # For backward compat with older pickles, we may need to construct # a DatetimeArray to adapt to the newer _simple_new signature tz = d.pop("tz") freq = d.pop("freq") dta = DatetimeArray._simple_new(data, dtype=tz_to_dtype(tz)) else: dta = data if "tz" in d: assert d.pop("tz") == dta.tz # Legacy pickles stored freq on the DatetimeArray; current pickles # include it in ``d``. Migrate either up onto the Index. legacy_freq = vars(dta).pop("_freq", None) freq = d.pop("freq", legacy_freq) result = cls._simple_new(dta, **d) result._freq = freq else: with warnings.catch_warnings(): # TODO: If we knew what was going in to **d, we might be able to # go through _simple_new instead warnings.simplefilter("ignore") result = cls.__new__(cls, **d) return result @set_module("pandas") class DatetimeIndex(DatetimeTimedeltaMixin): """ Immutable ndarray-like of datetime64 data. Represented internally as int64, and which can be boxed to Timestamp objects that are subclasses of datetime and carry metadata. .. versionchanged:: 2.0.0 The various numeric date/time attributes (:attr:`~DatetimeIndex.day`, :attr:`~DatetimeIndex.month`, :attr:`~DatetimeIndex.year` etc.) now have dtype ``int32``. Previously they had dtype ``int64``. Parameters ---------- data : array-like (1-dimensional) Datetime-like data to construct index with. freq : str or pandas offset object, optional One of pandas date offset strings or corresponding objects. The string 'infer' can be passed in order to set the frequency of the index as the inferred frequency upon creation. tz : zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile, datetime.tzinfo or str Set the Timezone of the data. ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. For example in Central European Time (UTC+01), when going from 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter dictates how ambiguous times should be handled. - 'infer' will attempt to infer fall dst-transition hours based on order. Requires that the timestamps are monotonically increasing. - bool-ndarray where True signifies a DST time, False signifies a non-DST time (note that this flag is only applicable for ambiguous times) - 'NaT' will return NaT where there are ambiguous times - 'raise' will raise a ValueError if there are ambiguous times. .. deprecated:: 3.1.0 Use :meth:`DatetimeIndex.tz_localize` instead. dayfirst : bool, default False If True, parse dates in `data` with the day first order. .. deprecated:: 3.1.0 Use :func:`to_datetime` instead. yearfirst : bool, default False If True parse dates in `data` with the year first order. .. deprecated:: 3.1.0 Use :func:`to_datetime` instead. dtype : numpy.dtype or DatetimeTZDtype or str, default None Note that the only NumPy dtypes allowed are 'datetime64[ns]', 'datetime64[us]', 'datetime64[ms]', 'datetime64[s]'. copy : bool, default None Whether to copy input data, only relevant for array, Series, and Index inputs (for other input, e.g. a list, a new array is created anyway). Defaults to True for array input and False for Index/Series. Set to False to avoid copying array input at your own risk (if you know the input data won't be modified elsewhere). Set to True to force copying Series/Index up front. name : label, default None Name to be stored in the index. Attributes ---------- year month day hour minute second microsecond nanosecond date time timetz dayofyear day_of_year dayofweek day_of_week weekday quarter tz freq freqstr is_month_start is_month_end is_quarter_start is_quarter_end is_year_start is_year_end is_leap_year inferred_freq Methods ------- normalize strftime snap tz_convert tz_localize round floor ceil to_period to_pydatetime to_series to_frame to_julian_date month_name day_name mean std See Also -------- Index : The base pandas Index type. TimedeltaIndex : Index of timedelta64 data. PeriodIndex : Index of Period data. to_datetime : Convert argument to datetime. date_range : Create a fixed-frequency DatetimeIndex. Notes ----- To learn more about the frequency strings, please see :ref:`this link`. Examples -------- >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"]) >>> idx DatetimeIndex(['2020-01-01 10:00:00+00:00', '2020-02-01 11:00:00+00:00'], dtype='datetime64[us, UTC]', freq=None) """ _typ = "datetimeindex" _data_cls = DatetimeArray _supports_partial_string_indexing = True @property def _engine_type(self) -> type[libindex.DatetimeEngine]: return libindex.DatetimeEngine _data: DatetimeArray _values: DatetimeArray # -------------------------------------------------------------------- # properties dispatching to DatetimeArray without wrapping the result @property def tz(self) -> dt.tzinfo | None: """ Return the timezone. This property returns the timezone information associated with the DatetimeIndex. If the data is timezone-naive (i.e. has no timezone information), it returns None. Returns ------- zoneinfo.ZoneInfo, datetime.tzinfo, pytz.tzinfo.BaseTZInfo, dateutil.tz.tz.tzfile, or None Returns None when the DatetimeIndex is tz-naive. See Also -------- DatetimeIndex.tz_localize : Localize tz-naive DatetimeIndex to a given time zone, or remove timezone from a tz-aware DatetimeIndex. DatetimeIndex.tz_convert : Convert tz-aware DatetimeIndex from one time zone to another. Examples -------- >>> idx = pd.DatetimeIndex( ... ["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"] ... ) >>> idx.tz datetime.timezone.utc """ # noqa: E501 return self._data.tz @tz.setter def tz(self, value) -> None: # GH#3746 disallow localizing or converting via attribute assignment; # delegate to DatetimeArray.tz for the raised error message self._data.tz = value @property def tzinfo(self) -> dt.tzinfo | None: """ Alias for tz attribute. Examples -------- >>> idx = pd.DatetimeIndex( ... ["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"] ... ) >>> idx.tzinfo datetime.timezone.utc """ return self.tz @cache_readonly def is_normalized(self) -> bool: """ Returns True if all of the dates are at midnight ("no time"). Examples -------- >>> idx = pd.DatetimeIndex(["2020-01-01 00:00:00", "2020-02-01 00:00:00"]) >>> idx.is_normalized True >>> idx = pd.DatetimeIndex(["2020-01-01 00:00:01", "2020-02-01 00:00:00"]) >>> idx.is_normalized False """ return self._data.is_normalized # field_ops: wrap result in Index def _wrap_field(self, name: str) -> Index: result = getattr(self._data, name) return Index(result, name=self.name, dtype=result.dtype, copy=False) @property def year(self) -> Index: """ The year of the datetime. This attribute returns the year component of each datetime value in the DatetimeIndex. See Also -------- DatetimeIndex.month: The month as January=1, December=12. DatetimeIndex.day: The day of the datetime. Examples -------- >>> idx = pd.DatetimeIndex(["2000-12-31", "2001-12-31", "2002-12-31"]) >>> idx.year Index([2000, 2001, 2002], dtype='int32') """ return self._wrap_field("year") @property def month(self) -> Index: """ The month as January=1, December=12. This attribute returns the month component of each datetime value in the DatetimeIndex. See Also -------- DatetimeIndex.year: The year of the datetime. DatetimeIndex.day: The day of the datetime. Examples -------- >>> idx = pd.DatetimeIndex(["2000-01-31", "2000-02-29", "2000-03-31"]) >>> idx.month Index([1, 2, 3], dtype='int32') """ return self._wrap_field("month") @property def day(self) -> Index: """ The day of the datetime. This attribute returns the day of the month component of each datetime value in the DatetimeIndex. See Also -------- DatetimeIndex.year: The year of the datetime. DatetimeIndex.month: The month as January=1, December=12. DatetimeIndex.hour: The hours of the datetime. Examples -------- >>> idx = pd.DatetimeIndex(["2000-01-01", "2000-01-02", "2000-01-03"]) >>> idx.day Index([1, 2, 3], dtype='int32') """ return self._wrap_field("day") @property def hour(self) -> Index: """ The hours of the datetime. This attribute returns the hour component of each datetime value in the DatetimeIndex. See Also -------- DatetimeIndex.day: The day of the datetime. DatetimeIndex.minute: The minutes of the datetime. DatetimeIndex.second: The seconds of the datetime. Examples -------- >>> idx = pd.date_range("2000-01-01", periods=3, freq="h") >>> idx.hour Index([0, 1, 2], dtype='int32') """ return self._wrap_field("hour") @property def minute(self) -> Index: """ The minutes of the datetime. This attribute returns the minute component of each datetime value in the DatetimeIndex. See Also -------- DatetimeIndex.hour: The hours of the datetime. DatetimeIndex.second: The seconds of the datetime. Examples -------- >>> idx = pd.date_range("2000-01-01", periods=3, freq="min") >>> idx.minute Index([0, 1, 2], dtype='int32') """ return self._wrap_field("minute") @property def second(self) -> Index: """ The seconds of the datetime. This attribute returns the second component of each datetime value in the DatetimeIndex. See Also -------- DatetimeIndex.minute: The minutes of the datetime. DatetimeIndex.microsecond: The microseconds of the datetime. DatetimeIndex.nanosecond: The nanoseconds of the datetime. Examples -------- >>> idx = pd.date_range("2000-01-01", periods=3, freq="s") >>> idx.second Index([0, 1, 2], dtype='int32') """ return self._wrap_field("second") @property def weekday(self) -> Index: """ The day of the week with Monday=0, Sunday=6. .. deprecated:: 3.1.0 Use :attr:`DatetimeIndex.day_of_week` instead. """ # GH#12816 warnings.warn( "DatetimeIndex.weekday is deprecated and will be removed " "in a future version. Use DatetimeIndex.day_of_week instead.", Pandas4Warning, stacklevel=find_stack_level(), ) return self._wrap_field("day_of_week") @property def dayofweek(self) -> Index: """ The day of the week with Monday=0, Sunday=6. .. deprecated:: 3.1.0 Use :attr:`DatetimeIndex.day_of_week` instead. """ warnings.warn( "DatetimeIndex.dayofweek is deprecated and will be removed in a " "future version. Use DatetimeIndex.day_of_week instead.", Pandas4Warning, stacklevel=find_stack_level(), ) return self._wrap_field("day_of_week") @property def day_of_week(self) -> Index: """ The day of the week with Monday=0, Sunday=6. Return the day of the week. It is assumed the week starts on Monday, which is denoted by 0 and ends on Sunday which is denoted by 6. See Also -------- DatetimeIndex.day_of_year : The ordinal day of the year. DatetimeIndex.day_name : Return the name of the day of the week. Examples -------- >>> idx = pd.DatetimeIndex(["2016-12-31", "2017-01-01", "2017-01-02"]) >>> idx.day_of_week Index([5, 6, 0], dtype='int32') """ return self._wrap_field("day_of_week") @property def dayofyear(self) -> Index: """ The ordinal day of the year. .. deprecated:: 3.1.0 Use :attr:`DatetimeIndex.day_of_year` instead. """ warnings.warn( "DatetimeIndex.dayofyear is deprecated and will be removed in a " "future version. Use DatetimeIndex.day_of_year instead.", Pandas4Warning, stacklevel=find_stack_level(), ) return self._wrap_field("day_of_year") @property def day_of_year(self) -> Index: """ The ordinal day of the year. This attribute returns the day of the year for each datetime value in the DatetimeIndex. Values range from 1 to 365 (or 366 for leap years). See Also -------- DatetimeIndex.day_of_week : The day of the week with Monday=0, Sunday=6. DatetimeIndex.day : The day of the datetime. Examples -------- >>> idx = pd.DatetimeIndex(["2020-01-01", "2020-02-01"]) >>> idx.day_of_year Index([1, 32], dtype='int32') """ return self._wrap_field("day_of_year") @property def quarter(self) -> Index: """ The quarter of the date. This attribute returns the quarter of the year for each datetime value in the DatetimeIndex. Quarter 1 includes January through March, quarter 2 includes April through June, quarter 3 includes July through September, and quarter 4 includes October through December. See Also -------- DatetimeIndex.month : The month as January=1, December=12. DatetimeIndex.is_quarter_start : Indicator for whether the date is the first day of a quarter. DatetimeIndex.is_quarter_end : Indicator for whether the date is the last day of a quarter. Examples -------- >>> idx = pd.DatetimeIndex(["2020-01-01", "2020-04-01"]) >>> idx.quarter Index([1, 2], dtype='int32') """ return self._wrap_field("quarter") @property def days_in_month(self) -> Index: """ The number of days in the month. This attribute returns the total number of days in the month for each datetime value in the DatetimeIndex. The value depends on the month and whether the year is a leap year (e.g., February has 29 days in a leap year). See Also -------- DatetimeIndex.day : Return the day of the month. DatetimeIndex.is_month_end : Return a boolean indicating if the date is the last day of the month. DatetimeIndex.is_month_start : Return a boolean indicating if the date is the first day of the month. DatetimeIndex.month : Return the month as January=1 through December=12. Examples -------- >>> idx = pd.DatetimeIndex(["2020-01-01", "2020-02-01"]) >>> idx.days_in_month Index([31, 29], dtype='int32') """ return self._wrap_field("days_in_month") @property def daysinmonth(self) -> Index: """ The number of days in the month. .. deprecated:: 3.1.0 Use :attr:`DatetimeIndex.days_in_month` instead. """ warnings.warn( "DatetimeIndex.daysinmonth is deprecated and will be removed in a " "future version. Use DatetimeIndex.days_in_month instead.", Pandas4Warning, stacklevel=find_stack_level(), ) return self._wrap_field("days_in_month") @property def microsecond(self) -> Index: """ The microseconds of the datetime. This attribute returns the microsecond component of each datetime value in the DatetimeIndex. Values range from 0 to 999999 (one microsecond is one millionth of a second). See Also -------- DatetimeIndex.second: The seconds of the datetime. DatetimeIndex.nanosecond: The nanoseconds of the datetime. Examples -------- >>> idx = pd.date_range("2000-01-01", periods=3, freq="us") >>> idx.microsecond Index([0, 1, 2], dtype='int32') """ return self._wrap_field("microsecond") @property def nanosecond(self) -> Index: """ The nanoseconds of the datetime. This attribute returns the nanosecond component of each datetime value in the DatetimeIndex. Values range from 0 to 999 (one nanosecond is one billionth of a second). See Also -------- DatetimeIndex.second: The seconds of the datetime. DatetimeIndex.microsecond: The microseconds of the datetime. Examples -------- >>> idx = pd.date_range("2000-01-01", periods=3, freq="ns") >>> idx.nanosecond Index([0, 1, 2], dtype='int32') """ return self._wrap_field("nanosecond") # bool_ops: return raw result @property def is_month_start(self) -> npt.NDArray[np.bool_]: """ Indicates whether the date is the first day of the month. This boolean attribute evaluates to True if the date falls on the first day of a calendar month, and False otherwise. If the index has a business ``freq`` (e.g. ``"BMS"``), the result follows that frequency's month boundaries instead of the calendar's. See Also -------- DatetimeIndex.is_month_end : Return a boolean indicating whether the date is the last day of the month. Examples -------- >>> idx = pd.date_range("2018-02-27", periods=3) >>> idx.is_month_start array([False, False, True]) """ return self._data._get_start_end_field("is_month_start", self.freq) @property def is_month_end(self) -> npt.NDArray[np.bool_]: """ Indicates whether the date is the last day of the month. This boolean attribute evaluates to True if the date falls on the last day of a calendar month, and False otherwise. If the index has a business ``freq`` (e.g. ``"BME"``), the result follows that frequency's month boundaries instead of the calendar's. See Also -------- DatetimeIndex.is_month_start : Return a boolean indicating whether the date is the first day of the month. Examples -------- >>> idx = pd.date_range("2018-02-27", periods=3) >>> idx.is_month_end array([False, True, False]) """ return self._data._get_start_end_field("is_month_end", self.freq) @property def is_quarter_start(self) -> npt.NDArray[np.bool_]: """ Indicator for whether the date is the first day of a quarter. This boolean attribute evaluates to True if the date falls on the first day of a calendar quarter (January 1, April 1, July 1, or October 1), and False otherwise. If the index has a business or anchored ``freq`` (e.g. ``"BQS"`` or ``"QS-FEB"``), the result follows that frequency's quarter boundaries instead of the calendar's. See Also -------- DatetimeIndex.quarter : Return the quarter of the date. DatetimeIndex.is_quarter_end : Similar property for indicating the quarter end. Examples -------- >>> idx = pd.date_range("2017-03-30", periods=4) >>> idx.is_quarter_start array([False, False, True, False]) """ return self._data._get_start_end_field("is_quarter_start", self.freq) @property def is_quarter_end(self) -> npt.NDArray[np.bool_]: """ Indicator for whether the date is the last day of a quarter. This boolean attribute evaluates to True if the date falls on the last day of a calendar quarter (March 31, June 30, September 30, or December 31), and False otherwise. If the index has a business or anchored ``freq`` (e.g. ``"BQE"`` or ``"QE-NOV"``), the result follows that frequency's quarter boundaries instead of the calendar's. See Also -------- DatetimeIndex.quarter : Return the quarter of the date. DatetimeIndex.is_quarter_start : Similar property indicating the quarter start. Examples -------- >>> idx = pd.date_range("2017-03-30", periods=4) >>> idx.is_quarter_end array([False, True, False, False]) """ return self._data._get_start_end_field("is_quarter_end", self.freq) @property def is_year_start(self) -> npt.NDArray[np.bool_]: """ Indicate whether the date is the first day of a year. This boolean attribute evaluates to True if the date is January 1st, and False otherwise. If the index has a business or anchored ``freq`` (e.g. ``"BYS"`` or ``"YS-APR"``), the result follows that frequency's year boundaries instead of the calendar's. See Also -------- DatetimeIndex.is_year_end : Similar property indicating the last day of the year. Examples -------- >>> idx = pd.date_range("2017-12-30", periods=3) >>> idx.is_year_start array([False, False, True]) With a business ``freq``, the first business day of the year counts as the year start even when it is not January 1st: >>> idx = pd.date_range("2020-10-30", periods=4, freq="BYS") >>> idx DatetimeIndex(['2021-01-01', '2022-01-03', '2023-01-02', '2024-01-01'], dtype='datetime64[us]', freq='BYS-JAN') >>> idx.is_year_start array([ True, True, True, True]) """ return self._data._get_start_end_field("is_year_start", self.freq) @property def is_year_end(self) -> npt.NDArray[np.bool_]: """ Indicate whether the date is the last day of the year. This boolean attribute evaluates to True if the date is December 31st, and False otherwise. If the index has a business or anchored ``freq`` (e.g. ``"BYE"`` or ``"YE-MAR"``), the result follows that frequency's year boundaries instead of the calendar's. See Also -------- DatetimeIndex.is_year_start : Similar property indicating the start of the year. Examples -------- >>> idx = pd.date_range("2017-12-30", periods=3) >>> idx.is_year_end array([False, True, False]) """ return self._data._get_start_end_field("is_year_end", self.freq) @property def is_leap_year(self) -> npt.NDArray[np.bool_]: """ Boolean indicator if the date belongs to a leap year. A leap year is a year, which has 366 days (instead of 365) including 29th of February as an intercalary day. Leap years are years which are multiples of four with the exception of years divisible by 100 but not by 400. See Also -------- DatetimeIndex.is_year_end : Indicate whether the date is the last day of the year. DatetimeIndex.is_year_start : Indicate whether the date is the first day of a year. Examples -------- >>> idx = pd.date_range("2012-01-01", "2015-01-01", freq="YE") >>> idx.is_leap_year array([ True, False, False]) """ return self._data.is_leap_year # -------------------------------------------------------------------- # properties and methods dispatching to DatetimeArray, result not wrapped @property def date(self) -> npt.NDArray[np.object_]: """ Returns numpy array of python :class:`datetime.date` objects. Namely, the date part of Timestamps without time and timezone information. See Also -------- DatetimeIndex.time : Returns numpy array of :class:`datetime.time` objects. The time part of the Timestamps. DatetimeIndex.year : The year of the datetime. DatetimeIndex.month : The month as January=1, December=12. DatetimeIndex.day : The day of the datetime. Examples -------- >>> idx = pd.DatetimeIndex( ... ["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"] ... ) >>> idx.date array([datetime.date(2020, 1, 1), datetime.date(2020, 2, 1)], dtype=object) """ return self._data.date @property def time(self) -> npt.NDArray[np.object_]: """ Returns numpy array of :class:`datetime.time` objects. The time part of the Timestamps. See Also -------- DatetimeIndex.timetz : Returns numpy array of :class:`datetime.time` objects with timezones. The time part of the Timestamps. DatetimeIndex.date : Returns numpy array of python :class:`datetime.date` objects. Namely, the date part of Timestamps without time and timezone information. Examples -------- >>> idx = pd.DatetimeIndex( ... ["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"] ... ) >>> idx.time array([datetime.time(10, 0), datetime.time(11, 0)], dtype=object) """ return self._data.time @property def timetz(self) -> npt.NDArray[np.object_]: """ Returns numpy array of :class:`datetime.time` objects with timezones. The time part of the Timestamps. See Also -------- DatetimeIndex.time : Returns numpy array of :class:`datetime.time` objects. The time part of the Timestamps. DatetimeIndex.tz : Return the timezone. Examples -------- >>> idx = pd.DatetimeIndex( ... ["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"] ... ) >>> idx.timetz array([datetime.time(10, 0, tzinfo=datetime.timezone.utc), datetime.time(11, 0, tzinfo=datetime.timezone.utc)], dtype=object) """ return self._data.timetz def to_pydatetime(self) -> npt.NDArray[np.object_]: """ Return an ndarray of ``datetime.datetime`` objects. This method converts each element in the DatetimeIndex to a native Python ``datetime.datetime`` object, including timezone information if present. Returns ------- numpy.ndarray An ndarray of ``datetime.datetime`` objects. See Also -------- DatetimeIndex.to_julian_date : Converts Datetime Array to float64 ndarray of Julian Dates. Examples -------- >>> idx = pd.date_range("2018-02-27", periods=3) >>> idx.to_pydatetime() array([datetime.datetime(2018, 2, 27, 0, 0), datetime.datetime(2018, 2, 28, 0, 0), datetime.datetime(2018, 3, 1, 0, 0)], dtype=object) """ return self._data.to_pydatetime() def std( self, axis=None, dtype=None, out=None, ddof: int = 1, keepdims: bool = False, skipna: bool = True, ) -> Timedelta: """ Return sample standard deviation over requested axis. Normalized by `N-1` by default. This can be changed using ``ddof``. Parameters ---------- axis : int, optional Axis for the function to be applied on. dtype : None Unused; for compatibility with :func:`numpy.std`. out : None Not supported; for compatibility with :func:`numpy.std`. ddof : int, default 1 Degrees of Freedom. The divisor used in calculations is `N - ddof`, where `N` represents the number of elements. keepdims : bool, default False Not supported; for compatibility with :func:`numpy.std`. skipna : bool, default True Exclude NA/null values. Returns ------- Timedelta Standard deviation over requested axis. See Also -------- numpy.ndarray.std : Returns the standard deviation of the array elements along given axis. Series.std : Return sample standard deviation over requested axis. Examples -------- >>> idx = pd.date_range("2001-01-01 00:00", periods=3) >>> idx DatetimeIndex(['2001-01-01', '2001-01-02', '2001-01-03'], dtype='datetime64[us]', freq='D') >>> idx.std() Timedelta('1 days 00:00:00') """ return self._data.std( axis=axis, dtype=dtype, out=out, ddof=ddof, keepdims=keepdims, skipna=skipna ) # -------------------------------------------------------------------- # methods that dispatch to DatetimeArray and wrap result def strftime(self, date_format) -> Index: """ Convert to Index using specified date_format. Return an Index of formatted strings specified by date_format, which supports the same string format as the python standard library. Details of the string format can be found in `python string format doc `__. Formats supported by the C `strftime` API but not by the python string format doc (such as `"%R"`, `"%r"`) are not officially supported and should be preferably replaced with their supported equivalents (such as `"%H:%M"`, `"%I:%M:%S %p"`). Note that `PeriodIndex` support additional directives, detailed in `Period.strftime`. Parameters ---------- date_format : str Date format string (e.g. "%Y-%m-%d"). Returns ------- ndarray[object] NumPy ndarray of formatted strings. See Also -------- to_datetime : Convert the given argument to datetime. DatetimeIndex.normalize : Return DatetimeIndex with times to midnight. DatetimeIndex.round : Round the DatetimeIndex to the specified freq. DatetimeIndex.floor : Floor the DatetimeIndex to the specified freq. Timestamp.strftime : Format a single Timestamp. Period.strftime : Format a single Period. Examples -------- >>> rng = pd.date_range(pd.Timestamp("2018-03-10 09:00"), periods=3, freq="s") >>> rng.strftime("%B %d, %Y, %r") Index(['March 10, 2018, 09:00:00 AM', 'March 10, 2018, 09:00:01 AM', 'March 10, 2018, 09:00:02 AM'], dtype='str') """ arr = self._data.strftime(date_format) return Index(arr, name=self.name, dtype=arr.dtype, copy=False) def month_name(self, locale=None) -> Index: """ Return the month names with specified locale. This method returns the full name of the month (e.g., "January", "February") for each datetime value in the Series/Index. The names can be localized to different languages using the locale parameter. Parameters ---------- locale : str, optional Locale determining the language in which to return the month name. Default is English locale (``'en_US.utf8'``). Use the command ``locale -a`` on your terminal on Unix systems to find your locale language code. Returns ------- Index Index of month names. See Also -------- DatetimeIndex.day_name : Return the day names with specified locale. Examples -------- >>> idx = pd.date_range(start="2018-01", freq="ME", periods=3) >>> idx DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31'], dtype='datetime64[us]', freq='ME') >>> idx.month_name() Index(['January', 'February', 'March'], dtype='str') Using the ``locale`` parameter you can set a different locale language, for example: ``idx.month_name(locale='pt_BR.utf8')`` will return month names in Brazilian Portuguese language. >>> idx.month_name(locale="pt_BR.utf8") # doctest: +SKIP Index(['Janeiro', 'Fevereiro', 'Março'], dtype='str') """ arr = self._data.month_name(locale=locale) return Index(arr, name=self.name, dtype=arr.dtype, copy=False) def day_name(self, locale=None) -> Index: """ Return the day names with specified locale. This method returns the full name of the day of the week (e.g., "Monday", "Tuesday") for each datetime value in the Series/Index. The names can be localized to different languages using the locale parameter. Parameters ---------- locale : str, optional Locale determining the language in which to return the day name. Default is English locale (``'en_US.utf8'``). Use the command ``locale -a`` on your terminal on Unix systems to find your locale language code. Returns ------- Index Index of day names. See Also -------- DatetimeIndex.month_name : Return the month names with specified locale. Examples -------- >>> idx = pd.date_range(start="2018-01-01", freq="D", periods=3) >>> idx DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03'], dtype='datetime64[us]', freq='D') >>> idx.day_name() Index(['Monday', 'Tuesday', 'Wednesday'], dtype='str') Using the ``locale`` parameter you can set a different locale language, for example: ``idx.day_name(locale='pt_BR.utf8')`` will return day names in Brazilian Portuguese language. >>> idx.day_name(locale="pt_BR.utf8") # doctest: +SKIP Index(['Segunda', 'Terça', 'Quarta'], dtype='str') """ arr = self._data.day_name(locale=locale) return Index(arr, name=self.name, dtype=arr.dtype, copy=False) # error: Signature of "round" incompatible with supertype "Index" # freq-based, unlike Index.round(decimals) def round( # type: ignore[override] self, freq, ambiguous: TimeAmbiguous = "raise", nonexistent: TimeNonexistent = "raise", ) -> Self: """ Perform round operation on the data to the specified `freq`. This method rounds each datetime value in the Series/Index to the nearest specified frequency using standard rounding rules (round half to even). Parameters ---------- freq : str or Offset The frequency level to round the index to. Must be a fixed frequency like 's' (second) not 'ME' (month end). See :ref:`frequency aliases ` for a list of possible `freq` values. ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' - 'infer' will attempt to infer fall dst-transition hours based on order. Requires that the timestamps are monotonically increasing. - bool-ndarray where True signifies a DST time, False designates a non-DST time (note that this flag is only applicable for ambiguous times) - 'NaT' will return NaT where there are ambiguous times - 'raise' will raise a ValueError if there are ambiguous times. nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, \ default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - 'shift_forward' will shift the nonexistent time forward to the closest existing time - 'shift_backward' will shift the nonexistent time backward to the closest existing time - 'NaT' will return NaT where there are nonexistent times - timedelta objects will shift nonexistent times by the timedelta - 'raise' will raise a ValueError if there are nonexistent times. Returns ------- DatetimeIndex Index with each value rounded to the specified `freq`. Raises ------ ValueError if the `freq` cannot be converted. See Also -------- DatetimeIndex.floor : Perform floor operation on the data to the specified `freq`. DatetimeIndex.ceil : Perform ceil operation on the data to the specified `freq`. DatetimeIndex.snap : Snap time stamps to nearest occurring frequency. Notes ----- If the timestamps have a timezone, rounding will take place relative to the local ("wall") time and re-localized to the same timezone. When rounding near daylight savings time, use ``nonexistent`` and ``ambiguous`` to control the re-localization behavior. Examples -------- >>> rng = pd.date_range("1/1/2018 11:59:00", periods=3, freq="min") >>> rng DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00', '2018-01-01 12:01:00'], dtype='datetime64[us]', freq='min') >>> rng.round("h") DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00', '2018-01-01 12:00:00'], dtype='datetime64[us]', freq=None) When rounding near a daylight savings time transition, use ``ambiguous`` or ``nonexistent`` to control how the timestamp should be re-localized. >>> rng_tz = pd.DatetimeIndex(["2021-10-31 01:30:00"], tz="Europe/Amsterdam") >>> rng_tz.round("2h", ambiguous=False) DatetimeIndex(['2021-10-31 02:00:00+01:00'], dtype='datetime64[us, Europe/Amsterdam]', freq=None) >>> rng_tz.round("2h", ambiguous=True) DatetimeIndex(['2021-10-31 02:00:00+02:00'], dtype='datetime64[us, Europe/Amsterdam]', freq=None) """ arr = self._data.round(freq, ambiguous, nonexistent) return type(self)._simple_new(arr, name=self.name) def floor( self, freq, ambiguous: TimeAmbiguous = "raise", nonexistent: TimeNonexistent = "raise", ) -> Self: """ Perform floor operation on the data to the specified `freq`. This method rounds each datetime value in the Series/Index down to the specified frequency (i.e., towards negative infinity). Parameters ---------- freq : str or Offset The frequency level to floor the index to. Must be a fixed frequency like 's' (second) not 'ME' (month end). See :ref:`frequency aliases ` for a list of possible `freq` values. ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' - 'infer' will attempt to infer fall dst-transition hours based on order. Requires that the timestamps are monotonically increasing. - bool-ndarray where True signifies a DST time, False designates a non-DST time (note that this flag is only applicable for ambiguous times) - 'NaT' will return NaT where there are ambiguous times - 'raise' will raise a ValueError if there are ambiguous times. nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, \ default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - 'shift_forward' will shift the nonexistent time forward to the closest existing time - 'shift_backward' will shift the nonexistent time backward to the closest existing time - 'NaT' will return NaT where there are nonexistent times - timedelta objects will shift nonexistent times by the timedelta - 'raise' will raise a ValueError if there are nonexistent times. Returns ------- DatetimeIndex Index with each value floored to the specified `freq`. Raises ------ ValueError if the `freq` cannot be converted. See Also -------- DatetimeIndex.round : Perform round operation on the data to the specified `freq`. DatetimeIndex.ceil : Perform ceil operation on the data to the specified `freq`. DatetimeIndex.snap : Snap time stamps to nearest occurring frequency. Notes ----- If the timestamps have a timezone, flooring will take place relative to the local ("wall") time and re-localized to the same timezone. When flooring near daylight savings time, use ``nonexistent`` and ``ambiguous`` to control the re-localization behavior. Examples -------- >>> rng = pd.date_range("1/1/2018 11:59:00", periods=3, freq="min") >>> rng DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00', '2018-01-01 12:01:00'], dtype='datetime64[us]', freq='min') >>> rng.floor("h") DatetimeIndex(['2018-01-01 11:00:00', '2018-01-01 12:00:00', '2018-01-01 12:00:00'], dtype='datetime64[us]', freq=None) When rounding near a daylight savings time transition, use ``ambiguous`` or ``nonexistent`` to control how the timestamp should be re-localized. >>> rng_tz = pd.DatetimeIndex(["2021-10-31 03:30:00"], tz="Europe/Amsterdam") >>> rng_tz.floor("2h", ambiguous=False) DatetimeIndex(['2021-10-31 02:00:00+01:00'], dtype='datetime64[us, Europe/Amsterdam]', freq=None) >>> rng_tz.floor("2h", ambiguous=True) DatetimeIndex(['2021-10-31 02:00:00+02:00'], dtype='datetime64[us, Europe/Amsterdam]', freq=None) """ arr = self._data.floor(freq, ambiguous, nonexistent) return type(self)._simple_new(arr, name=self.name) def ceil( self, freq, ambiguous: TimeAmbiguous = "raise", nonexistent: TimeNonexistent = "raise", ) -> Self: """ Perform ceil operation on the data to the specified `freq`. This method rounds each datetime value in the Series/Index up to the specified frequency (i.e., towards positive infinity). Parameters ---------- freq : str or Offset The frequency level to ceil the index to. Must be a fixed frequency like 's' (second) not 'ME' (month end). See :ref:`frequency aliases ` for a list of possible `freq` values. ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' - 'infer' will attempt to infer fall dst-transition hours based on order. Requires that the timestamps are monotonically increasing. - bool-ndarray where True signifies a DST time, False designates a non-DST time (note that this flag is only applicable for ambiguous times) - 'NaT' will return NaT where there are ambiguous times - 'raise' will raise a ValueError if there are ambiguous times. nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, \ default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - 'shift_forward' will shift the nonexistent time forward to the closest existing time - 'shift_backward' will shift the nonexistent time backward to the closest existing time - 'NaT' will return NaT where there are nonexistent times - timedelta objects will shift nonexistent times by the timedelta - 'raise' will raise a ValueError if there are nonexistent times. Returns ------- DatetimeIndex Index with each value ceiled to the specified `freq`. Raises ------ ValueError if the `freq` cannot be converted. See Also -------- DatetimeIndex.round : Perform round operation on the data to the specified `freq`. DatetimeIndex.floor : Perform floor operation on the data to the specified `freq`. DatetimeIndex.snap : Snap time stamps to nearest occurring frequency. Notes ----- If the timestamps have a timezone, ceiling will take place relative to the local ("wall") time and re-localized to the same timezone. When ceiling near daylight savings time, use ``nonexistent`` and ``ambiguous`` to control the re-localization behavior. Examples -------- >>> rng = pd.date_range("1/1/2018 11:59:00", periods=3, freq="min") >>> rng DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00', '2018-01-01 12:01:00'], dtype='datetime64[us]', freq='min') >>> rng.ceil("h") DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00', '2018-01-01 13:00:00'], dtype='datetime64[us]', freq=None) When rounding near a daylight savings time transition, use ``ambiguous`` or ``nonexistent`` to control how the timestamp should be re-localized. >>> rng_tz = pd.DatetimeIndex(["2021-10-31 01:30:00"], tz="Europe/Amsterdam") >>> rng_tz.ceil("h", ambiguous=False) DatetimeIndex(['2021-10-31 02:00:00+01:00'], dtype='datetime64[us, Europe/Amsterdam]', freq=None) >>> rng_tz.ceil("h", ambiguous=True) DatetimeIndex(['2021-10-31 02:00:00+02:00'], dtype='datetime64[us, Europe/Amsterdam]', freq=None) """ arr = self._data.ceil(freq, ambiguous, nonexistent) return type(self)._simple_new(arr, name=self.name) def normalize(self) -> Self: """ Convert times to midnight. The time component of the date-time is converted to midnight i.e. 00:00:00. This is useful in cases, when the time does not matter. Length is unaltered. The timezones are unaffected. This method is available on Series with datetime values under the ``.dt`` accessor, and directly on Datetime Array/Index. Returns ------- DatetimeArray, DatetimeIndex or Series The same type as the original data. Series will have the same name and index. DatetimeIndex will have the same name. See Also -------- floor : Floor the datetimes to the specified freq. ceil : Ceil the datetimes to the specified freq. round : Round the datetimes to the specified freq. Examples -------- >>> idx = pd.date_range( ... start="2014-08-01 10:00", freq="h", periods=3, tz="Asia/Calcutta" ... ) >>> idx DatetimeIndex(['2014-08-01 10:00:00+05:30', '2014-08-01 11:00:00+05:30', '2014-08-01 12:00:00+05:30'], dtype='datetime64[us, Asia/Calcutta]', freq='h') >>> idx.normalize() DatetimeIndex(['2014-08-01 00:00:00+05:30', '2014-08-01 00:00:00+05:30', '2014-08-01 00:00:00+05:30'], dtype='datetime64[us, Asia/Calcutta]', freq=None) """ data = self._data # Inferring frequency from naive normalization is significantly # cheaper than tz-aware. naive = data._normalize_naive() freq = to_offset(naive._inferred_freq_str) arr = naive.tz_localize(data.tz) if data.tz is not None else naive result = type(self)._simple_new(arr, name=self.name) result._freq = freq return result def tz_convert(self, tz) -> Self: """ Convert tz-aware Datetime Array/Index from one time zone to another. This method converts each timestamp in the index to the target time zone while preserving the underlying UTC time. The index must already be timezone-aware. Parameters ---------- tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile, datetime.tzinfo or None Time zone for time. Corresponding timestamps would be converted to this time zone of the Datetime Array/Index. A `tz` of None will convert to UTC and remove the timezone information. Returns ------- Array or Index Datetime Array/Index with target `tz`. Raises ------ TypeError If Datetime Array/Index is tz-naive. See Also -------- DatetimeIndex.tz : A timezone that has a variable offset from UTC. DatetimeIndex.tz_localize : Localize tz-naive DatetimeIndex to a given time zone, or remove timezone from a tz-aware DatetimeIndex. Examples -------- With the `tz` parameter, we can change the DatetimeIndex to other time zones: >>> dti = pd.date_range( ... start="2014-08-01 09:00", freq="h", periods=3, tz="Europe/Berlin" ... ) >>> dti DatetimeIndex(['2014-08-01 09:00:00+02:00', '2014-08-01 10:00:00+02:00', '2014-08-01 11:00:00+02:00'], dtype='datetime64[us, Europe/Berlin]', freq='h') >>> dti.tz_convert("US/Central") DatetimeIndex(['2014-08-01 02:00:00-05:00', '2014-08-01 03:00:00-05:00', '2014-08-01 04:00:00-05:00'], dtype='datetime64[us, US/Central]', freq='h') With the ``tz=None``, we can remove the timezone (after converting to UTC if necessary): >>> dti = pd.date_range( ... start="2014-08-01 09:00", freq="h", periods=3, tz="Europe/Berlin" ... ) >>> dti DatetimeIndex(['2014-08-01 09:00:00+02:00', '2014-08-01 10:00:00+02:00', '2014-08-01 11:00:00+02:00'], dtype='datetime64[us, Europe/Berlin]', freq='h') >>> dti.tz_convert(None) DatetimeIndex(['2014-08-01 07:00:00', '2014-08-01 08:00:00', '2014-08-01 09:00:00'], dtype='datetime64[us]', freq='h') """ # noqa: E501 arr = self._data.tz_convert(tz) result = type(self)._simple_new(arr, name=self.name, refs=self._references) if isinstance(self.freq, Tick): result._freq = self.freq return result def tz_localize( self, tz, ambiguous: TimeAmbiguous = "raise", nonexistent: TimeNonexistent = "raise", ) -> Self: """ Localize tz-naive Datetime Array/Index to tz-aware Datetime Array/Index. This method takes a time zone (tz) naive Datetime Array/Index object and makes this time zone aware. It does not move the time to another time zone. This method can also be used to do the inverse -- to create a time zone unaware object from an aware object. To that end, pass `tz=None`. Parameters ---------- tz : str, zoneinfo.ZoneInfo, pytz.timezone, dateutil.tz.tzfile, datetime.tzinfo or None Time zone to attach to the tz-naive timestamps; the wall time is preserved. Passing ``None`` detaches the time zone from a tz-aware DatetimeIndex, returning a tz-naive DatetimeIndex with the same wall time. ambiguous : 'infer', 'NaT', bool array, default 'raise' When clocks moved backward due to DST, ambiguous times may arise. For example in Central European Time (UTC+01), when going from 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter dictates how ambiguous times should be handled. - 'infer' will attempt to infer fall dst-transition hours based on order. Requires that the timestamps are monotonically increasing. - bool-ndarray where True signifies a DST time, False signifies a non-DST time (note that this flag is only applicable for ambiguous times) - 'NaT' will return NaT where there are ambiguous times - 'raise' will raise a ValueError if there are ambiguous times. nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, \ default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - 'shift_forward' will shift the nonexistent time forward to the closest existing time - 'shift_backward' will shift the nonexistent time backward to the closest existing time - 'NaT' will return NaT where there are nonexistent times - timedelta objects will shift nonexistent times by the timedelta - 'raise' will raise a ValueError if there are nonexistent times. Returns ------- Same type as self Array/Index converted to the specified time zone. Raises ------ TypeError If the Datetime Array/Index is tz-aware and tz is not None. See Also -------- DatetimeIndex.tz_convert : Convert tz-aware DatetimeIndex from one time zone to another. Examples -------- >>> tz_naive = pd.date_range('2018-03-01 09:00', periods=3) >>> tz_naive DatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00', '2018-03-03 09:00:00'], dtype='datetime64[us]', freq='D') Localize DatetimeIndex in US/Eastern time zone: >>> tz_aware = tz_naive.tz_localize(tz='US/Eastern') >>> tz_aware DatetimeIndex(['2018-03-01 09:00:00-05:00', '2018-03-02 09:00:00-05:00', '2018-03-03 09:00:00-05:00'], dtype='datetime64[us, US/Eastern]', freq='D') With ``tz=None`` we can remove the time zone information while preserving the wall time (no conversion to UTC): >>> tz_aware.tz_localize(None) DatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00', '2018-03-03 09:00:00'], dtype='datetime64[us]', freq='D') Be careful with DST changes. When there is sequential data, pandas can infer the DST time: >>> s = pd.to_datetime(pd.Series(['2018-10-28 01:30:00', ... '2018-10-28 02:00:00', ... '2018-10-28 02:30:00', ... '2018-10-28 02:00:00', ... '2018-10-28 02:30:00', ... '2018-10-28 03:00:00', ... '2018-10-28 03:30:00'])) >>> s.dt.tz_localize('CET', ambiguous='infer') 0 2018-10-28 01:30:00+02:00 1 2018-10-28 02:00:00+02:00 2 2018-10-28 02:30:00+02:00 3 2018-10-28 02:00:00+01:00 4 2018-10-28 02:30:00+01:00 5 2018-10-28 03:00:00+01:00 6 2018-10-28 03:30:00+01:00 dtype: datetime64[us, CET] In some cases, inferring the DST is impossible. In such cases, you can pass an ndarray to the ambiguous parameter to set the DST explicitly >>> s = pd.to_datetime(pd.Series(['2018-10-28 01:20:00', ... '2018-10-28 02:36:00', ... '2018-10-28 03:46:00'])) >>> s.dt.tz_localize('CET', ambiguous=np.array([True, True, False])) 0 2018-10-28 01:20:00+02:00 1 2018-10-28 02:36:00+02:00 2 2018-10-28 03:46:00+01:00 dtype: datetime64[us, CET] If the DST transition causes nonexistent times, you can shift these dates forward or backwards with a timedelta object or `'shift_forward'` or `'shift_backward'`. >>> s = pd.to_datetime(pd.Series(['2015-03-29 02:30:00', ... '2015-03-29 03:30:00'], dtype="M8[ns]")) >>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_forward') 0 2015-03-29 03:00:00+02:00 1 2015-03-29 03:30:00+02:00 dtype: datetime64[ns, Europe/Warsaw] >>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_backward') 0 2015-03-29 01:59:59.999999999+01:00 1 2015-03-29 03:30:00.000000000+02:00 dtype: datetime64[ns, Europe/Warsaw] >>> s.dt.tz_localize('Europe/Warsaw', nonexistent=pd.Timedelta('1h')) 0 2015-03-29 03:30:00+02:00 1 2015-03-29 03:30:00+02:00 dtype: datetime64[ns, Europe/Warsaw] """ # noqa: E501 freq = self._freq arr = self._data.tz_localize(tz, ambiguous, nonexistent) result = type(self)._simple_new(arr, name=self.name) if timezones.is_utc(arr.tz) or (len(arr) == 1 and arr[0] is not NaT): # we can preserve freq # TODO: Also for fixed-offsets result._freq = freq elif arr.tz is None and self._data.tz is None: # no-op result._freq = freq elif ( freq is not None and not isinstance(freq, Tick) and nonexistent in ("raise", "NaT") and not arr._hasna ): # GH#36575 pandas treats non-Tick offsets as wall-time: date_range # generates them in wall time and localizes after, and # _validate_frequency validates them against wall times (GH#55499). # tz_localize leaves wall times unchanged, so freq survives unless # we shifted nonexistent times or introduced NaTs. result._freq = freq return result def to_period(self, freq=None) -> PeriodIndex: """ Cast to PeriodArray/PeriodIndex at a particular frequency. Converts DatetimeArray/Index to PeriodArray/PeriodIndex. Parameters ---------- freq : str, optional One of pandas' :ref:`period aliases `. Will be inferred by default. Returns ------- PeriodArray/PeriodIndex Immutable ndarray holding ordinal values at a particular frequency. Raises ------ ValueError When converting a DatetimeArray/Index with non-regular values, so that a frequency cannot be inferred. See Also -------- PeriodIndex: Immutable ndarray holding ordinal values. DatetimeIndex.to_pydatetime: Return DatetimeIndex as object. Examples -------- >>> df = pd.DataFrame( ... {"y": [1, 2, 3]}, ... index=pd.to_datetime( ... [ ... "2000-03-31 00:00:00", ... "2000-05-31 00:00:00", ... "2000-08-31 00:00:00", ... ] ... ), ... ) >>> df.index.to_period("M") PeriodIndex(['2000-03', '2000-05', '2000-08'], dtype='period[M]') Infer the daily frequency >>> idx = pd.date_range("2017-01-01", periods=2) >>> idx.to_period() PeriodIndex(['2017-01-01', '2017-01-02'], dtype='period[D]') """ from pandas.core.dtypes.dtypes import PeriodDtype from pandas.core.indexes.api import PeriodIndex from pandas.tseries.frequencies import get_period_alias if freq is None: dt_freq = self.freq freq = self.freqstr if dt_freq is not None and hasattr(dt_freq, "_period_dtype_code"): freq = PeriodDtype(dt_freq)._freqstr if freq is None: freq = self._inferred_freq_str if freq is not None: res = get_period_alias(freq) if res is not None: freq = res arr = self._data.to_period(freq) return PeriodIndex._simple_new(arr, name=self.name) def to_julian_date(self) -> Index: """ Convert Timestamp to a Julian Date. This method returns the number of days as a float since noon January 1, 4713 BC. https://en.wikipedia.org/wiki/Julian_day Returns ------- ndarray or Index Float values that represent each date in Julian Calendar. See Also -------- Timestamp.to_julian_date : Equivalent method on ``Timestamp`` objects. Examples -------- >>> idx = pd.DatetimeIndex(["2028-08-12 00:54", "2028-08-12 02:06"]) >>> idx.to_julian_date() Index([2461995.5375, 2461995.5875], dtype='float64') """ arr = self._data.to_julian_date() return Index._simple_new(arr, name=self.name) def isocalendar(self) -> DataFrame: """ Calculate year, week, and day according to the ISO 8601 standard. Returns ------- DataFrame With columns year, week and day. See Also -------- Timestamp.isocalendar : Function return a 3-tuple containing ISO year, week number, and weekday for the given Timestamp object. datetime.date.isocalendar : Return a named tuple object with three components: year, week and weekday. Examples -------- >>> idx = pd.date_range(start="2019-12-29", freq="D", periods=4) >>> idx.isocalendar() year week day 2019-12-29 2019 52 7 2019-12-30 2020 1 1 2019-12-31 2020 1 2 2020-01-01 2020 1 3 >>> idx.isocalendar().week 2019-12-29 52 2019-12-30 1 2019-12-31 1 2020-01-01 1 Freq: D, Name: week, dtype: UInt32 """ df = self._data.isocalendar() return df.set_index(self) # -------------------------------------------------------------------- # Constructors def __new__( cls, data=None, freq: Frequency | lib.NoDefault = lib.no_default, tz=lib.no_default, ambiguous: TimeAmbiguous | lib.NoDefault = lib.no_default, dayfirst: bool | lib.NoDefault = lib.no_default, yearfirst: bool | lib.NoDefault = lib.no_default, dtype: Dtype | None = None, copy: bool | None = None, name: Hashable | None = None, ) -> Self: if is_scalar(data): cls._raise_scalar_data_error(data) if dayfirst is lib.no_default: dayfirst = False else: warnings.warn( f"The 'dayfirst' keyword in {cls.__name__} is deprecated " "and will be removed in a future version. " "Use pd.to_datetime instead.", Pandas4Warning, stacklevel=find_stack_level(), ) if yearfirst is lib.no_default: yearfirst = False else: warnings.warn( f"The 'yearfirst' keyword in {cls.__name__} is deprecated " "and will be removed in a future version. " "Use pd.to_datetime instead.", Pandas4Warning, stacklevel=find_stack_level(), ) if ambiguous is lib.no_default: ambiguous = "raise" else: warnings.warn( f"The 'ambiguous' keyword in {cls.__name__} is deprecated " "and will be removed in a future version. " f"Use {cls.__name__}.tz_localize instead.", Pandas4Warning, stacklevel=find_stack_level(), ) # - Cases checked above all return/raise before reaching here - # name = maybe_extract_name(name, data, cls) # GH#63388 data, copy = cls._maybe_copy_array_input(data, copy, dtype) if ( isinstance(data, DatetimeArray) and freq is lib.no_default and tz is lib.no_default and dtype is None ): # fastpath, similar logic in TimedeltaIndex.__new__; # Note in this particular case we retain non-nano. if copy: data = data.copy() return cls._simple_new(data, name=name) inferred_freq = data.freq if isinstance(data, DatetimeIndex) else None dtarr = DatetimeArray._from_sequence_not_strict( data, dtype=dtype, copy=copy, tz=tz, dayfirst=dayfirst, yearfirst=yearfirst, ambiguous=ambiguous, ) refs = None if not copy and isinstance(data, (Index, ABCSeries)): refs = data._references subarr = cls._simple_new(dtarr, name=name, refs=refs) subarr._pin_freq(freq, inferred_freq) return subarr # -------------------------------------------------------------------- @cache_readonly def _is_dates_only(self) -> bool: """ Return a boolean if we are only dates (and don't have a timezone) Returns ------- bool """ if isinstance(self.freq, Tick): delta = Timedelta(self.freq) if delta % dt.timedelta(days=1) != dt.timedelta(days=0): return False return self._values._is_dates_only def __reduce__(self): d = {"data": self._data, "name": self.name, "freq": self._freq} return _new_DatetimeIndex, (type(self), d), None def _is_comparable_dtype(self, dtype: DtypeObj) -> bool: """ Can we compare values of the given dtype to our own? """ if isinstance(dtype, ArrowDtype): # GH#62277 if dtype.kind != "M": return False import pyarrow as pa pa_dtype = dtype.pyarrow_dtype if not pa.types.is_timestamp(pa_dtype): # GH#62051 date types (date32, date64) are not # comparable with DatetimeIndex return False if (pa_dtype.tz is None) ^ (self.tz is None): return False return True if self.tz is not None: # If we have tz, we can compare to tzaware return isinstance(dtype, DatetimeTZDtype) # if we dont have tz, we can only compare to tznaive return lib.is_np_dtype(dtype, "M") # -------------------------------------------------------------------- # Rendering Methods def _formatter_func(self, val) -> str: # Note this is equivalent to the DatetimeIndexOpsMixin method but # uses the maybe-cached self._is_dates_only instead of re-computing it. return f"'{self._date_formatter(val)}'" @cache_readonly def _date_formatter(self): from pandas.io.formats.format import get_format_datetime64 return get_format_datetime64(is_dates_only=self._is_dates_only) # -------------------------------------------------------------------- # Set Operation Methods def _can_range_setop(self, other) -> bool: # GH 46702: If self or other have non-UTC tzs, DST transitions prevent # range representation due to no singular step if ( self.tz is not None and not timezones.is_utc(self.tz) and not timezones.is_fixed_offset(self.tz) ): return False if ( other.tz is not None and not timezones.is_utc(other.tz) and not timezones.is_fixed_offset(other.tz) ): return False return super()._can_range_setop(other) # -------------------------------------------------------------------- def _get_time_micros(self) -> npt.NDArray[np.int64]: """ Return the number of microseconds since midnight. Returns ------- ndarray[int64_t] """ values = self._data._local_timestamps() ppd = periods_per_day(self._data._creso) frac = values % ppd if self.unit == "ns": micros = frac // 1000 elif self.unit == "us": micros = frac elif self.unit == "ms": micros = frac * 1000 elif self.unit == "s": micros = frac * 1_000_000 else: # pragma: no cover raise NotImplementedError(self.unit) micros[self._isnan] = -1 return micros def snap(self, freq: Frequency = "S") -> DatetimeIndex: """ Snap time stamps to nearest occurring frequency. Each timestamp in the index is adjusted to the nearest occurrence of the specified frequency, snapping backward or forward as appropriate. Parameters ---------- freq : str, Timedelta, datetime.timedelta, or DateOffset, default 'S' Frequency strings can have multiples, e.g. '5h'. See :ref:`here ` for a list of frequency aliases. Returns ------- DatetimeIndex Time stamps to nearest occurring `freq`. See Also -------- DatetimeIndex.round : Perform round operation on the data to the specified `freq`. DatetimeIndex.floor : Perform floor operation on the data to the specified `freq`. Examples -------- >>> idx = pd.DatetimeIndex( ... ["2023-01-01", "2023-01-02", "2023-02-01", "2023-02-02"], ... dtype="M8[ns]", ... ) >>> idx DatetimeIndex(['2023-01-01', '2023-01-02', '2023-02-01', '2023-02-02'], dtype='datetime64[ns]', freq=None) >>> idx.snap("MS") DatetimeIndex(['2023-01-01', '2023-01-01', '2023-02-01', '2023-02-01'], dtype='datetime64[ns]', freq=None) """ # Superdumb, punting on any optimizing freq = to_offset(freq) dta = self._data.copy() for i, v in enumerate(self): s = v if not freq.is_on_offset(s): t0 = freq.rollback(s) t1 = freq.rollforward(s) if abs(s - t0) < abs(t1 - s): s = t0 else: s = t1 dta[i] = s return DatetimeIndex._simple_new(dta, name=self.name) # -------------------------------------------------------------------- # Indexing Methods def _parsed_string_to_bounds( self, reso: Resolution, parsed: dt.datetime ) -> tuple[Timestamp, Timestamp]: """ Calculate datetime bounds for parsed time string and its resolution. Parameters ---------- reso : Resolution Resolution provided by parsed string. parsed : datetime Datetime from parsed string. Returns ------- lower, upper: pd.Timestamp """ freq = OFFSET_TO_PERIOD_FREQSTR.get(reso.attr_abbrev, reso.attr_abbrev) per = Period(parsed, freq=freq) start = per.start_time # Can't use end_time here bc that will subtract a microsecond # instead of a nanosecond end = (per + 1).start_time - np.timedelta64(1, "ns") start = start.as_unit(self.unit) end = end.as_unit(self.unit) # GH 24076 # If an incoming date string contained a UTC offset, need to localize # the parsed date to this offset first before aligning with the index's # timezone start = start.tz_localize(parsed.tzinfo) end = end.tz_localize(parsed.tzinfo) if parsed.tzinfo is not None: if self.tz is None: raise ValueError( "The index must be timezone aware when indexing " "with a date string with a UTC offset" ) # The flipped case with parsed.tz is None and self.tz is not None # is ruled out bc parsed and reso are produced by _parse_with_reso, # which localizes parsed. return start, end def _parse_with_reso(self, label: str) -> tuple[Timestamp, Resolution]: parsed, reso = super()._parse_with_reso(label) parsed = Timestamp(parsed) if self.tz is not None and parsed.tzinfo is None: # we special-case timezone-naive strings and timezone-aware # DatetimeIndex # https://github.com/pandas-dev/pandas/pull/36148#issuecomment-687883081 parsed = parsed.tz_localize(self.tz) return parsed, reso def _disallow_mismatched_indexing(self, key) -> None: """ Check for mismatched-tzawareness indexing and re-raise as KeyError. """ # we get here with isinstance(key, self._data._recognized_scalars) try: # GH#36148 self._data._assert_tzawareness_compat(key) except TypeError as err: raise KeyError(key) from err def get_loc(self, key): """ Get integer location for requested label Returns ------- loc : int """ self._check_indexing_error(key) orig_key = key if is_valid_na_for_dtype(key, self.dtype): key = NaT if isinstance(key, self._data._recognized_scalars): # needed to localize naive datetimes self._disallow_mismatched_indexing(key) key = Timestamp(key) elif isinstance(key, str): try: parsed, reso = self._parse_with_reso(key) except ValueError as err: raise KeyError(key) from err self._disallow_mismatched_indexing(parsed) if self._can_partial_date_slice(reso): try: return self._partial_date_slice(reso, parsed) except KeyError as err: raise KeyError(key) from err key = parsed elif isinstance(key, dt.timedelta): # GH#20464 raise TypeError( f"Cannot index {type(self).__name__} with {type(key).__name__}" ) elif isinstance(key, dt.time): return self.indexer_at_time(key) else: # unrecognized type raise KeyError(key) try: return Index.get_loc(self, key) except KeyError as err: raise KeyError(orig_key) from err def _maybe_cast_slice_bound(self, label, side: str): """ This function should be overloaded in subclasses that allow non-trivial casting on label-slice bounds, e.g. datetime-like indices allowing strings containing formatted datetimes. Parameters ---------- label : object side : {'left', 'right'} Returns ------- label : object Notes ----- Value of `side` parameter should be validated in caller. """ # GH#42855 handle date here instead of get_slice_bound if isinstance(label, dt.date) and not isinstance(label, dt.datetime): # Pandas supports slicing with dates, treated as datetimes at midnight. # https://github.com/pandas-dev/pandas/issues/31501 label = Timestamp(label).to_pydatetime() warnings.warn( # GH#35830 deprecate last remaining inconsistent date treatment "Slicing with a datetime.date object is deprecated. " "Explicitly cast to Timestamp instead.", Pandas4Warning, stacklevel=find_stack_level(), ) label = super()._maybe_cast_slice_bound(label, side) self._data._assert_tzawareness_compat(label) return Timestamp(label) def slice_indexer(self, start=None, end=None, step=None): """ Return indexer for specified label slice. Index.slice_indexer, customized to handle time slicing. In addition to functionality provided by Index.slice_indexer, does the following: - if both `start` and `end` are instances of `datetime.time`, it invokes `indexer_between_time` - if `start` and `end` are both either string or None perform value-based selection in non-monotonic cases. """ # For historical reasons DatetimeIndex supports slices between two # instances of datetime.time as if it were applying a slice mask to # an array of (self.hour, self.minute, self.seconds, self.microsecond). if isinstance(start, dt.time) and isinstance(end, dt.time): if step is not None and step != 1: raise ValueError("Must have step size of 1 with time slices") return self.indexer_between_time(start, end) if isinstance(start, dt.time) or isinstance(end, dt.time): raise KeyError("Cannot mix time and non-time slice keys") def check_str_or_none(point) -> bool: return point is not None and not isinstance(point, str) # GH#33146 if start and end are combinations of str and None and Index is not # monotonic, we can not use Index.slice_indexer because it does not honor the # actual elements, is only searching for start and end if ( check_str_or_none(start) or check_str_or_none(end) or self.is_monotonic_increasing ): return Index.slice_indexer(self, start, end, step) mask = np.array(True) in_index = True if start is not None: start_casted = self._maybe_cast_slice_bound(start, "left") mask = start_casted <= self in_index &= (start_casted == self).any() if end is not None: end_casted = self._maybe_cast_slice_bound(end, "right") mask = (self <= end_casted) & mask in_index &= (end_casted == self).any() if not in_index: raise KeyError( "Value based partial slicing on non-monotonic DatetimeIndexes " "with non-existing keys is not allowed.", ) indexer = mask.nonzero()[0][::step] if len(indexer) == len(self): return slice(None) else: return indexer # -------------------------------------------------------------------- @property def inferred_type(self) -> str: # b/c datetime is represented as microseconds since the epoch, make # sure we can't have ambiguous indexing return "datetime64" def indexer_at_time(self, time, asof: bool = False) -> npt.NDArray[np.intp]: """ Return index locations of values at particular time of day. This method returns the integer indices of the DatetimeIndex entries that match the specified time of day, regardless of the date. Parameters ---------- time : datetime.time or str Time passed in either as object (datetime.time) or as string in appropriate format ("%H:%M", "%H%M", "%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p", "%I%M%S%p"). asof : bool, default False This parameter is currently not supported. Returns ------- np.ndarray[np.intp] Index locations of values at given `time` of day. See Also -------- indexer_between_time : Get index locations of values between particular times of day. DataFrame.at_time : Select values at particular time of day. Examples -------- >>> idx = pd.DatetimeIndex( ... ["1/1/2020 10:00", "2/1/2020 11:00", "3/1/2020 10:00"] ... ) >>> idx.indexer_at_time("10:00") array([0, 2]) """ if asof: raise NotImplementedError("'asof' argument is not supported") if isinstance(time, str): from dateutil.parser import parse orig = time try: alt = to_time(time) except ValueError: warnings.warn( # GH#50839 f"The string '{orig}' cannot be parsed using pd.core.tools.to_time " f"and in a future version will raise. " "Use an unambiguous time string format or explicitly cast to " "`datetime.time` before calling.", Pandas4Warning, stacklevel=find_stack_level(), ) time = parse(time).time() else: try: time = parse(time).time() except ValueError: # e.g. '23550' raises dateutil.parser._parser.ParserError time = alt if alt != time: warnings.warn( # GH#50839 f"The string '{orig}' is currently parsed as {time} " f"but in a future version will be parsed as {alt}, consistent" "with `between_time` behavior. To avoid this warning, " "use an unambiguous string format or explicitly cast to " "`datetime.time` before calling.", Pandas4Warning, stacklevel=find_stack_level(), ) if time.tzinfo: if self.tz is None: raise ValueError("Index must be timezone aware.") time_micros = self.tz_convert(time.tzinfo)._get_time_micros() else: time_micros = self._get_time_micros() micros = _time_to_micros(time) return (time_micros == micros).nonzero()[0] def indexer_between_time( self, start_time, end_time, include_start: bool = True, include_end: bool = True ) -> npt.NDArray[np.intp]: """ Return index locations of values between particular times of day. This method returns the integer indices of the DatetimeIndex entries whose time-of-day components fall within the specified range. Parameters ---------- start_time, end_time : datetime.time, str Time passed either as object (datetime.time) or as string in appropriate format ("%H:%M", "%H%M", "%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p","%I%M%S%p"). include_start : bool, default True Include boundaries; whether to set start bound as closed or open. include_end : bool, default True Include boundaries; whether to set end bound as closed or open. Returns ------- np.ndarray[np.intp] Index locations of values between particular times of day. See Also -------- indexer_at_time : Get index locations of values at particular time of day. DataFrame.between_time : Select values between particular times of day. Examples -------- >>> idx = pd.date_range("2023-01-01", periods=4, freq="h") >>> idx DatetimeIndex(['2023-01-01 00:00:00', '2023-01-01 01:00:00', '2023-01-01 02:00:00', '2023-01-01 03:00:00'], dtype='datetime64[us]', freq='h') >>> idx.indexer_between_time("00:00", "2:00", include_end=False) array([0, 1]) """ start_time = to_time(start_time) end_time = to_time(end_time) time_micros = self._get_time_micros() start_micros = _time_to_micros(start_time) end_micros = _time_to_micros(end_time) if include_start and include_end: lop = rop = operator.le elif include_start: lop = operator.le rop = operator.lt elif include_end: lop = operator.lt rop = operator.le else: lop = rop = operator.lt if start_time <= end_time: join_op = operator.and_ else: join_op = operator.or_ mask = join_op(lop(start_micros, time_micros), rop(time_micros, end_micros)) return mask.nonzero()[0] @set_module("pandas") def date_range( start=None, end=None, periods=None, freq=None, tz=None, normalize: bool = False, name: Hashable | None = None, inclusive: IntervalClosedType = "both", *, unit: TimeUnit | None = None, ambiguous: TimeAmbiguous = "raise", nonexistent: TimeNonexistent = "raise", **kwargs, ) -> DatetimeIndex: """ Return a fixed frequency DatetimeIndex. Returns the range of equally spaced time points (where the difference between any two adjacent points is specified by the given frequency) such that they fall in the range `[start, end]` , where the first one and the last one are, resp., the first and last time points in that range that fall on the boundary of ``freq`` (if given as a frequency string) or that are valid for ``freq`` (if given as a :class:`pandas.tseries.offsets.DateOffset`). If ``freq`` is positive, the points satisfy `start <[=] x <[=] end`, and if ``freq`` is negative, the points satisfy `end <[=] x <[=] start`. (If exactly one of ``start``, ``end``, or ``freq`` is *not* specified, this missing parameter can be computed given ``periods``, the number of timesteps in the range. See the note below.) Parameters ---------- start : str or datetime-like, optional Left bound for generating dates. end : str or datetime-like, optional Right bound for generating dates. periods : int, optional Number of periods to generate. freq : str, Timedelta, datetime.timedelta, or DateOffset, default 'D' Frequency strings can have multiples, e.g. '5h'. See :ref:`here ` for a list of frequency aliases. tz : str or tzinfo, optional Time zone name for returning localized DatetimeIndex, for example 'Asia/Hong_Kong'. By default, the resulting DatetimeIndex is timezone-naive unless timezone-aware datetime-likes are passed. normalize : bool, default False Normalize start/end dates to midnight before generating date range. name : Hashable, default None Name of the resulting DatetimeIndex. inclusive : {"both", "neither", "left", "right"}, default "both" Include boundaries; Whether to set each bound as closed or open. unit : {'s', 'ms', 'us', 'ns', None}, default None Specify the desired resolution of the result. If not specified, this is inferred from the 'start', 'end', and 'freq' using the same inference as :class:`Timestamp` taking the highest resolution of the three that are provided. .. versionadded:: 2.0.0 ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. For example in Central European Time (UTC+01), when going from 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter dictates how ambiguous times should be handled. - 'infer' will attempt to infer fall dst-transition hours based on order. Requires that the timestamps are monotonically increasing. - bool-ndarray where True signifies a DST time, False signifies a non-DST time (note that this flag is only applicable for ambiguous times) - 'NaT' will return NaT where there are ambiguous times - 'raise' will raise a ValueError if there are ambiguous times. nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, \ default 'raise' A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. - 'shift_forward' will shift the nonexistent time forward to the closest existing time - 'shift_backward' will shift the nonexistent time backward to the closest existing time - 'NaT' will return NaT where there are nonexistent times - timedelta objects will shift nonexistent times by the timedelta - 'raise' will raise a ValueError if there are nonexistent times. **kwargs For compatibility. Has no effect on the result. Returns ------- DatetimeIndex A DatetimeIndex object of the generated dates. See Also -------- DatetimeIndex : An immutable container for datetimes. timedelta_range : Return a fixed frequency TimedeltaIndex. period_range : Return a fixed frequency PeriodIndex. interval_range : Return a fixed frequency IntervalIndex. Notes ----- Of the four parameters ``start``, ``end``, ``periods``, and ``freq``, a maximum of three can be specified at once. Of the three parameters ``start``, ``end``, and ``periods``, at least two must be specified. If ``freq`` is omitted, the resulting ``DatetimeIndex`` will have ``periods`` linearly spaced elements between ``start`` and ``end`` (closed on both sides). To learn more about the frequency strings, please see :ref:`this link`. Examples -------- **Specifying the values** The next four examples generate the same `DatetimeIndex`, but vary the combination of `start`, `end` and `periods`. Specify `start` and `end`, with the default daily frequency. >>> pd.date_range(start="1/1/2018", end="1/08/2018") DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04', '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'], dtype='datetime64[us]', freq='D') Specify timezone-aware `start` and `end`, with the default daily frequency. >>> pd.date_range( ... start=pd.to_datetime("1/1/2018").tz_localize("Europe/Berlin"), ... end=pd.to_datetime("1/08/2018").tz_localize("Europe/Berlin"), ... ) DatetimeIndex(['2018-01-01 00:00:00+01:00', '2018-01-02 00:00:00+01:00', '2018-01-03 00:00:00+01:00', '2018-01-04 00:00:00+01:00', '2018-01-05 00:00:00+01:00', '2018-01-06 00:00:00+01:00', '2018-01-07 00:00:00+01:00', '2018-01-08 00:00:00+01:00'], dtype='datetime64[us, Europe/Berlin]', freq='D') Specify `start` and `periods`, the number of periods (days). >>> pd.date_range(start="1/1/2018", periods=8) DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04', '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'], dtype='datetime64[us]', freq='D') Specify `end` and `periods`, the number of periods (days). >>> pd.date_range(end="1/1/2018", periods=8) DatetimeIndex(['2017-12-25', '2017-12-26', '2017-12-27', '2017-12-28', '2017-12-29', '2017-12-30', '2017-12-31', '2018-01-01'], dtype='datetime64[us]', freq='D') Specify `start`, `end`, and `periods`; the frequency is generated automatically (linearly spaced). >>> pd.date_range(start="2018-04-24", end="2018-04-27", periods=3) DatetimeIndex(['2018-04-24 00:00:00', '2018-04-25 12:00:00', '2018-04-27 00:00:00'], dtype='datetime64[us]', freq=None) **Other Parameters** Changed the `freq` (frequency) to ``'ME'`` (month end frequency). >>> pd.date_range(start="1/1/2018", periods=5, freq="ME") DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31', '2018-04-30', '2018-05-31'], dtype='datetime64[us]', freq='ME') Multiples are allowed >>> pd.date_range(start="1/1/2018", periods=5, freq="3ME") DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31', '2019-01-31'], dtype='datetime64[us]', freq='3ME') `freq` can also be specified as an Offset object. >>> pd.date_range(start="1/1/2018", periods=5, freq=pd.offsets.MonthEnd(3)) DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31', '2019-01-31'], dtype='datetime64[us]', freq='3ME') Use :class:`pandas.DateOffset` for calendar steps that are not anchored to the start or end of a period. >>> pd.date_range(end="2017-03-12", periods=3, freq=pd.DateOffset(years=1)) DatetimeIndex(['2015-03-12', '2016-03-12', '2017-03-12'], dtype='datetime64[us]', freq='') Specify `tz` to set the timezone. >>> pd.date_range(start="1/1/2018", periods=5, tz="Asia/Tokyo") DatetimeIndex(['2018-01-01 00:00:00+09:00', '2018-01-02 00:00:00+09:00', '2018-01-03 00:00:00+09:00', '2018-01-04 00:00:00+09:00', '2018-01-05 00:00:00+09:00'], dtype='datetime64[us, Asia/Tokyo]', freq='D') `inclusive` controls whether to include `start` and `end` that are on the boundary. The default, "both", includes boundary points on either end. >>> pd.date_range(start="2017-01-01", end="2017-01-04", inclusive="both") DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03', '2017-01-04'], dtype='datetime64[us]', freq='D') Use ``inclusive='left'`` to exclude `end` if it falls on the boundary. >>> pd.date_range(start="2017-01-01", end="2017-01-04", inclusive="left") DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'], dtype='datetime64[us]', freq='D') Use ``inclusive='right'`` to exclude `start` if it falls on the boundary, and similarly ``inclusive='neither'`` will exclude both `start` and `end`. >>> pd.date_range(start="2017-01-01", end="2017-01-04", inclusive="right") DatetimeIndex(['2017-01-02', '2017-01-03', '2017-01-04'], dtype='datetime64[us]', freq='D') **Specify a unit** >>> pd.date_range(start="2017-01-01", periods=10, freq="100YS", unit="s") DatetimeIndex(['2017-01-01', '2117-01-01', '2217-01-01', '2317-01-01', '2417-01-01', '2517-01-01', '2617-01-01', '2717-01-01', '2817-01-01', '2917-01-01'], dtype='datetime64[s]', freq='100YS-JAN') """ if freq is None and com.any_none(periods, start, end): freq = "D" if freq is not None: freq = to_offset(freq) if start is NaT or end is NaT: # This check needs to come before the `unit = start.unit` line below raise ValueError("Neither `start` nor `end` can be NaT") if unit is None: # Infer the unit based on the inputs if start is not None and end is not None: start = Timestamp(start) end = Timestamp(end) if abbrev_to_npy_unit(start.unit) > abbrev_to_npy_unit(end.unit): unit = start.unit else: unit = end.unit elif start is not None: start = Timestamp(start) unit = start.unit elif end is not None: end = Timestamp(end) unit = end.unit else: raise ValueError( "Of the four parameters: start, end, periods, " "and freq, exactly three must be specified" ) # Last we need to watch out for cases where the 'freq' implies a higher # unit than either start or end if freq is not None: creso = abbrev_to_npy_unit(unit) if isinstance(freq, Tick): if freq._creso > creso: unit = freq.base.freqstr # type: ignore[assignment] elif hasattr(freq, "offset") and freq.offset is not None: # e.g. BDay with an offset td = Timedelta(freq.offset) if abbrev_to_npy_unit(td.unit) > creso: unit = td.unit elif type(freq) is DateOffset: if getattr(freq, "nanoseconds", 0) != 0: # e.g. test_freq_dateoffset_with_relateivedelta_nanos unit = "ns" elif getattr(freq, "microseconds", 0) != 0 and unit != "ns": unit = "us" elif getattr(freq, "milliseconds", 0) != 0 and unit not in ["ns", "us"]: unit = "ms" dtarr = DatetimeArray._generate_range( start=start, end=end, periods=periods, freq=freq, tz=tz, normalize=normalize, ambiguous=ambiguous, nonexistent=nonexistent, inclusive=inclusive, unit=unit, **kwargs, ) result = DatetimeIndex._simple_new(dtarr, name=name) result._freq = freq return result @set_module("pandas") def bdate_range( start=None, end=None, periods: int | None = None, freq: Frequency | dt.timedelta = "B", tz=None, normalize: bool = True, name: Hashable | None = None, weekmask=None, holidays=None, inclusive: IntervalClosedType = "both", **kwargs, ) -> DatetimeIndex: """ Return a fixed frequency DatetimeIndex with business day as the default. This function generates a DatetimeIndex using business day frequency by default, skipping weekends. Custom business day calendars can be specified via ``weekmask`` and ``holidays``. Parameters ---------- start : str or datetime-like, default None Left bound for generating dates. end : str or datetime-like, default None Right bound for generating dates. periods : int, default None Number of periods to generate. freq : str, Timedelta, datetime.timedelta, or DateOffset, default 'B' Frequency strings can have multiples, e.g. '5h'. The default is business daily ('B'). tz : str or None Time zone name for returning localized DatetimeIndex, for example Asia/Beijing. normalize : bool, default False Normalize start/end dates to midnight before generating date range. name : Hashable, default None Name of the resulting DatetimeIndex. weekmask : str or None, default None Weekmask of valid business days, passed to ``numpy.busdaycalendar``, only used when custom frequency strings are passed. The default value None is equivalent to 'Mon Tue Wed Thu Fri'. holidays : list-like or None, default None Dates to exclude from the set of valid business days, passed to ``numpy.busdaycalendar``, only used when custom frequency strings are passed. inclusive : {"both", "neither", "left", "right"}, default "both" Include boundaries; Whether to set each bound as closed or open. **kwargs For compatibility. Has no effect on the result. Returns ------- DatetimeIndex Fixed frequency DatetimeIndex. See Also -------- date_range : Return a fixed frequency DatetimeIndex. period_range : Return a fixed frequency PeriodIndex. timedelta_range : Return a fixed frequency TimedeltaIndex. Notes ----- Of the four parameters: ``start``, ``end``, ``periods``, and ``freq``, exactly three must be specified. Specifying ``freq`` is a requirement for ``bdate_range``. Use ``date_range`` if specifying ``freq`` is not desired. To learn more about the frequency strings, please see :ref:`this link`. Examples -------- Note how the two weekend days are skipped in the result. >>> pd.bdate_range(start="1/1/2018", end="1/08/2018") DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04', '2018-01-05', '2018-01-08'], dtype='datetime64[us]', freq='B') """ if freq is None: msg = "freq must be specified for bdate_range; use date_range instead" raise TypeError(msg) if isinstance(freq, str) and freq.upper().startswith("C"): msg = f"invalid custom frequency string: {freq}" if freq == "CBH": # GH#62849 raise ValueError(f"{msg}, did you mean cbh?") try: weekmask = weekmask or "Mon Tue Wed Thu Fri" freq = prefix_mapping[freq](holidays=holidays, weekmask=weekmask) except (KeyError, TypeError) as err: raise ValueError(msg) from err elif holidays or weekmask: msg = ( "a custom frequency string is required when holidays or " f"weekmask are passed, got frequency {freq}" ) raise ValueError(msg) return date_range( start=start, end=end, periods=periods, freq=freq, tz=tz, normalize=normalize, name=name, inclusive=inclusive, **kwargs, ) def _time_to_micros(time_obj: dt.time) -> int: seconds = time_obj.hour * 60 * 60 + 60 * time_obj.minute + time_obj.second return 1_000_000 * seconds + time_obj.microsecond