Skip to content

Commit 295323c

Browse files
author
tp
committed
Improve doc strings, also indexer_at/between/_time
1 parent eb974ce commit 295323c

File tree

3 files changed

+96
-53
lines changed

3 files changed

+96
-53
lines changed

doc/source/whatsnew/v0.23.0.txt

+4
Original file line numberDiff line numberDiff line change
@@ -916,6 +916,10 @@ Datetimelike API Changes
916916
- :class:`CacheableOffset` and :class:`WeekDay` are no longer available in the ``pandas.tseries.offsets`` module (:issue:`17830`)
917917
- ``pandas.tseries.frequencies.get_freq_group()`` and ``pandas.tseries.frequencies.DAYS`` are removed from the public API (:issue:`18034`)
918918
- :func:`Series.truncate` and :func:`DataFrame.truncate` will raise a ``ValueError`` if the index is not sorted instead of an unhelpful ``KeyError`` (:issue:`17935`)
919+
- :attr:`Series.at_time` and :attr:`DataFrame.at_time` will now raise a ``TypeError``
920+
rather than ``NotImplementedError`` when index is not a :class:`DatetimeIndex`` (:issue:`20725`).
921+
- :attr:`Series.between_time` and :attr:`DateFrame.between_time` will now raise
922+
a ``TypeError`` rather than ``NotImplementedError`` when index is not a :class:`DatetimeIndex`` (:issue:`20725`).
919923
- Restricted ``DateOffset`` keyword arguments. Previously, ``DateOffset`` subclasses allowed arbitrary keyword arguments which could lead to unexpected behavior. Now, only valid arguments will be accepted. (:issue:`17176`, :issue:`18226`).
920924
- :func:`pandas.merge` provides a more informative error message when trying to merge on timezone-aware and timezone-naive columns (:issue:`15800`)
921925
- For :class:`DatetimeIndex` and :class:`TimedeltaIndex` with ``freq=None``, addition or subtraction of integer-dtyped array or ``Index`` will raise ``NullFrequencyError`` instead of ``TypeError`` (:issue:`19895`)

pandas/core/generic.py

+74-44
Original file line numberDiff line numberDiff line change
@@ -6761,9 +6761,10 @@ def at_time(self, time, asof=False):
67616761
"""
67626762
Select values at particular time of day (e.g. 9:30AM).
67636763
6764-
Notes
6765-
-----
6766-
For this method to work, the index must to be a :class:`DatetimeIndex`
6764+
Raises
6765+
------
6766+
TypeError
6767+
If the index is not a :class:`DatetimeIndex`
67676768
67686769
Parameters
67696770
----------
@@ -6775,25 +6776,27 @@ def at_time(self, time, asof=False):
67756776
67766777
Examples
67776778
--------
6778-
>>> i = pd.date_range('2018-04-09', periods=4, freq='4D2min')
6779+
>>> i = pd.date_range('2018-04-09', periods=4, freq='12H')
67796780
>>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
67806781
>>> ts
67816782
A
6782-
date
67836783
2018-04-09 00:00:00 1
6784-
2018-04-13 00:02:00 2
6785-
2018-04-17 00:04:00 3
6786-
2018-04-21 00:06:00 4
6787-
>>> ts.at_time('0:02')
6784+
2018-04-09 12:00:00 2
6785+
2018-04-10 00:00:00 3
6786+
2018-04-10 12:00:00 4
6787+
6788+
>>> ts.at_time('12:00')
67886789
A
6789-
date
6790-
2018-04-13 00:02:00 2
6790+
2018-04-09 12:00:00 2
6791+
2018-04-10 12:00:00 4
67916792
67926793
See Also
67936794
--------
67946795
between_time : Select values between particular times of the day
67956796
first : Select initial periods of time series based on a date offset
67966797
last : Select final periods of time series based on a date offset
6798+
DatetimeIndex.indexer_at_time : Get just the index locations for
6799+
values at particular time of the day
67976800
"""
67986801
try:
67996802
indexer = self.index.indexer_at_time(time, asof=asof)
@@ -6806,9 +6809,13 @@ def between_time(self, start_time, end_time, include_start=True,
68066809
"""
68076810
Select values between particular times of the day (e.g., 9:00-9:30 AM).
68086811
6809-
Notes
6810-
-----
6811-
For this method to work, the index must to be a :class:`DatetimeIndex`
6812+
By setting ``start_time`` to be later than ``end_time``,
6813+
you can get the times that are *not* between the two times.
6814+
6815+
Raises
6816+
------
6817+
TypeError
6818+
If the index is not a :class:`DatetimeIndex`
68126819
68136820
Parameters
68146821
----------
@@ -6823,24 +6830,35 @@ def between_time(self, start_time, end_time, include_start=True,
68236830
68246831
Examples
68256832
--------
6826-
>>> i = pd.date_range('2018-04-09', periods=4, freq='2min')
6833+
>>> i = pd.date_range('2018-04-09', periods=4, freq='1D20min')
68276834
>>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
68286835
>>> ts
68296836
A
68306837
2018-04-09 00:00:00 1
6831-
2018-04-09 00:02:00 2
6832-
2018-04-09 00:04:00 3
6833-
2018-04-09 00:06:00 4
6834-
>>> ts.between_time('0:02', '0:04')
6838+
2018-04-10 00:20:00 2
6839+
2018-04-11 00:40:00 3
6840+
2018-04-12 01:00:00 4
6841+
6842+
>>> ts.between_time('0:15', '0:45')
68356843
A
6836-
2018-04-09 00:02:00 2
6837-
2018-04-09 00:04:00 3
6844+
2018-04-10 00:20:00 2
6845+
2018-04-11 00:40:00 3
6846+
6847+
You get the times that are *not* between two times by setting
6848+
``start_time`` later than ``end_time``:
6849+
6850+
>>> ts.between_time('0:45', '0:15')
6851+
A
6852+
2018-04-09 00:00:00 1
6853+
2018-04-12 01:00:00 4
68386854
68396855
See Also
68406856
--------
68416857
at_time : Select values at a particular time of the day
68426858
first : Select initial periods of time series based on a date offset
68436859
last : Select final periods of time series based on a date offset
6860+
DatetimeIndex.indexer_between_time : Get just the index locations for
6861+
values between particular times of the day
68446862
"""
68456863
try:
68466864
indexer = self.index.indexer_between_time(
@@ -7094,29 +7112,36 @@ def first(self, offset):
70947112
Convenience method for subsetting initial periods of time series data
70957113
based on a date offset.
70967114
7097-
Notes
7098-
-----
7099-
For this method to work, the index must to be a :class:`DatetimeIndex`
7115+
Raises
7116+
------
7117+
TypeError
7118+
If the index is not a :class:`DatetimeIndex`
71007119
71017120
Parameters
71027121
----------
71037122
offset : string, DateOffset, dateutil.relativedelta
71047123
71057124
Examples
71067125
--------
7107-
>>> i = pd.date_range('2018-04-09', periods=4, freq='D')
7126+
>>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
71087127
>>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
71097128
>>> ts
71107129
A
71117130
2018-04-09 1
7112-
2018-04-10 2
7113-
2018-04-11 3
7114-
2018-04-12 4
7131+
2018-04-11 2
7132+
2018-04-13 3
7133+
2018-04-15 4
7134+
7135+
Get the rows for the first 3 days:
7136+
71157137
>>> ts.first('3D')
71167138
A
71177139
2018-04-09 1
7118-
2018-04-10 2
7119-
2018-04-11 3
7140+
2018-04-11 2
7141+
7142+
Notice the data for 3 first calender days were returned, not the first
7143+
3 days observed in the dataset, and therefore data for 2018-04-13 was
7144+
not returned.
71207145
71217146
Returns
71227147
-------
@@ -7130,8 +7155,7 @@ def first(self, offset):
71307155
"""
71317156
from pandas.tseries.frequencies import to_offset
71327157
if not isinstance(self.index, DatetimeIndex):
7133-
raise NotImplementedError("'first' only supports a DatetimeIndex "
7134-
"index")
7158+
raise TypeError("'first' only supports a DatetimeIndex index")
71357159

71367160
if len(self.index) == 0:
71377161
return self
@@ -7152,29 +7176,36 @@ def last(self, offset):
71527176
Convenience method for subsetting final periods of time series data
71537177
based on a date offset.
71547178
7155-
Notes
7156-
-----
7157-
For this method to work, the index must to be a :class:`DatetimeIndex`
7179+
Raises
7180+
------
7181+
TypeError
7182+
If the index is not a :class:`DatetimeIndex`
71587183
71597184
Parameters
71607185
----------
71617186
offset : string, DateOffset, dateutil.relativedelta
71627187
71637188
Examples
71647189
--------
7165-
>>> i = pd.date_range('2018-04-09', periods=4, freq='D')
7190+
>>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
71667191
>>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
71677192
>>> ts
71687193
A
71697194
2018-04-09 1
7170-
2018-04-10 2
7171-
2018-04-11 3
7172-
2018-04-12 4
7195+
2018-04-11 2
7196+
2018-04-13 3
7197+
2018-04-15 4
7198+
7199+
Get the rows for the last 3 days:
7200+
71737201
>>> ts.last('3D')
71747202
A
7175-
2018-04-10 2
7176-
2018-04-11 3
7177-
2018-04-12 4
7203+
2018-04-13 3
7204+
2018-04-15 4
7205+
7206+
Notice the data for 3 last calender days were returned, not the last
7207+
3 observed days in the dataset, and therefore data for 2018-04-11 was
7208+
not returned.
71787209
71797210
Returns
71807211
-------
@@ -7188,8 +7219,7 @@ def last(self, offset):
71887219
"""
71897220
from pandas.tseries.frequencies import to_offset
71907221
if not isinstance(self.index, DatetimeIndex):
7191-
raise NotImplementedError("'last' only supports a DatetimeIndex "
7192-
"index")
7222+
raise TypeError("'last' only supports a DatetimeIndex index")
71937223

71947224
if len(self.index) == 0:
71957225
return self

pandas/core/indexes/datetimes.py

+18-9
Original file line numberDiff line numberDiff line change
@@ -2368,15 +2368,23 @@ def tz_localize(self, tz, ambiguous='raise', errors='raise'):
23682368

23692369
def indexer_at_time(self, time, asof=False):
23702370
"""
2371-
Select values at particular time of day (e.g. 9:30AM)
2371+
Returns index locations of index values at particular time of day
2372+
(e.g. 9:30AM).
23722373
23732374
Parameters
23742375
----------
23752376
time : datetime.time or string
2377+
datetime.time or string in appropriate format ("%H:%M", "%H%M",
2378+
"%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p",
2379+
"%I%M%S%p").
23762380
23772381
Returns
23782382
-------
2379-
values_at_time : TimeSeries
2383+
values_at_time : array of integers
2384+
2385+
See Also
2386+
--------
2387+
indexer_between_time, DataFrame.at_time
23802388
"""
23812389
from dateutil.parser import parse
23822390

@@ -2398,24 +2406,25 @@ def indexer_at_time(self, time, asof=False):
23982406
def indexer_between_time(self, start_time, end_time, include_start=True,
23992407
include_end=True):
24002408
"""
2401-
Select values between particular times of day (e.g., 9:00-9:30AM).
2402-
2403-
Return values of the index between two times. If start_time or
2404-
end_time are strings then tseries.tools.to_time is used to convert to
2405-
a time object.
2409+
Return index locations of values between particular times of day
2410+
(e.g., 9:00-9:30AM).
24062411
24072412
Parameters
24082413
----------
24092414
start_time, end_time : datetime.time, str
24102415
datetime.time or string in appropriate format ("%H:%M", "%H%M",
24112416
"%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p",
2412-
"%I%M%S%p")
2417+
"%I%M%S%p").
24132418
include_start : boolean, default True
24142419
include_end : boolean, default True
24152420
24162421
Returns
24172422
-------
2418-
values_between_time : TimeSeries
2423+
values_between_time : array of integers
2424+
2425+
See Also
2426+
--------
2427+
indexer_at_time, DataFrame.between_time
24192428
"""
24202429
start_time = tools.to_time(start_time)
24212430
end_time = tools.to_time(end_time)

0 commit comments

Comments
 (0)