Skip to content

Commit 40b71f8

Browse files
committed
DOC: unify series/frame docstrings, fix indent
1 parent f41596d commit 40b71f8

File tree

3 files changed

+82
-68
lines changed

3 files changed

+82
-68
lines changed

pandas/core/frame.py

+19-10
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@
151151

152152
from pandas.io.common import get_filepath_or_buffer
153153
from pandas.io.formats import console, format as fmt
154-
from pandas.io.formats.info import DataFrameInfo
154+
from pandas.io.formats.info import BaseInfo, DataFrameInfo
155155
import pandas.plotting
156156

157157
if TYPE_CHECKING:
@@ -2506,16 +2506,25 @@ def to_html(
25062506
@Substitution(
25072507
klass="DataFrame",
25082508
type_sub=" and columns",
2509-
max_cols_sub=(
2510-
"""max_cols : int, optional
2509+
max_cols_sub=dedent(
2510+
"""\
2511+
max_cols : int, optional
25112512
When to switch from the verbose to the truncated output. If the
25122513
DataFrame has more than `max_cols` columns, the truncated output
25132514
is used. By default, the setting in
2514-
``pandas.options.display.max_info_columns`` is used.
2515-
"""
2515+
``pandas.options.display.max_info_columns`` is used."""
25162516
),
2517-
examples_sub=(
2518-
"""
2517+
null_counts_sub=dedent(
2518+
"""\
2519+
null_counts : bool, optional
2520+
Whether to show the non-null counts. By default, this is shown
2521+
only if the DataFrame is smaller than
2522+
``pandas.options.display.max_info_rows`` and
2523+
``pandas.options.display.max_info_columns``. A value of True always
2524+
shows the counts, and False never shows the counts."""
2525+
),
2526+
examples_sub=dedent(
2527+
"""\
25192528
>>> int_values = [1, 2, 3, 4, 5]
25202529
>>> text_values = ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
25212530
>>> float_values = [0.0, 0.25, 0.5, 0.75, 1.0]
@@ -2598,14 +2607,14 @@ def to_html(
25982607
dtypes: object(3)
25992608
memory usage: 165.9 MB"""
26002609
),
2601-
see_also_sub=(
2602-
"""
2610+
see_also_sub=dedent(
2611+
"""\
26032612
DataFrame.describe: Generate descriptive statistics of DataFrame
26042613
columns.
26052614
DataFrame.memory_usage: Memory usage of DataFrame columns."""
26062615
),
26072616
)
2608-
@doc(DataFrameInfo.to_buffer)
2617+
@doc(BaseInfo.to_buffer)
26092618
def info(
26102619
self,
26112620
verbose: Optional[bool] = None,

pandas/core/series.py

+12-7
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@
9797
from pandas.core.tools.datetimes import to_datetime
9898

9999
import pandas.io.formats.format as fmt
100-
from pandas.io.formats.info import SeriesInfo
100+
from pandas.io.formats.info import BaseInfo, SeriesInfo
101101
import pandas.plotting
102102

103103
if TYPE_CHECKING:
@@ -4569,8 +4569,13 @@ def replace(
45694569
klass="Series",
45704570
type_sub="",
45714571
max_cols_sub="",
4572-
examples_sub=(
4573-
"""
4572+
null_counts_sub=dedent(
4573+
"""\
4574+
null_counts : bool, default True.
4575+
Whether to show the non-null counts."""
4576+
),
4577+
examples_sub=dedent(
4578+
"""\
45744579
>>> int_values = [1, 2, 3, 4, 5]
45754580
>>> text_values = ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
45764581
>>> s = pd.Series(text_values, index=int_values)
@@ -4629,20 +4634,20 @@ def replace(
46294634
dtypes: object(1)
46304635
memory usage: 55.3 MB"""
46314636
),
4632-
see_also_sub=(
4633-
"""
4637+
see_also_sub=dedent(
4638+
"""\
46344639
Series.describe: Generate descriptive statistics of Series.
46354640
Series.memory_usage: Memory usage of Series."""
46364641
),
46374642
)
4638-
@doc(SeriesInfo.to_buffer)
4643+
@doc(BaseInfo.to_buffer)
46394644
def info(
46404645
self,
46414646
verbose: Optional[bool] = None,
46424647
buf: Optional[IO[str]] = None,
46434648
max_cols: Optional[int] = None,
46444649
memory_usage: Optional[Union[bool, str]] = None,
4645-
null_counts: Optional[bool] = None,
4650+
null_counts: bool = True,
46464651
) -> None:
46474652
if max_cols is not None:
46484653
raise ValueError(

pandas/io/formats/info.py

+51-51
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,55 @@ def size_qualifier(self) -> str:
159159
size_qualifier = "+"
160160
return size_qualifier
161161

162+
@abstractmethod
163+
def to_buffer():
164+
"""
165+
Print a concise summary of a %(klass)s.
166+
167+
This method prints information about a %(klass)s including
168+
the index dtype%(type_sub)s, non-null values and memory usage.
169+
170+
Parameters
171+
----------
172+
data : %(klass)s
173+
%(klass)s to print information about.
174+
verbose : bool, optional
175+
Whether to print the full summary. By default, the setting in
176+
``pandas.options.display.max_info_columns`` is followed.
177+
buf : writable buffer, defaults to sys.stdout
178+
Where to send the output. By default, the output is printed to
179+
sys.stdout. Pass a writable buffer if you need to further process
180+
the output.
181+
%(max_cols_sub)s
182+
memory_usage : bool, str, optional
183+
Specifies whether total memory usage of the %(klass)s
184+
elements (including the index) should be displayed. By default,
185+
this follows the ``pandas.options.display.memory_usage`` setting.
186+
187+
True always show memory usage. False never shows memory usage.
188+
A value of 'deep' is equivalent to "True with deep introspection".
189+
Memory usage is shown in human-readable units (base-2
190+
representation). Without deep introspection a memory estimation is
191+
made based in column dtype and number of rows assuming values
192+
consume the same memory amount for corresponding dtypes. With deep
193+
memory introspection, a real memory usage calculation is performed
194+
at the cost of computational resources.
195+
%(null_counts_sub)s
196+
197+
Returns
198+
-------
199+
None
200+
This method prints a summary of a %(klass)s and returns None.
201+
202+
See Also
203+
--------
204+
%(see_also_sub)s
205+
206+
Examples
207+
--------
208+
%(examples_sub)s
209+
"""
210+
162211

163212
class DataFrameInfo(BaseInfo):
164213
"""
@@ -225,57 +274,6 @@ def to_buffer(
225274
verbose: Optional[bool],
226275
show_counts: Optional[bool],
227276
) -> None:
228-
"""
229-
Print a concise summary of a %(klass)s.
230-
231-
This method prints information about a %(klass)s including
232-
the index dtype%(type_sub)s, non-null values and memory usage.
233-
234-
Parameters
235-
----------
236-
data : %(klass)s
237-
%(klass)s to print information about.
238-
verbose : bool, optional
239-
Whether to print the full summary. By default, the setting in
240-
``pandas.options.display.max_info_columns`` is followed.
241-
buf : writable buffer, defaults to sys.stdout
242-
Where to send the output. By default, the output is printed to
243-
sys.stdout. Pass a writable buffer if you need to further process
244-
the output.
245-
%(max_cols_sub)s
246-
memory_usage : bool, str, optional
247-
Specifies whether total memory usage of the %(klass)s
248-
elements (including the index) should be displayed. By default,
249-
this follows the ``pandas.options.display.memory_usage`` setting.
250-
251-
True always show memory usage. False never shows memory usage.
252-
A value of 'deep' is equivalent to "True with deep introspection".
253-
Memory usage is shown in human-readable units (base-2
254-
representation). Without deep introspection a memory estimation is
255-
made based in column dtype and number of rows assuming values
256-
consume the same memory amount for corresponding dtypes. With deep
257-
memory introspection, a real memory usage calculation is performed
258-
at the cost of computational resources.
259-
null_counts : bool, optional
260-
Whether to show the non-null counts. By default, this is shown
261-
only if the %(klass)s is smaller than
262-
``pandas.options.display.max_info_rows`` and
263-
``pandas.options.display.max_info_columns``. A value of True always
264-
shows the counts, and False never shows the counts.
265-
266-
Returns
267-
-------
268-
None
269-
This method prints a summary of a %(klass)s and returns None.
270-
271-
See Also
272-
--------
273-
%(see_also_sub)s
274-
275-
Examples
276-
--------
277-
%(examples_sub)s
278-
"""
279277
printer = DataFrameInfoPrinter(
280278
info=self,
281279
max_cols=max_cols,
@@ -305,6 +303,8 @@ def to_buffer(
305303
verbose: Optional[bool],
306304
show_counts: Optional[bool],
307305
) -> None:
306+
"""
307+
"""
308308
printer = SeriesInfoPrinter(
309309
info=self,
310310
verbose=verbose,

0 commit comments

Comments
 (0)