1187 lines
39 KiB
Python
1187 lines
39 KiB
Python
from datetime import date, datetime, time, timedelta, tzinfo
|
||
import operator
|
||
from typing import TYPE_CHECKING, Optional, Tuple
|
||
import warnings
|
||
|
||
import numpy as np
|
||
|
||
from pandas._libs import NaT, Period, Timestamp, index as libindex, lib
|
||
from pandas._libs.tslibs import (
|
||
Resolution,
|
||
ints_to_pydatetime,
|
||
parsing,
|
||
timezones,
|
||
to_offset,
|
||
)
|
||
from pandas._libs.tslibs.offsets import prefix_mapping
|
||
from pandas._typing import DtypeObj
|
||
from pandas.errors import InvalidIndexError
|
||
from pandas.util._decorators import cache_readonly, doc
|
||
|
||
from pandas.core.dtypes.common import (
|
||
DT64NS_DTYPE,
|
||
is_datetime64_dtype,
|
||
is_datetime64tz_dtype,
|
||
is_scalar,
|
||
)
|
||
from pandas.core.dtypes.missing import is_valid_nat_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, get_unanimous_names, maybe_extract_name
|
||
from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
|
||
from pandas.core.indexes.extension import inherit_names
|
||
from pandas.core.tools.times import to_time
|
||
|
||
if TYPE_CHECKING:
|
||
from pandas import DataFrame, Float64Index, PeriodIndex, TimedeltaIndex
|
||
|
||
|
||
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), freq=freq)
|
||
else:
|
||
dta = data
|
||
for key in ["tz", "freq"]:
|
||
# These are already stored in our DatetimeArray; if they are
|
||
# also in the pickle and don't match, we have a problem.
|
||
if key in d:
|
||
assert d.pop(key) == getattr(dta, key)
|
||
result = cls._simple_new(dta, **d)
|
||
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
|
||
|
||
|
||
@inherit_names(
|
||
DatetimeArray._field_ops
|
||
+ [
|
||
method
|
||
for method in DatetimeArray._datetimelike_methods
|
||
if method not in ("tz_localize", "tz_convert")
|
||
],
|
||
DatetimeArray,
|
||
wrap=True,
|
||
)
|
||
@inherit_names(["is_normalized", "_resolution_obj"], DatetimeArray, cache=True)
|
||
@inherit_names(
|
||
[
|
||
"_bool_ops",
|
||
"_object_ops",
|
||
"_field_ops",
|
||
"_datetimelike_ops",
|
||
"_datetimelike_methods",
|
||
"tz",
|
||
"tzinfo",
|
||
"dtype",
|
||
"to_pydatetime",
|
||
"_has_same_tz",
|
||
"_format_native_types",
|
||
"date",
|
||
"time",
|
||
"timetz",
|
||
"std",
|
||
]
|
||
+ DatetimeArray._bool_ops,
|
||
DatetimeArray,
|
||
)
|
||
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.
|
||
|
||
Parameters
|
||
----------
|
||
data : array-like (1-dimensional), optional
|
||
Optional 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 : pytz.timezone or dateutil.tz.tzfile or datetime.tzinfo or str
|
||
Set the Timezone of the data.
|
||
normalize : bool, default False
|
||
Normalize start/end dates to midnight before generating date range.
|
||
closed : {'left', 'right'}, optional
|
||
Set whether to include `start` and `end` that are on the
|
||
boundary. The default includes boundary points on either end.
|
||
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
|
||
- 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 an AmbiguousTimeError if there are ambiguous times.
|
||
dayfirst : bool, default False
|
||
If True, parse dates in `data` with the day first order.
|
||
yearfirst : bool, default False
|
||
If True parse dates in `data` with the year first order.
|
||
dtype : numpy.dtype or DatetimeTZDtype or str, default None
|
||
Note that the only NumPy dtype allowed is ‘datetime64[ns]’.
|
||
copy : bool, default False
|
||
Make a copy of input ndarray.
|
||
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
|
||
weekofyear
|
||
week
|
||
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_perioddelta
|
||
to_pydatetime
|
||
to_series
|
||
to_frame
|
||
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 `this link
|
||
<https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases>`__.
|
||
"""
|
||
|
||
_typ = "datetimeindex"
|
||
|
||
_data_cls = DatetimeArray
|
||
_engine_type = libindex.DatetimeEngine
|
||
_supports_partial_string_indexing = True
|
||
|
||
_comparables = ["name", "freqstr", "tz"]
|
||
_attributes = ["name", "tz", "freq"]
|
||
|
||
_is_numeric_dtype = False
|
||
|
||
_data: DatetimeArray
|
||
inferred_freq: Optional[str]
|
||
tz: Optional[tzinfo]
|
||
|
||
# --------------------------------------------------------------------
|
||
# methods that dispatch to DatetimeArray and wrap result
|
||
|
||
@doc(DatetimeArray.strftime)
|
||
def strftime(self, date_format) -> Index:
|
||
arr = self._data.strftime(date_format)
|
||
return Index(arr, name=self.name)
|
||
|
||
@doc(DatetimeArray.tz_convert)
|
||
def tz_convert(self, tz) -> "DatetimeIndex":
|
||
arr = self._data.tz_convert(tz)
|
||
return type(self)._simple_new(arr, name=self.name)
|
||
|
||
@doc(DatetimeArray.tz_localize)
|
||
def tz_localize(
|
||
self, tz, ambiguous="raise", nonexistent="raise"
|
||
) -> "DatetimeIndex":
|
||
arr = self._data.tz_localize(tz, ambiguous, nonexistent)
|
||
return type(self)._simple_new(arr, name=self.name)
|
||
|
||
@doc(DatetimeArray.to_period)
|
||
def to_period(self, freq=None) -> "PeriodIndex":
|
||
from pandas.core.indexes.api import PeriodIndex
|
||
|
||
arr = self._data.to_period(freq)
|
||
return PeriodIndex._simple_new(arr, name=self.name)
|
||
|
||
@doc(DatetimeArray.to_perioddelta)
|
||
def to_perioddelta(self, freq) -> "TimedeltaIndex":
|
||
from pandas.core.indexes.api import TimedeltaIndex
|
||
|
||
arr = self._data.to_perioddelta(freq)
|
||
return TimedeltaIndex._simple_new(arr, name=self.name)
|
||
|
||
@doc(DatetimeArray.to_julian_date)
|
||
def to_julian_date(self) -> "Float64Index":
|
||
from pandas.core.indexes.api import Float64Index
|
||
|
||
arr = self._data.to_julian_date()
|
||
return Float64Index._simple_new(arr, name=self.name)
|
||
|
||
@doc(DatetimeArray.isocalendar)
|
||
def isocalendar(self) -> "DataFrame":
|
||
df = self._data.isocalendar()
|
||
return df.set_index(self)
|
||
|
||
# --------------------------------------------------------------------
|
||
# Constructors
|
||
|
||
def __new__(
|
||
cls,
|
||
data=None,
|
||
freq=lib.no_default,
|
||
tz=None,
|
||
normalize=False,
|
||
closed=None,
|
||
ambiguous="raise",
|
||
dayfirst=False,
|
||
yearfirst=False,
|
||
dtype=None,
|
||
copy=False,
|
||
name=None,
|
||
):
|
||
|
||
if is_scalar(data):
|
||
raise TypeError(
|
||
f"{cls.__name__}() must be called with a "
|
||
f"collection of some kind, {repr(data)} was passed"
|
||
)
|
||
|
||
# - Cases checked above all return/raise before reaching here - #
|
||
|
||
name = maybe_extract_name(name, data, cls)
|
||
|
||
dtarr = DatetimeArray._from_sequence_not_strict(
|
||
data,
|
||
dtype=dtype,
|
||
copy=copy,
|
||
tz=tz,
|
||
freq=freq,
|
||
dayfirst=dayfirst,
|
||
yearfirst=yearfirst,
|
||
ambiguous=ambiguous,
|
||
)
|
||
|
||
subarr = cls._simple_new(dtarr, name=name)
|
||
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
|
||
"""
|
||
from pandas.io.formats.format import is_dates_only
|
||
|
||
return self.tz is None and is_dates_only(self._values)
|
||
|
||
def __reduce__(self):
|
||
|
||
# we use a special reduce here because we need
|
||
# to simply set the .tz (and not reinterpret it)
|
||
|
||
d = {"data": self._data}
|
||
d.update(self._get_attributes_dict())
|
||
return _new_DatetimeIndex, (type(self), d), None
|
||
|
||
def _validate_fill_value(self, value):
|
||
"""
|
||
Convert value to be insertable to ndarray.
|
||
"""
|
||
return self._data._validate_setitem_value(value)
|
||
|
||
def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
|
||
"""
|
||
Can we compare values of the given dtype to our own?
|
||
"""
|
||
if self.tz is not None:
|
||
# If we have tz, we can compare to tzaware
|
||
return is_datetime64tz_dtype(dtype)
|
||
# if we dont have tz, we can only compare to tznaive
|
||
return is_datetime64_dtype(dtype)
|
||
|
||
# --------------------------------------------------------------------
|
||
# Rendering Methods
|
||
|
||
def _mpl_repr(self):
|
||
# how to represent ourselves to matplotlib
|
||
return ints_to_pydatetime(self.asi8, self.tz)
|
||
|
||
@property
|
||
def _formatter_func(self):
|
||
from pandas.io.formats.format import get_format_datetime64
|
||
|
||
formatter = get_format_datetime64(is_dates_only=self._is_dates_only)
|
||
return lambda x: f"'{formatter(x)}'"
|
||
|
||
# --------------------------------------------------------------------
|
||
# Set Operation Methods
|
||
|
||
def union_many(self, others):
|
||
"""
|
||
A bit of a hack to accelerate unioning a collection of indexes.
|
||
"""
|
||
this = self
|
||
|
||
for other in others:
|
||
if not isinstance(this, DatetimeIndex):
|
||
this = Index.union(this, other)
|
||
continue
|
||
|
||
if not isinstance(other, DatetimeIndex):
|
||
try:
|
||
other = DatetimeIndex(other)
|
||
except TypeError:
|
||
pass
|
||
|
||
this, other = this._maybe_utc_convert(other)
|
||
|
||
if this._can_fast_union(other):
|
||
this = this._fast_union(other)
|
||
else:
|
||
this = Index.union(this, other)
|
||
|
||
res_name = get_unanimous_names(self, *others)[0]
|
||
if this.name != res_name:
|
||
return this.rename(res_name)
|
||
return this
|
||
|
||
def _maybe_utc_convert(self, other: Index) -> Tuple["DatetimeIndex", Index]:
|
||
this = self
|
||
|
||
if isinstance(other, DatetimeIndex):
|
||
if self.tz is not None:
|
||
if other.tz is None:
|
||
raise TypeError("Cannot join tz-naive with tz-aware DatetimeIndex")
|
||
elif other.tz is not None:
|
||
raise TypeError("Cannot join tz-naive with tz-aware DatetimeIndex")
|
||
|
||
if not timezones.tz_compare(self.tz, other.tz):
|
||
this = self.tz_convert("UTC")
|
||
other = other.tz_convert("UTC")
|
||
return this, other
|
||
|
||
# --------------------------------------------------------------------
|
||
|
||
def _get_time_micros(self):
|
||
"""
|
||
Return the number of microseconds since midnight.
|
||
|
||
Returns
|
||
-------
|
||
ndarray[int64_t]
|
||
"""
|
||
values = self._data._local_timestamps()
|
||
|
||
nanos = values % (24 * 3600 * 1_000_000_000)
|
||
micros = nanos // 1000
|
||
|
||
micros[self._isnan] = -1
|
||
return micros
|
||
|
||
def to_series(self, keep_tz=lib.no_default, index=None, name=None):
|
||
"""
|
||
Create a Series with both index and values equal to the index keys
|
||
useful with map for returning an indexer based on an index.
|
||
|
||
Parameters
|
||
----------
|
||
keep_tz : optional, defaults True
|
||
Return the data keeping the timezone.
|
||
|
||
If keep_tz is True:
|
||
|
||
If the timezone is not set, the resulting
|
||
Series will have a datetime64[ns] dtype.
|
||
|
||
Otherwise the Series will have an datetime64[ns, tz] dtype; the
|
||
tz will be preserved.
|
||
|
||
If keep_tz is False:
|
||
|
||
Series will have a datetime64[ns] dtype. TZ aware
|
||
objects will have the tz removed.
|
||
|
||
.. versionchanged:: 1.0.0
|
||
The default value is now True. In a future version,
|
||
this keyword will be removed entirely. Stop passing the
|
||
argument to obtain the future behavior and silence the warning.
|
||
|
||
index : Index, optional
|
||
Index of resulting Series. If None, defaults to original index.
|
||
name : str, optional
|
||
Name of resulting Series. If None, defaults to name of original
|
||
index.
|
||
|
||
Returns
|
||
-------
|
||
Series
|
||
"""
|
||
from pandas import Series
|
||
|
||
if index is None:
|
||
index = self._shallow_copy()
|
||
if name is None:
|
||
name = self.name
|
||
|
||
if keep_tz is not lib.no_default:
|
||
if keep_tz:
|
||
warnings.warn(
|
||
"The 'keep_tz' keyword in DatetimeIndex.to_series "
|
||
"is deprecated and will be removed in a future version. "
|
||
"You can stop passing 'keep_tz' to silence this warning.",
|
||
FutureWarning,
|
||
stacklevel=2,
|
||
)
|
||
else:
|
||
warnings.warn(
|
||
"Specifying 'keep_tz=False' is deprecated and this "
|
||
"option will be removed in a future release. If "
|
||
"you want to remove the timezone information, you "
|
||
"can do 'idx.tz_convert(None)' before calling "
|
||
"'to_series'.",
|
||
FutureWarning,
|
||
stacklevel=2,
|
||
)
|
||
else:
|
||
keep_tz = True
|
||
|
||
if keep_tz and self.tz is not None:
|
||
# preserve the tz & copy
|
||
values = self.copy(deep=True)
|
||
else:
|
||
values = self._values.view("M8[ns]").copy()
|
||
|
||
return Series(values, index=index, name=name)
|
||
|
||
def snap(self, freq="S"):
|
||
"""
|
||
Snap time stamps to nearest occurring frequency.
|
||
|
||
Returns
|
||
-------
|
||
DatetimeIndex
|
||
"""
|
||
# Superdumb, punting on any optimizing
|
||
freq = to_offset(freq)
|
||
|
||
snapped = np.empty(len(self), dtype=DT64NS_DTYPE)
|
||
|
||
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
|
||
snapped[i] = s
|
||
|
||
dta = DatetimeArray(snapped, dtype=self.dtype)
|
||
return DatetimeIndex._simple_new(dta, name=self.name)
|
||
|
||
# --------------------------------------------------------------------
|
||
# Indexing Methods
|
||
|
||
def _parsed_string_to_bounds(self, reso: Resolution, parsed: datetime):
|
||
"""
|
||
Calculate datetime bounds for parsed time string and its resolution.
|
||
|
||
Parameters
|
||
----------
|
||
reso : str
|
||
Resolution provided by parsed string.
|
||
parsed : datetime
|
||
Datetime from parsed string.
|
||
|
||
Returns
|
||
-------
|
||
lower, upper: pd.Timestamp
|
||
"""
|
||
assert isinstance(reso, Resolution), (type(reso), reso)
|
||
valid_resos = {
|
||
"year",
|
||
"month",
|
||
"quarter",
|
||
"day",
|
||
"hour",
|
||
"minute",
|
||
"second",
|
||
"minute",
|
||
"second",
|
||
"microsecond",
|
||
}
|
||
if reso.attrname not in valid_resos:
|
||
raise KeyError
|
||
|
||
grp = reso.freq_group
|
||
per = Period(parsed, freq=grp)
|
||
start, end = per.start_time, per.end_time
|
||
|
||
# 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
|
||
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"
|
||
)
|
||
start = start.tz_localize(parsed.tzinfo).tz_convert(self.tz)
|
||
end = end.tz_localize(parsed.tzinfo).tz_convert(self.tz)
|
||
elif self.tz is not None:
|
||
start = start.tz_localize(self.tz)
|
||
end = end.tz_localize(self.tz)
|
||
return start, end
|
||
|
||
def _validate_partial_date_slice(self, reso: Resolution):
|
||
assert isinstance(reso, Resolution), (type(reso), reso)
|
||
if (
|
||
self.is_monotonic
|
||
and reso.attrname in ["day", "hour", "minute", "second"]
|
||
and self._resolution_obj >= reso
|
||
):
|
||
# These resolution/monotonicity validations came from GH3931,
|
||
# GH3452 and GH2369.
|
||
|
||
# See also GH14826
|
||
raise KeyError
|
||
|
||
if reso == "microsecond":
|
||
# _partial_date_slice doesn't allow microsecond resolution, but
|
||
# _parsed_string_to_bounds allows it.
|
||
raise KeyError
|
||
|
||
def _deprecate_mismatched_indexing(self, key):
|
||
# GH#36148
|
||
# we get here with isinstance(key, self._data._recognized_scalars)
|
||
try:
|
||
self._data._assert_tzawareness_compat(key)
|
||
except TypeError:
|
||
if self.tz is None:
|
||
msg = (
|
||
"Indexing a timezone-naive DatetimeIndex with a "
|
||
"timezone-aware datetime is deprecated and will "
|
||
"raise KeyError in a future version. "
|
||
"Use a timezone-naive object instead."
|
||
)
|
||
else:
|
||
msg = (
|
||
"Indexing a timezone-aware DatetimeIndex with a "
|
||
"timezone-naive datetime is deprecated and will "
|
||
"raise KeyError in a future version. "
|
||
"Use a timezone-aware object instead."
|
||
)
|
||
warnings.warn(msg, FutureWarning, stacklevel=5)
|
||
|
||
def get_loc(self, key, method=None, tolerance=None):
|
||
"""
|
||
Get integer location for requested label
|
||
|
||
Returns
|
||
-------
|
||
loc : int
|
||
"""
|
||
if not is_scalar(key):
|
||
raise InvalidIndexError(key)
|
||
|
||
orig_key = key
|
||
if is_valid_nat_for_dtype(key, self.dtype):
|
||
key = NaT
|
||
|
||
if isinstance(key, self._data._recognized_scalars):
|
||
# needed to localize naive datetimes
|
||
self._deprecate_mismatched_indexing(key)
|
||
key = self._maybe_cast_for_get_loc(key)
|
||
|
||
elif isinstance(key, str):
|
||
try:
|
||
return self._get_string_slice(key)
|
||
except (TypeError, KeyError, ValueError, OverflowError):
|
||
pass
|
||
|
||
try:
|
||
key = self._maybe_cast_for_get_loc(key)
|
||
except ValueError as err:
|
||
raise KeyError(key) from err
|
||
|
||
elif isinstance(key, timedelta):
|
||
# GH#20464
|
||
raise TypeError(
|
||
f"Cannot index {type(self).__name__} with {type(key).__name__}"
|
||
)
|
||
|
||
elif isinstance(key, time):
|
||
if method is not None:
|
||
raise NotImplementedError(
|
||
"cannot yet lookup inexact labels when key is a time object"
|
||
)
|
||
return self.indexer_at_time(key)
|
||
|
||
else:
|
||
# unrecognized type
|
||
raise KeyError(key)
|
||
|
||
try:
|
||
return Index.get_loc(self, key, method, tolerance)
|
||
except KeyError as err:
|
||
raise KeyError(orig_key) from err
|
||
|
||
def _maybe_cast_for_get_loc(self, key) -> Timestamp:
|
||
# needed to localize naive datetimes or dates (GH 35690)
|
||
key = Timestamp(key)
|
||
if key.tzinfo is None:
|
||
key = key.tz_localize(self.tz)
|
||
else:
|
||
key = key.tz_convert(self.tz)
|
||
return key
|
||
|
||
def _maybe_cast_slice_bound(self, label, side: str, kind):
|
||
"""
|
||
If label is a string, cast it to datetime according to resolution.
|
||
|
||
Parameters
|
||
----------
|
||
label : object
|
||
side : {'left', 'right'}
|
||
kind : {'loc', 'getitem'} or None
|
||
|
||
Returns
|
||
-------
|
||
label : object
|
||
|
||
Notes
|
||
-----
|
||
Value of `side` parameter should be validated in caller.
|
||
"""
|
||
assert kind in ["loc", "getitem", None]
|
||
|
||
if isinstance(label, str):
|
||
freq = getattr(self, "freqstr", getattr(self, "inferred_freq", None))
|
||
try:
|
||
parsed, reso = parsing.parse_time_string(label, freq)
|
||
except parsing.DateParseError as err:
|
||
raise self._invalid_indexer("slice", label) from err
|
||
|
||
reso = Resolution.from_attrname(reso)
|
||
lower, upper = self._parsed_string_to_bounds(reso, parsed)
|
||
# lower, upper form the half-open interval:
|
||
# [parsed, parsed + 1 freq)
|
||
# because label may be passed to searchsorted
|
||
# the bounds need swapped if index is reverse sorted and has a
|
||
# length > 1 (is_monotonic_decreasing gives True for empty
|
||
# and length 1 index)
|
||
if self._is_strictly_monotonic_decreasing and len(self) > 1:
|
||
return upper if side == "left" else lower
|
||
return lower if side == "left" else upper
|
||
elif isinstance(label, (self._data._recognized_scalars, date)):
|
||
self._deprecate_mismatched_indexing(label)
|
||
else:
|
||
raise self._invalid_indexer("slice", label)
|
||
|
||
return self._maybe_cast_for_get_loc(label)
|
||
|
||
def _get_string_slice(self, key: str):
|
||
freq = getattr(self, "freqstr", getattr(self, "inferred_freq", None))
|
||
parsed, reso = parsing.parse_time_string(key, freq)
|
||
reso = Resolution.from_attrname(reso)
|
||
loc = self._partial_date_slice(reso, parsed)
|
||
return loc
|
||
|
||
def slice_indexer(self, start=None, end=None, step=None, kind=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, time) and isinstance(end, 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, time) or isinstance(end, time):
|
||
raise KeyError("Cannot mix time and non-time slice keys")
|
||
|
||
# Pandas supports slicing with dates, treated as datetimes at midnight.
|
||
# https://github.com/pandas-dev/pandas/issues/31501
|
||
if isinstance(start, date) and not isinstance(start, datetime):
|
||
start = datetime.combine(start, time(0, 0))
|
||
if isinstance(end, date) and not isinstance(end, datetime):
|
||
end = datetime.combine(end, time(0, 0))
|
||
|
||
try:
|
||
return Index.slice_indexer(self, start, end, step, kind=kind)
|
||
except KeyError:
|
||
# For historical reasons DatetimeIndex by default supports
|
||
# value-based partial (aka string) slices on non-monotonic arrays,
|
||
# let's try that.
|
||
if (start is None or isinstance(start, str)) and (
|
||
end is None or isinstance(end, str)
|
||
):
|
||
mask = np.array(True)
|
||
deprecation_mask = np.array(True)
|
||
if start is not None:
|
||
start_casted = self._maybe_cast_slice_bound(start, "left", kind)
|
||
mask = start_casted <= self
|
||
deprecation_mask = start_casted == self
|
||
|
||
if end is not None:
|
||
end_casted = self._maybe_cast_slice_bound(end, "right", kind)
|
||
mask = (self <= end_casted) & mask
|
||
deprecation_mask = (end_casted == self) | deprecation_mask
|
||
|
||
if not deprecation_mask.any():
|
||
warnings.warn(
|
||
"Value based partial slicing on non-monotonic DatetimeIndexes "
|
||
"with non-existing keys is deprecated and will raise a "
|
||
"KeyError in a future Version.",
|
||
FutureWarning,
|
||
stacklevel=5,
|
||
)
|
||
indexer = mask.nonzero()[0][::step]
|
||
if len(indexer) == len(self):
|
||
return slice(None)
|
||
else:
|
||
return indexer
|
||
else:
|
||
raise
|
||
|
||
# --------------------------------------------------------------------
|
||
|
||
@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=False):
|
||
"""
|
||
Return index locations of values at particular time of day
|
||
(e.g. 9:30AM).
|
||
|
||
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").
|
||
|
||
Returns
|
||
-------
|
||
values_at_time : array of integers
|
||
|
||
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.
|
||
"""
|
||
if asof:
|
||
raise NotImplementedError("'asof' argument is not supported")
|
||
|
||
if isinstance(time, str):
|
||
from dateutil.parser import parse
|
||
|
||
time = parse(time).time()
|
||
|
||
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 (micros == time_micros).nonzero()[0]
|
||
|
||
def indexer_between_time(
|
||
self, start_time, end_time, include_start=True, include_end=True
|
||
):
|
||
"""
|
||
Return index locations of values between particular times of day
|
||
(e.g., 9:00-9:30AM).
|
||
|
||
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_end : bool, default True
|
||
|
||
Returns
|
||
-------
|
||
values_between_time : array of integers
|
||
|
||
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.
|
||
"""
|
||
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]
|
||
|
||
|
||
def date_range(
|
||
start=None,
|
||
end=None,
|
||
periods=None,
|
||
freq=None,
|
||
tz=None,
|
||
normalize=False,
|
||
name=None,
|
||
closed=None,
|
||
**kwargs,
|
||
) -> DatetimeIndex:
|
||
"""
|
||
Return a fixed frequency DatetimeIndex.
|
||
|
||
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 or DateOffset, default 'D'
|
||
Frequency strings can have multiples, e.g. '5H'. See
|
||
:ref:`here <timeseries.offset_aliases>` 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.
|
||
normalize : bool, default False
|
||
Normalize start/end dates to midnight before generating date range.
|
||
name : str, default None
|
||
Name of the resulting DatetimeIndex.
|
||
closed : {None, 'left', 'right'}, optional
|
||
Make the interval closed with respect to the given frequency to
|
||
the 'left', 'right', or both sides (None, the default).
|
||
**kwargs
|
||
For compatibility. Has no effect on the result.
|
||
|
||
Returns
|
||
-------
|
||
rng : DatetimeIndex
|
||
|
||
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``,
|
||
exactly three 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 `this link
|
||
<https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases>`__.
|
||
|
||
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[ns]', 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[ns]', 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[ns]', 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[ns]', freq=None)
|
||
|
||
**Other Parameters**
|
||
|
||
Changed the `freq` (frequency) to ``'M'`` (month end frequency).
|
||
|
||
>>> pd.date_range(start='1/1/2018', periods=5, freq='M')
|
||
DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31', '2018-04-30',
|
||
'2018-05-31'],
|
||
dtype='datetime64[ns]', freq='M')
|
||
|
||
Multiples are allowed
|
||
|
||
>>> pd.date_range(start='1/1/2018', periods=5, freq='3M')
|
||
DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31',
|
||
'2019-01-31'],
|
||
dtype='datetime64[ns]', freq='3M')
|
||
|
||
`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[ns]', freq='3M')
|
||
|
||
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[ns, Asia/Tokyo]', freq='D')
|
||
|
||
`closed` controls whether to include `start` and `end` that are on the
|
||
boundary. The default includes boundary points on either end.
|
||
|
||
>>> pd.date_range(start='2017-01-01', end='2017-01-04', closed=None)
|
||
DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03', '2017-01-04'],
|
||
dtype='datetime64[ns]', freq='D')
|
||
|
||
Use ``closed='left'`` to exclude `end` if it falls on the boundary.
|
||
|
||
>>> pd.date_range(start='2017-01-01', end='2017-01-04', closed='left')
|
||
DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'],
|
||
dtype='datetime64[ns]', freq='D')
|
||
|
||
Use ``closed='right'`` to exclude `start` if it falls on the boundary.
|
||
|
||
>>> pd.date_range(start='2017-01-01', end='2017-01-04', closed='right')
|
||
DatetimeIndex(['2017-01-02', '2017-01-03', '2017-01-04'],
|
||
dtype='datetime64[ns]', freq='D')
|
||
"""
|
||
if freq is None and com.any_none(periods, start, end):
|
||
freq = "D"
|
||
|
||
dtarr = DatetimeArray._generate_range(
|
||
start=start,
|
||
end=end,
|
||
periods=periods,
|
||
freq=freq,
|
||
tz=tz,
|
||
normalize=normalize,
|
||
closed=closed,
|
||
**kwargs,
|
||
)
|
||
return DatetimeIndex._simple_new(dtarr, name=name)
|
||
|
||
|
||
def bdate_range(
|
||
start=None,
|
||
end=None,
|
||
periods=None,
|
||
freq="B",
|
||
tz=None,
|
||
normalize=True,
|
||
name=None,
|
||
weekmask=None,
|
||
holidays=None,
|
||
closed=None,
|
||
**kwargs,
|
||
) -> DatetimeIndex:
|
||
"""
|
||
Return a fixed frequency DatetimeIndex, with business day as the default
|
||
frequency.
|
||
|
||
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 or DateOffset, default 'B' (business daily)
|
||
Frequency strings can have multiples, e.g. '5H'.
|
||
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 : str, 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.
|
||
closed : str, default None
|
||
Make the interval closed with respect to the given frequency to
|
||
the 'left', 'right', or both sides (None).
|
||
**kwargs
|
||
For compatibility. Has no effect on the result.
|
||
|
||
Returns
|
||
-------
|
||
DatetimeIndex
|
||
|
||
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 `this link
|
||
<https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases>`__.
|
||
|
||
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[ns]', 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.startswith("C"):
|
||
try:
|
||
weekmask = weekmask or "Mon Tue Wed Thu Fri"
|
||
freq = prefix_mapping[freq](holidays=holidays, weekmask=weekmask)
|
||
except (KeyError, TypeError) as err:
|
||
msg = f"invalid custom frequency string: {freq}"
|
||
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,
|
||
closed=closed,
|
||
**kwargs,
|
||
)
|
||
|
||
|
||
def _time_to_micros(time_obj: time) -> int:
|
||
seconds = time_obj.hour * 60 * 60 + 60 * time_obj.minute + time_obj.second
|
||
return 1_000_000 * seconds + time_obj.microsecond
|