Skip to content

Commit 409b415

Browse files
simonjayhawkinsjreback
authored andcommitted
DOC update docstrings following refactor of buffer handling (#27738)
1 parent 1944ab8 commit 409b415

File tree

2 files changed

+19
-12
lines changed

2 files changed

+19
-12
lines changed

pandas/core/generic.py

+4-8
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@
6868
from pandas.core.internals import BlockManager
6969
from pandas.core.ops import _align_method_FRAME
7070

71+
from pandas.io.formats import format as fmt
7172
from pandas.io.formats.format import DataFrameFormatter, format_percentiles
7273
from pandas.io.formats.printing import pprint_thing
7374
from pandas.tseries.frequencies import to_offset
@@ -2881,6 +2882,7 @@ class (index) object 'bird' 'bird' 'mammal' 'mammal'
28812882
else:
28822883
return xarray.Dataset.from_dataframe(self)
28832884

2885+
@Substitution(returns=fmt.return_docstring)
28842886
def to_latex(
28852887
self,
28862888
buf=None,
@@ -2914,7 +2916,7 @@ def to_latex(
29142916
29152917
Parameters
29162918
----------
2917-
buf : file descriptor or None
2919+
buf : str, Path or StringIO-like, optional, default None
29182920
Buffer to write to. If None, the output is returned as a string.
29192921
columns : list of label, optional
29202922
The subset of columns to write. Writes all columns by default.
@@ -2979,13 +2981,7 @@ def to_latex(
29792981
from the pandas config module.
29802982
29812983
.. versionadded:: 0.20.0
2982-
2983-
Returns
2984-
-------
2985-
str or None
2986-
If buf is None, returns the resulting LateX format as a
2987-
string. Otherwise returns None.
2988-
2984+
%(returns)s
29892985
See Also
29902986
--------
29912987
DataFrame.to_string : Render a DataFrame to a console-friendly

pandas/io/formats/format.py

+15-4
Original file line numberDiff line numberDiff line change
@@ -85,8 +85,8 @@
8585
common_docstring = """
8686
Parameters
8787
----------
88-
buf : StringIO-like, optional
89-
Buffer to write to.
88+
buf : str, Path or StringIO-like, optional, default None
89+
Buffer to write to. If None, the output is returned as a string.
9090
columns : sequence, optional, default None
9191
The subset of columns to write. Writes all columns by default.
9292
col_space : %(col_space_type)s, optional
@@ -156,8 +156,9 @@
156156
return_docstring = """
157157
Returns
158158
-------
159-
str (or unicode, depending on data and options)
160-
String representation of the dataframe.
159+
str or None
160+
If buf is None, returns the result as a string. Otherwise returns
161+
None.
161162
"""
162163

163164

@@ -471,6 +472,10 @@ def _get_formatter(self, i: Union[str, int]) -> Optional[Callable]:
471472
def get_buffer(
472473
self, buf: Optional[FilePathOrBuffer[str]], encoding: Optional[str] = None
473474
):
475+
"""
476+
Context manager to open, yield and close buffer for filenames or Path-like
477+
objects, otherwise yield buf unchanged.
478+
"""
474479
if buf is not None:
475480
buf = _stringify_path(buf)
476481
else:
@@ -488,13 +493,19 @@ def get_buffer(
488493
raise TypeError("buf is not a file name and it has no write method")
489494

490495
def write_result(self, buf: IO[str]) -> None:
496+
"""
497+
Write the result of serialization to buf.
498+
"""
491499
raise AbstractMethodError(self)
492500

493501
def get_result(
494502
self,
495503
buf: Optional[FilePathOrBuffer[str]] = None,
496504
encoding: Optional[str] = None,
497505
) -> Optional[str]:
506+
"""
507+
Perform serialization. Write to buf or return as string if buf is None.
508+
"""
498509
with self.get_buffer(buf, encoding=encoding) as f:
499510
self.write_result(buf=f)
500511
if buf is None:

0 commit comments

Comments
 (0)