From 7fd8464c04cc71efc22bb91744790bc0c272e839 Mon Sep 17 00:00:00 2001 From: Tomasz-Kluczkowski Date: Sat, 10 Mar 2018 14:55:32 +0000 Subject: [PATCH 1/6] Fixed docstring for the DataFrame.to_string method. Had to correct parameters descriptions in common docstrings (format.py) as well as in frame.py. --- pandas/core/frame.py | 22 ++++++++++++-- pandas/io/formats/format.py | 59 +++++++++++++++++++------------------ 2 files changed, 51 insertions(+), 30 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index a66d00fff9714..dc1fc29b299f5 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -1721,11 +1721,29 @@ def to_parquet(self, fname, engine='auto', compression='snappy', @Appender(fmt.docstring_to_string, indents=1) def to_string(self, buf=None, columns=None, col_space=None, header=True, index=True, na_rep='NaN', formatters=None, float_format=None, - sparsify=None, index_names=True, justify=None, + sparsify=None, index_names=True, line_width=None, max_rows=None, max_cols=None, - show_dimensions=False): + show_dimensions=False, justify=None): """ Render a DataFrame to a console-friendly tabular output. + + Convert DataFrame object into a string (or unicode) representation + which can be shown in command line interface. + + See Also + -------- + pandas.DataFrame.to_html + Convert dataframe to a html file. + + Examples + -------- + >>> d = {'col1' : [1, 2, 3], 'col2' : [4, 5, 6]} + >>> df = pd.DataFrame(d) + >>> print(df.to_string()) + col1 col2 + 0 1 4 + 1 2 5 + 2 3 6 """ formatter = fmt.DataFrameFormatter(self, buf=buf, columns=columns, diff --git a/pandas/io/formats/format.py b/pandas/io/formats/format.py index 50b4f11634b78..13d3264469537 100644 --- a/pandas/io/formats/format.py +++ b/pandas/io/formats/format.py @@ -53,35 +53,38 @@ Parameters ---------- buf : StringIO-like, optional - buffer to write to - columns : sequence, optional - the subset of columns to write; default None writes all columns + Buffer to write to. + columns : sequence, optional, default None + The subset of columns to write. The default None writes all columns. col_space : int, optional - the minimum width of each column + The minimum width of each column. header : bool, optional - %(header)s - index : bool, optional - whether to print index (row) labels, default True - na_rep : string, optional - string representation of NAN to use, default 'NaN' - formatters : list or dict of one-parameter functions, optional - formatter functions to apply to columns' elements by position or name, - default None. The result of each function must be a unicode string. + %(header)s. + index : bool, optional, default True + Whether to print index (row) labels. + na_rep : str, optional, default 'NaN' + String representation of NAN to use. + formatters : list or dict of one-parameter functions, optional, default None + Formatter functions to apply to columns' elements by position or name. + The result of each function must be a unicode string. List must be of length equal to the number of columns. - float_format : one-parameter function, optional - formatter function to apply to columns' elements if they are floats, - default None. The result of this function must be a unicode string. - sparsify : bool, optional + float_format : one-parameter function, optional, default None + Formatter function to apply to columns' elements if they are floats. + The result of this function must be a unicode string. + sparsify : bool, optional, default True Set to False for a DataFrame with a hierarchical index to print every - multiindex key at each row, default True - index_names : bool, optional - Prints the names of the indexes, default True - line_width : int, optional - Width to wrap a line in characters, default no wrap - table_id : str, optional - id for the element create by to_html - - .. versionadded:: 0.23.0""" + multiindex key at each row. + index_names : bool, optional, default True + Prints the names of the indexes. + line_width : int, optional, default no wrap + Width to wrap a line in characters. + max_rows : int, optional + Maximum number of rows to display in the console. + max_cols : int, optional + Maximum number of columns to display in the console. + show_dimensions : bool, default False + Display dataframe's dimensions (number of rows by number of columns). + """ _VALID_JUSTIFY_PARAMETERS = ("left", "right", "center", "justify", "justify-all", "start", "end", "inherit", @@ -103,14 +106,14 @@ * inherit * match-parent * initial - * unset + * unset. """ return_docstring = """ - Returns ------- - formatted : string (or unicode, depending on data and options)""" + formatted : str (or unicode, depending on data and options) + """ docstring_to_string = common_docstring + justify_docstring + return_docstring From f9f436a1247a3034b3345b4f52bfe953b48a766d Mon Sep 17 00:00:00 2001 From: Tomasz-Kluczkowski Date: Sat, 10 Mar 2018 15:09:34 +0000 Subject: [PATCH 2/6] Shortened parameters to param. to make line <= 79 characters in formatters parameter description. --- pandas/io/formats/format.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/io/formats/format.py b/pandas/io/formats/format.py index 13d3264469537..e6c1c5c70895c 100644 --- a/pandas/io/formats/format.py +++ b/pandas/io/formats/format.py @@ -64,7 +64,7 @@ Whether to print index (row) labels. na_rep : str, optional, default 'NaN' String representation of NAN to use. - formatters : list or dict of one-parameter functions, optional, default None + formatters : list or dict of one-param. functions, optional, default None Formatter functions to apply to columns' elements by position or name. The result of each function must be a unicode string. List must be of length equal to the number of columns. From d4156f54e3f218842393f88e411127be0eef5ccc Mon Sep 17 00:00:00 2001 From: Tomasz-Kluczkowski Date: Tue, 13 Mar 2018 21:53:06 +0000 Subject: [PATCH 3/6] Added returns description as per standard. Fixed See Also description to match the standard. --- pandas/core/frame.py | 3 +-- pandas/io/formats/format.py | 3 ++- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index dc1fc29b299f5..70594139063b5 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -1732,8 +1732,7 @@ def to_string(self, buf=None, columns=None, col_space=None, header=True, See Also -------- - pandas.DataFrame.to_html - Convert dataframe to a html file. + pandas.DataFrame.to_html : Convert dataframe to a html file. Examples -------- diff --git a/pandas/io/formats/format.py b/pandas/io/formats/format.py index e6c1c5c70895c..21922d81e4305 100644 --- a/pandas/io/formats/format.py +++ b/pandas/io/formats/format.py @@ -112,7 +112,8 @@ return_docstring = """ Returns ------- - formatted : str (or unicode, depending on data and options) + str (or unicode, depending on data and options) + String representation of the dataframe. """ docstring_to_string = common_docstring + justify_docstring + return_docstring From 42ea45f01da247e7ca72df59baee6db0b01113ef Mon Sep 17 00:00:00 2001 From: Will Ayd Date: Sat, 7 Jul 2018 09:44:51 -0500 Subject: [PATCH 4/6] DOCstring fixup --- pandas/core/frame.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 70594139063b5..87a794d2d78d4 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -1718,21 +1718,23 @@ def to_parquet(self, fname, engine='auto', compression='snappy', @Substitution(header='Write out the column names. If a list of strings ' 'is given, it is assumed to be aliases for the ' 'column names') - @Appender(fmt.docstring_to_string, indents=1) + @Substitution(shared_docstring=fmt.docstring_to_string) def to_string(self, buf=None, columns=None, col_space=None, header=True, index=True, na_rep='NaN', formatters=None, float_format=None, - sparsify=None, index_names=True, + sparsify=None, index_names=True, justify=None, line_width=None, max_rows=None, max_cols=None, - show_dimensions=False, justify=None): + show_dimensions=False): """ Render a DataFrame to a console-friendly tabular output. Convert DataFrame object into a string (or unicode) representation which can be shown in command line interface. + %(shared_docstring)s + See Also -------- - pandas.DataFrame.to_html : Convert dataframe to a html file. + to_html : Convert dataframe to a html file. Examples -------- From acd5d1d593d93e579e2102d2bb9eaa260445fa90 Mon Sep 17 00:00:00 2001 From: Will Ayd Date: Sat, 7 Jul 2018 10:31:52 -0500 Subject: [PATCH 5/6] Shared argument fixup --- pandas/core/frame.py | 33 ++++++++++++++++++--------------- pandas/io/formats/format.py | 31 +++++++++++++------------------ 2 files changed, 31 insertions(+), 33 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index af9e9fc9dd899..fee26c3cb79d9 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -18,7 +18,7 @@ import sys import types import warnings -from textwrap import dedent +from textwrap import dedent, indent import numpy as np import numpy.ma as ma @@ -1955,7 +1955,8 @@ def to_parquet(self, fname, engine='auto', compression='snappy', @Substitution(header='Write out the column names. If a list of strings ' 'is given, it is assumed to be aliases for the ' 'column names') - @Substitution(shared_docstring=fmt.docstring_to_string) + @Substitution(shared_params=indent(fmt.common_docstring, " "), + returns=indent(fmt.return_docstring, " ")) def to_string(self, buf=None, columns=None, col_space=None, header=True, index=True, na_rep='NaN', formatters=None, float_format=None, sparsify=None, index_names=True, justify=None, @@ -1964,14 +1965,15 @@ def to_string(self, buf=None, columns=None, col_space=None, header=True, """ Render a DataFrame to a console-friendly tabular output. - Convert DataFrame object into a string (or unicode) representation - which can be shown in command line interface. + %(shared_params)s + line_width : int, optional, default no wrap + Width to wrap a line in characters. - %(shared_docstring)s + %(returns)s See Also -------- - to_html : Convert dataframe to a html file. + to_html : Convert DataFrame to HTML. Examples -------- @@ -2002,7 +2004,8 @@ def to_string(self, buf=None, columns=None, col_space=None, header=True, return result @Substitution(header='whether to print column labels, default True') - @Appender(fmt.docstring_to_string, indents=1) + @Substitution(shared_params=indent(fmt.common_docstring, " "), + returns=indent(fmt.return_docstring, " ")) def to_html(self, buf=None, columns=None, col_space=None, header=True, index=True, na_rep='NaN', formatters=None, float_format=None, sparsify=None, index_names=True, justify=None, bold_rows=True, @@ -2012,20 +2015,15 @@ def to_html(self, buf=None, columns=None, col_space=None, header=True, """ Render a DataFrame as an HTML table. - `to_html`-specific options: - + %(shared_params)s bold_rows : boolean, default True Make the row labels bold in the output classes : str or list or tuple, default None CSS class(es) to apply to the resulting html table escape : boolean, default True Convert the characters <, >, and & to HTML-safe sequences. - max_rows : int, optional - Maximum number of rows to show before truncating. If None, show - all. - max_cols : int, optional - Maximum number of columns to show before truncating. If None, show - all. + notebook : {True, False}, default False + Whether the generated HTML is for IPython Notebook. decimal : string, default '.' Character recognized as decimal separator, e.g. ',' in Europe @@ -2042,6 +2040,11 @@ def to_html(self, buf=None, columns=None, col_space=None, header=True, .. versionadded:: 0.23.0 + %(returns)s + + See Also + -------- + to_string : Convert DataFrame to a string. """ if (justify is not None and diff --git a/pandas/io/formats/format.py b/pandas/io/formats/format.py index 5ebf26f3ab9c8..b011fc1e575d4 100644 --- a/pandas/io/formats/format.py +++ b/pandas/io/formats/format.py @@ -71,21 +71,6 @@ multiindex key at each row. index_names : bool, optional, default True Prints the names of the indexes. - line_width : int, optional, default no wrap - Width to wrap a line in characters. - max_rows : int, optional - Maximum number of rows to display in the console. - max_cols : int, optional - Maximum number of columns to display in the console. - show_dimensions : bool, default False - Display dataframe's dimensions (number of rows by number of columns). - """ - -_VALID_JUSTIFY_PARAMETERS = ("left", "right", "center", "justify", - "justify-all", "start", "end", "inherit", - "match-parent", "initial", "unset") - -justify_docstring = """ justify : str, default None How to justify the column labels. If None uses the option from the print configuration (controlled by set_option), 'right' out @@ -102,7 +87,17 @@ * match-parent * initial * unset. -""" + max_rows : int, optional + Maximum number of rows to display in the console. + max_cols : int, optional + Maximum number of columns to display in the console. + show_dimensions : bool, default False + Display dataframe's dimensions (number of rows by number of columns). + """ + +_VALID_JUSTIFY_PARAMETERS = ("left", "right", "center", "justify", + "justify-all", "start", "end", "inherit", + "match-parent", "initial", "unset") return_docstring = """ Returns @@ -111,7 +106,7 @@ String representation of the dataframe. """ -docstring_to_string = common_docstring + justify_docstring + return_docstring +docstring_to_string = common_docstring + return_docstring class CategoricalFormatter(object): @@ -385,7 +380,7 @@ class DataFrameFormatter(TableFormatter): """ __doc__ = __doc__ if __doc__ else '' - __doc__ += common_docstring + justify_docstring + return_docstring + __doc__ += common_docstring + return_docstring def __init__(self, frame, buf=None, columns=None, col_space=None, header=True, index=True, na_rep='NaN', formatters=None, From 40cb3aa0c9320c0a9a17146e5846f2a14ede9876 Mon Sep 17 00:00:00 2001 From: Will Ayd Date: Sat, 7 Jul 2018 14:09:08 -0500 Subject: [PATCH 6/6] PY27 compat --- pandas/core/frame.py | 12 ++--- pandas/io/formats/format.py | 105 ++++++++++++++++++------------------ 2 files changed, 59 insertions(+), 58 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index fee26c3cb79d9..7ff4637e300b7 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -18,7 +18,7 @@ import sys import types import warnings -from textwrap import dedent, indent +from textwrap import dedent import numpy as np import numpy.ma as ma @@ -1955,8 +1955,8 @@ def to_parquet(self, fname, engine='auto', compression='snappy', @Substitution(header='Write out the column names. If a list of strings ' 'is given, it is assumed to be aliases for the ' 'column names') - @Substitution(shared_params=indent(fmt.common_docstring, " "), - returns=indent(fmt.return_docstring, " ")) + @Substitution(shared_params=fmt.common_docstring, + returns=fmt.return_docstring) def to_string(self, buf=None, columns=None, col_space=None, header=True, index=True, na_rep='NaN', formatters=None, float_format=None, sparsify=None, index_names=True, justify=None, @@ -1966,7 +1966,7 @@ def to_string(self, buf=None, columns=None, col_space=None, header=True, Render a DataFrame to a console-friendly tabular output. %(shared_params)s - line_width : int, optional, default no wrap + line_width : int, optional Width to wrap a line in characters. %(returns)s @@ -2004,8 +2004,8 @@ def to_string(self, buf=None, columns=None, col_space=None, header=True, return result @Substitution(header='whether to print column labels, default True') - @Substitution(shared_params=indent(fmt.common_docstring, " "), - returns=indent(fmt.return_docstring, " ")) + @Substitution(shared_params=fmt.common_docstring, + returns=fmt.return_docstring) def to_html(self, buf=None, columns=None, col_space=None, header=True, index=True, na_rep='NaN', formatters=None, float_format=None, sparsify=None, index_names=True, justify=None, bold_rows=True, diff --git a/pandas/io/formats/format.py b/pandas/io/formats/format.py index b011fc1e575d4..5f333276c57b4 100644 --- a/pandas/io/formats/format.py +++ b/pandas/io/formats/format.py @@ -45,54 +45,55 @@ from functools import partial common_docstring = """ - Parameters - ---------- - buf : StringIO-like, optional - Buffer to write to. - columns : sequence, optional, default None - The subset of columns to write. The default None writes all columns. - col_space : int, optional - The minimum width of each column. - header : bool, optional - %(header)s. - index : bool, optional, default True - Whether to print index (row) labels. - na_rep : str, optional, default 'NaN' - String representation of NAN to use. - formatters : list or dict of one-param. functions, optional, default None - Formatter functions to apply to columns' elements by position or name. - The result of each function must be a unicode string. - List must be of length equal to the number of columns. - float_format : one-parameter function, optional, default None - Formatter function to apply to columns' elements if they are floats. - The result of this function must be a unicode string. - sparsify : bool, optional, default True - Set to False for a DataFrame with a hierarchical index to print every - multiindex key at each row. - index_names : bool, optional, default True - Prints the names of the indexes. - justify : str, default None - How to justify the column labels. If None uses the option from - the print configuration (controlled by set_option), 'right' out - of the box. Valid values are - - * left - * right - * center - * justify - * justify-all - * start - * end - * inherit - * match-parent - * initial - * unset. - max_rows : int, optional - Maximum number of rows to display in the console. - max_cols : int, optional - Maximum number of columns to display in the console. - show_dimensions : bool, default False - Display dataframe's dimensions (number of rows by number of columns). + Parameters + ---------- + buf : StringIO-like, optional + Buffer to write to. + columns : sequence, optional, default None + The subset of columns to write. Writes all columns by default. + col_space : int, optional + The minimum width of each column. + header : bool, optional + %(header)s. + index : bool, optional, default True + Whether to print index (row) labels. + na_rep : str, optional, default 'NaN' + String representation of NAN to use. + formatters : list or dict of one-param. functions, optional + Formatter functions to apply to columns' elements by position or + name. + The result of each function must be a unicode string. + List must be of length equal to the number of columns. + float_format : one-parameter function, optional, default None + Formatter function to apply to columns' elements if they are + floats. The result of this function must be a unicode string. + sparsify : bool, optional, default True + Set to False for a DataFrame with a hierarchical index to print + every multiindex key at each row. + index_names : bool, optional, default True + Prints the names of the indexes. + justify : str, default None + How to justify the column labels. If None uses the option from + the print configuration (controlled by set_option), 'right' out + of the box. Valid values are + + * left + * right + * center + * justify + * justify-all + * start + * end + * inherit + * match-parent + * initial + * unset. + max_rows : int, optional + Maximum number of rows to display in the console. + max_cols : int, optional + Maximum number of columns to display in the console. + show_dimensions : bool, default False + Display DataFrame dimensions (number of rows by number of columns). """ _VALID_JUSTIFY_PARAMETERS = ("left", "right", "center", "justify", @@ -100,10 +101,10 @@ "match-parent", "initial", "unset") return_docstring = """ - Returns - ------- - str (or unicode, depending on data and options) - String representation of the dataframe. + Returns + ------- + str (or unicode, depending on data and options) + String representation of the dataframe. """ docstring_to_string = common_docstring + return_docstring