Skip to content

Commit 513d3e2

Browse files
ShaharNavehShaharNaveh
authored
DOC: Fixed examples in pandas/core/indexes/ (#33208)
1 parent 37dc5dc commit 513d3e2

File tree

7 files changed

+225
-70
lines changed

7 files changed

+225
-70
lines changed

‎ci/code_checks.sh

+4-4
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,10 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
278278
pytest -q --doctest-modules pandas/core/groupby/groupby.py -k"-cumcount -describe -pipe"
279279
RET=$(($RET + $?)) ; echo $MSG "DONE"
280280

281+
MSG='Doctests indexes' ; echo $MSG
282+
pytest -q --doctest-modules pandas/core/indexes/
283+
RET=$(($RET + $?)) ; echo $MSG "DONE"
284+
281285
MSG='Doctests tools' ; echo $MSG
282286
pytest -q --doctest-modules pandas/core/tools/
283287
RET=$(($RET + $?)) ; echo $MSG "DONE"
@@ -286,10 +290,6 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
286290
pytest -q --doctest-modules pandas/core/reshape/
287291
RET=$(($RET + $?)) ; echo $MSG "DONE"
288292

289-
MSG='Doctests interval classes' ; echo $MSG
290-
pytest -q --doctest-modules pandas/core/indexes/interval.py
291-
RET=$(($RET + $?)) ; echo $MSG "DONE"
292-
293293
MSG='Doctests arrays'; echo $MSG
294294
pytest -q --doctest-modules pandas/core/arrays/
295295
RET=$(($RET + $?)) ; echo $MSG "DONE"

‎pandas/core/indexes/accessors.py

+107-18
Original file line numberDiff line numberDiff line change
@@ -129,9 +129,41 @@ class DatetimeProperties(Properties):
129129
130130
Examples
131131
--------
132-
>>> s.dt.hour
133-
>>> s.dt.second
134-
>>> s.dt.quarter
132+
>>> seconds_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="s"))
133+
>>> seconds_series
134+
0 2000-01-01 00:00:00
135+
1 2000-01-01 00:00:01
136+
2 2000-01-01 00:00:02
137+
dtype: datetime64[ns]
138+
>>> seconds_series.dt.second
139+
0 0
140+
1 1
141+
2 2
142+
dtype: int64
143+
144+
>>> hours_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="h"))
145+
>>> hours_series
146+
0 2000-01-01 00:00:00
147+
1 2000-01-01 01:00:00
148+
2 2000-01-01 02:00:00
149+
dtype: datetime64[ns]
150+
>>> hours_series.dt.hour
151+
0 0
152+
1 1
153+
2 2
154+
dtype: int64
155+
156+
>>> quarters_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="q"))
157+
>>> quarters_series
158+
0 2000-03-31
159+
1 2000-06-30
160+
2 2000-09-30
161+
dtype: datetime64[ns]
162+
>>> quarters_series.dt.quarter
163+
0 1
164+
1 2
165+
2 3
166+
dtype: int64
135167
136168
Returns a Series indexed like the original Series.
137169
Raises TypeError if the Series does not contain datetimelike values.
@@ -200,13 +232,24 @@ class TimedeltaProperties(Properties):
200232
"""
201233
Accessor object for datetimelike properties of the Series values.
202234
203-
Examples
204-
--------
205-
>>> s.dt.hours
206-
>>> s.dt.seconds
207-
208235
Returns a Series indexed like the original Series.
209236
Raises TypeError if the Series does not contain datetimelike values.
237+
238+
Examples
239+
--------
240+
>>> seconds_series = pd.Series(
241+
... pd.timedelta_range(start="1 second", periods=3, freq="S")
242+
... )
243+
>>> seconds_series
244+
0 00:00:01
245+
1 00:00:02
246+
2 00:00:03
247+
dtype: timedelta64[ns]
248+
>>> seconds_series.dt.seconds
249+
0 1
250+
1 2
251+
2 3
252+
dtype: int64
210253
"""
211254

212255
def to_pytimedelta(self) -> np.ndarray:
@@ -229,7 +272,7 @@ def to_pytimedelta(self) -> np.ndarray:
229272
230273
Examples
231274
--------
232-
>>> s = pd.Series(pd.to_timedelta(np.arange(5), unit='d'))
275+
>>> s = pd.Series(pd.to_timedelta(np.arange(5), unit="d"))
233276
>>> s
234277
0 0 days
235278
1 1 days
@@ -239,9 +282,9 @@ def to_pytimedelta(self) -> np.ndarray:
239282
dtype: timedelta64[ns]
240283
241284
>>> s.dt.to_pytimedelta()
242-
array([datetime.timedelta(0), datetime.timedelta(1),
243-
datetime.timedelta(2), datetime.timedelta(3),
244-
datetime.timedelta(4)], dtype=object)
285+
array([datetime.timedelta(0), datetime.timedelta(days=1),
286+
datetime.timedelta(days=2), datetime.timedelta(days=3),
287+
datetime.timedelta(days=4)], dtype=object)
245288
"""
246289
return self._get_values().to_pytimedelta()
247290

@@ -289,14 +332,60 @@ class PeriodProperties(Properties):
289332
"""
290333
Accessor object for datetimelike properties of the Series values.
291334
292-
Examples
293-
--------
294-
>>> s.dt.hour
295-
>>> s.dt.second
296-
>>> s.dt.quarter
297-
298335
Returns a Series indexed like the original Series.
299336
Raises TypeError if the Series does not contain datetimelike values.
337+
338+
Examples
339+
--------
340+
>>> seconds_series = pd.Series(
341+
... pd.period_range(
342+
... start="2000-01-01 00:00:00", end="2000-01-01 00:00:03", freq="s"
343+
... )
344+
... )
345+
>>> seconds_series
346+
0 2000-01-01 00:00:00
347+
1 2000-01-01 00:00:01
348+
2 2000-01-01 00:00:02
349+
3 2000-01-01 00:00:03
350+
dtype: period[S]
351+
>>> seconds_series.dt.second
352+
0 0
353+
1 1
354+
2 2
355+
3 3
356+
dtype: int64
357+
358+
>>> hours_series = pd.Series(
359+
... pd.period_range(start="2000-01-01 00:00", end="2000-01-01 03:00", freq="h")
360+
... )
361+
>>> hours_series
362+
0 2000-01-01 00:00
363+
1 2000-01-01 01:00
364+
2 2000-01-01 02:00
365+
3 2000-01-01 03:00
366+
dtype: period[H]
367+
>>> hours_series.dt.hour
368+
0 0
369+
1 1
370+
2 2
371+
3 3
372+
dtype: int64
373+
374+
>>> quarters_series = pd.Series(
375+
... pd.period_range(start="2000-01-01", end="2000-12-31", freq="Q-DEC")
376+
... )
377+
>>> quarters_series
378+
0 2000Q1
379+
1 2000Q2
380+
2 2000Q3
381+
3 2000Q4
382+
dtype: period[Q-DEC]
383+
>>> quarters_series.dt.quarter
384+
0 1
385+
1 2
386+
2 3
387+
3 4
388+
dtype: int64
300389
"""
301390

302391

‎pandas/core/indexes/base.py

+17-18
Original file line numberDiff line numberDiff line change
@@ -1841,7 +1841,7 @@ def is_object(self) -> bool:
18411841
18421842
>>> idx = pd.Index(["Watermelon", "Orange", "Apple",
18431843
... "Watermelon"]).astype("category")
1844-
>>> idx.object()
1844+
>>> idx.is_object()
18451845
False
18461846
18471847
>>> idx = pd.Index([1.0, 2.0, 3.0, 4.0])
@@ -2053,7 +2053,7 @@ def isna(self):
20532053
>>> idx
20542054
Float64Index([5.2, 6.0, nan], dtype='float64')
20552055
>>> idx.isna()
2056-
array([False, False, True], dtype=bool)
2056+
array([False, False, True])
20572057
20582058
Empty strings are not considered NA values. None is considered an NA
20592059
value.
@@ -2062,7 +2062,7 @@ def isna(self):
20622062
>>> idx
20632063
Index(['black', '', 'red', None], dtype='object')
20642064
>>> idx.isna()
2065-
array([False, False, False, True], dtype=bool)
2065+
array([False, False, False, True])
20662066
20672067
For datetimes, `NaT` (Not a Time) is considered as an NA value.
20682068
@@ -2072,7 +2072,7 @@ def isna(self):
20722072
DatetimeIndex(['1940-04-25', 'NaT', 'NaT', 'NaT'],
20732073
dtype='datetime64[ns]', freq=None)
20742074
>>> idx.isna()
2075-
array([False, True, True, True], dtype=bool)
2075+
array([False, True, True, True])
20762076
"""
20772077
return self._isnan
20782078

@@ -4790,8 +4790,9 @@ def isin(self, values, level=None):
47904790
... ['red', 'blue', 'green']],
47914791
... names=('number', 'color'))
47924792
>>> midx
4793-
MultiIndex(levels=[[1, 2, 3], ['blue', 'green', 'red']],
4794-
codes=[[0, 1, 2], [2, 0, 1]],
4793+
MultiIndex([(1, 'red'),
4794+
(2, 'blue'),
4795+
(3, 'green')],
47954796
names=['number', 'color'])
47964797
47974798
Check whether the strings in the 'color' level of the MultiIndex
@@ -4859,11 +4860,11 @@ def slice_indexer(self, start=None, end=None, step=None, kind=None):
48594860
48604861
>>> idx = pd.Index(list('abcd'))
48614862
>>> idx.slice_indexer(start='b', end='c')
4862-
slice(1, 3)
4863+
slice(1, 3, None)
48634864
48644865
>>> idx = pd.MultiIndex.from_arrays([list('abcd'), list('efgh')])
48654866
>>> idx.slice_indexer(start='b', end=('c', 'g'))
4866-
slice(1, 3)
4867+
slice(1, 3, None)
48674868
"""
48684869
start_slice, end_slice = self.slice_locs(start, end, step=step, kind=kind)
48694870

@@ -5434,11 +5435,10 @@ def ensure_index_from_sequences(sequences, names=None):
54345435
54355436
Examples
54365437
--------
5437-
>>> ensure_index_from_sequences([[1, 2, 3]], names=['name'])
5438+
>>> ensure_index_from_sequences([[1, 2, 3]], names=["name"])
54385439
Int64Index([1, 2, 3], dtype='int64', name='name')
54395440
5440-
>>> ensure_index_from_sequences([['a', 'a'], ['a', 'b']],
5441-
names=['L1', 'L2'])
5441+
>>> ensure_index_from_sequences([["a", "a"], ["a", "b"]], names=["L1", "L2"])
54425442
MultiIndex([('a', 'a'),
54435443
('a', 'b')],
54445444
names=['L1', 'L2'])
@@ -5471,6 +5471,10 @@ def ensure_index(index_like, copy=False):
54715471
-------
54725472
index : Index or MultiIndex
54735473
5474+
See Also
5475+
--------
5476+
ensure_index_from_sequences
5477+
54745478
Examples
54755479
--------
54765480
>>> ensure_index(['a', 'b'])
@@ -5481,13 +5485,8 @@ def ensure_index(index_like, copy=False):
54815485
54825486
>>> ensure_index([['a', 'a'], ['b', 'c']])
54835487
MultiIndex([('a', 'b'),
5484-
('a', 'c')],
5485-
dtype='object')
5486-
)
5487-
5488-
See Also
5489-
--------
5490-
ensure_index_from_sequences
5488+
('a', 'c')],
5489+
)
54915490
"""
54925491
if isinstance(index_like, Index):
54935492
if copy:

‎pandas/core/indexes/category.py

+12-8
Original file line numberDiff line numberDiff line change
@@ -138,21 +138,25 @@ class CategoricalIndex(ExtensionIndex, accessor.PandasDelegate):
138138
139139
Examples
140140
--------
141-
>>> pd.CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'])
142-
CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category') # noqa
141+
>>> pd.CategoricalIndex(["a", "b", "c", "a", "b", "c"])
142+
CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
143+
categories=['a', 'b', 'c'], ordered=False, dtype='category')
143144
144145
``CategoricalIndex`` can also be instantiated from a ``Categorical``:
145146
146-
>>> c = pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'])
147+
>>> c = pd.Categorical(["a", "b", "c", "a", "b", "c"])
147148
>>> pd.CategoricalIndex(c)
148-
CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category') # noqa
149+
CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
150+
categories=['a', 'b', 'c'], ordered=False, dtype='category')
149151
150152
Ordered ``CategoricalIndex`` can have a min and max value.
151153
152-
>>> ci = pd.CategoricalIndex(['a','b','c','a','b','c'], ordered=True,
153-
... categories=['c', 'b', 'a'])
154+
>>> ci = pd.CategoricalIndex(
155+
... ["a", "b", "c", "a", "b", "c"], ordered=True, categories=["c", "b", "a"]
156+
... )
154157
>>> ci
155-
CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['c', 'b', 'a'], ordered=True, dtype='category') # noqa
158+
CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
159+
categories=['c', 'b', 'a'], ordered=True, dtype='category')
156160
>>> ci.min()
157161
'c'
158162
"""
@@ -652,7 +656,7 @@ def map(self, mapper):
652656
>>> idx = pd.CategoricalIndex(['a', 'b', 'c'])
653657
>>> idx
654658
CategoricalIndex(['a', 'b', 'c'], categories=['a', 'b', 'c'],
655-
ordered=False, dtype='category')
659+
ordered=False, dtype='category')
656660
>>> idx.map(lambda x: x.upper())
657661
CategoricalIndex(['A', 'B', 'C'], categories=['A', 'B', 'C'],
658662
ordered=False, dtype='category')

0 commit comments

Comments
 (0)