Skip to content

Commit 3099773

Browse files
danielplawrenceTomAugspurger
danielplawrence
authored and
TomAugspurger
committed
DOC:Remove hard-coded examples from _flex_doc_SERIES (#24589) (#25524)
* DOC:Remove hard-coded examples from _flex_doc_SERIES (#24589)
1 parent f886139 commit 3099773

File tree

1 file changed

+226
-60
lines changed

1 file changed

+226
-60
lines changed

‎pandas/core/ops.py

+226-60
Original file line numberDiff line numberDiff line change
@@ -384,57 +384,252 @@ def _get_op_name(op, special):
384384
# -----------------------------------------------------------------------------
385385
# Docstring Generation and Templates
386386

387+
_add_example_SERIES = """
388+
Examples
389+
--------
390+
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
391+
>>> a
392+
a 1.0
393+
b 1.0
394+
c 1.0
395+
d NaN
396+
dtype: float64
397+
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
398+
>>> b
399+
a 1.0
400+
b NaN
401+
d 1.0
402+
e NaN
403+
dtype: float64
404+
>>> a.add(b, fill_value=0)
405+
a 2.0
406+
b 1.0
407+
c 1.0
408+
d 1.0
409+
e NaN
410+
dtype: float64
411+
"""
412+
413+
_sub_example_SERIES = """
414+
Examples
415+
--------
416+
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
417+
>>> a
418+
a 1.0
419+
b 1.0
420+
c 1.0
421+
d NaN
422+
dtype: float64
423+
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
424+
>>> b
425+
a 1.0
426+
b NaN
427+
d 1.0
428+
e NaN
429+
dtype: float64
430+
>>> a.subtract(b, fill_value=0)
431+
a 0.0
432+
b 1.0
433+
c 1.0
434+
d -1.0
435+
e NaN
436+
dtype: float64
437+
"""
438+
439+
_mul_example_SERIES = """
440+
Examples
441+
--------
442+
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
443+
>>> a
444+
a 1.0
445+
b 1.0
446+
c 1.0
447+
d NaN
448+
dtype: float64
449+
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
450+
>>> b
451+
a 1.0
452+
b NaN
453+
d 1.0
454+
e NaN
455+
dtype: float64
456+
>>> a.multiply(b, fill_value=0)
457+
a 1.0
458+
b 0.0
459+
c 0.0
460+
d 0.0
461+
e NaN
462+
dtype: float64
463+
"""
464+
465+
_div_example_SERIES = """
466+
Examples
467+
--------
468+
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
469+
>>> a
470+
a 1.0
471+
b 1.0
472+
c 1.0
473+
d NaN
474+
dtype: float64
475+
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
476+
>>> b
477+
a 1.0
478+
b NaN
479+
d 1.0
480+
e NaN
481+
dtype: float64
482+
>>> a.divide(b, fill_value=0)
483+
a 1.0
484+
b inf
485+
c inf
486+
d 0.0
487+
e NaN
488+
dtype: float64
489+
"""
490+
491+
_floordiv_example_SERIES = """
492+
Examples
493+
--------
494+
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
495+
>>> a
496+
a 1.0
497+
b 1.0
498+
c 1.0
499+
d NaN
500+
dtype: float64
501+
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
502+
>>> b
503+
a 1.0
504+
b NaN
505+
d 1.0
506+
e NaN
507+
dtype: float64
508+
>>> a.floordiv(b, fill_value=0)
509+
a 1.0
510+
b NaN
511+
c NaN
512+
d 0.0
513+
e NaN
514+
dtype: float64
515+
"""
516+
517+
_mod_example_SERIES = """
518+
Examples
519+
--------
520+
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
521+
>>> a
522+
a 1.0
523+
b 1.0
524+
c 1.0
525+
d NaN
526+
dtype: float64
527+
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
528+
>>> b
529+
a 1.0
530+
b NaN
531+
d 1.0
532+
e NaN
533+
dtype: float64
534+
>>> a.mod(b, fill_value=0)
535+
a 0.0
536+
b NaN
537+
c NaN
538+
d 0.0
539+
e NaN
540+
dtype: float64
541+
"""
542+
_pow_example_SERIES = """
543+
Examples
544+
--------
545+
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
546+
>>> a
547+
a 1.0
548+
b 1.0
549+
c 1.0
550+
d NaN
551+
dtype: float64
552+
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
553+
>>> b
554+
a 1.0
555+
b NaN
556+
d 1.0
557+
e NaN
558+
dtype: float64
559+
>>> a.pow(b, fill_value=0)
560+
a 1.0
561+
b 1.0
562+
c 1.0
563+
d 0.0
564+
e NaN
565+
dtype: float64
566+
"""
567+
387568
_op_descriptions = {
388569
# Arithmetic Operators
389570
'add': {'op': '+',
390571
'desc': 'Addition',
391-
'reverse': 'radd'},
572+
'reverse': 'radd',
573+
'series_examples': _add_example_SERIES},
392574
'sub': {'op': '-',
393575
'desc': 'Subtraction',
394-
'reverse': 'rsub'},
576+
'reverse': 'rsub',
577+
'series_examples': _sub_example_SERIES},
395578
'mul': {'op': '*',
396579
'desc': 'Multiplication',
397580
'reverse': 'rmul',
581+
'series_examples': _mul_example_SERIES,
398582
'df_examples': None},
399583
'mod': {'op': '%',
400584
'desc': 'Modulo',
401-
'reverse': 'rmod'},
585+
'reverse': 'rmod',
586+
'series_examples': _mod_example_SERIES},
402587
'pow': {'op': '**',
403588
'desc': 'Exponential power',
404589
'reverse': 'rpow',
590+
'series_examples': _pow_example_SERIES,
405591
'df_examples': None},
406592
'truediv': {'op': '/',
407593
'desc': 'Floating division',
408594
'reverse': 'rtruediv',
595+
'series_examples': _div_example_SERIES,
409596
'df_examples': None},
410597
'floordiv': {'op': '//',
411598
'desc': 'Integer division',
412599
'reverse': 'rfloordiv',
600+
'series_examples': _floordiv_example_SERIES,
413601
'df_examples': None},
414602
'divmod': {'op': 'divmod',
415603
'desc': 'Integer division and modulo',
416604
'reverse': 'rdivmod',
605+
'series_examples': None,
417606
'df_examples': None},
418607

419608
# Comparison Operators
420609
'eq': {'op': '==',
421610
'desc': 'Equal to',
422-
'reverse': None},
611+
'reverse': None,
612+
'series_examples': None},
423613
'ne': {'op': '!=',
424614
'desc': 'Not equal to',
425-
'reverse': None},
615+
'reverse': None,
616+
'series_examples': None},
426617
'lt': {'op': '<',
427618
'desc': 'Less than',
428-
'reverse': None},
619+
'reverse': None,
620+
'series_examples': None},
429621
'le': {'op': '<=',
430622
'desc': 'Less than or equal to',
431-
'reverse': None},
623+
'reverse': None,
624+
'series_examples': None},
432625
'gt': {'op': '>',
433626
'desc': 'Greater than',
434-
'reverse': None},
627+
'reverse': None,
628+
'series_examples': None},
435629
'ge': {'op': '>=',
436630
'desc': 'Greater than or equal to',
437-
'reverse': None}
631+
'reverse': None,
632+
'series_examples': None}
438633
}
439634

440635
_op_names = list(_op_descriptions.keys())
@@ -472,51 +667,6 @@ def _get_op_name(op, special):
472667
See Also
473668
--------
474669
Series.{reverse}
475-
476-
Examples
477-
--------
478-
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
479-
>>> a
480-
a 1.0
481-
b 1.0
482-
c 1.0
483-
d NaN
484-
dtype: float64
485-
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
486-
>>> b
487-
a 1.0
488-
b NaN
489-
d 1.0
490-
e NaN
491-
dtype: float64
492-
>>> a.add(b, fill_value=0)
493-
a 2.0
494-
b 1.0
495-
c 1.0
496-
d 1.0
497-
e NaN
498-
dtype: float64
499-
>>> a.subtract(b, fill_value=0)
500-
a 0.0
501-
b 1.0
502-
c 1.0
503-
d -1.0
504-
e NaN
505-
dtype: float64
506-
>>> a.multiply(b)
507-
a 1.0
508-
b NaN
509-
c NaN
510-
d NaN
511-
e NaN
512-
dtype: float64
513-
>>> a.divide(b, fill_value=0)
514-
a 1.0
515-
b inf
516-
c inf
517-
d 0.0
518-
e NaN
519-
dtype: float64
520670
"""
521671

522672
_arith_doc_FRAME = """
@@ -906,16 +1056,32 @@ def _make_flex_doc(op_name, typ):
9061056

9071057
if typ == 'series':
9081058
base_doc = _flex_doc_SERIES
909-
doc = base_doc.format(desc=op_desc['desc'], op_name=op_name,
910-
equiv=equiv, reverse=op_desc['reverse'])
1059+
doc_no_examples = base_doc.format(
1060+
desc=op_desc['desc'],
1061+
op_name=op_name,
1062+
equiv=equiv,
1063+
reverse=op_desc['reverse']
1064+
)
1065+
if op_desc['series_examples']:
1066+
doc = doc_no_examples + op_desc['series_examples']
1067+
else:
1068+
doc = doc_no_examples
9111069
elif typ == 'dataframe':
9121070
base_doc = _flex_doc_FRAME
913-
doc = base_doc.format(desc=op_desc['desc'], op_name=op_name,
914-
equiv=equiv, reverse=op_desc['reverse'])
1071+
doc = base_doc.format(
1072+
desc=op_desc['desc'],
1073+
op_name=op_name,
1074+
equiv=equiv,
1075+
reverse=op_desc['reverse']
1076+
)
9151077
elif typ == 'panel':
9161078
base_doc = _flex_doc_PANEL
917-
doc = base_doc.format(desc=op_desc['desc'], op_name=op_name,
918-
equiv=equiv, reverse=op_desc['reverse'])
1079+
doc = base_doc.format(
1080+
desc=op_desc['desc'],
1081+
op_name=op_name,
1082+
equiv=equiv,
1083+
reverse=op_desc['reverse']
1084+
)
9191085
else:
9201086
raise AssertionError('Invalid typ argument.')
9211087
return doc

0 commit comments

Comments
 (0)