Skip to content

DOC: update the to_excel docstring #20185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jul 24, 2018
Merged

DOC: update the to_excel docstring #20185

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3cdb8b3
Fix to_excel parameters
robmarkcole Mar 10, 2018
0e9f733
Extend example, add Also
robmarkcole Mar 10, 2018
8eb8330
Extend summary
robmarkcole Mar 10, 2018
48116e2
Address reviewer comments
robmarkcole Mar 13, 2018
69921c6
Address second round of comments
robmarkcole Mar 14, 2018
6755281
Address comments
robmarkcole Apr 4, 2018
ede409d
Merge remote-tracking branch 'upstream/master' into robmarkcole-to_ex…
TomAugspurger Jul 24, 2018
b2a6496
Updated
TomAugspurger Jul 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 23 additions & 18 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1591,52 +1591,57 @@ def _repr_latex_(self):
# I/O Methods

_shared_docs['to_excel'] = """
Write %(klass)s to an excel sheet
Write %(klass)s to an excel sheet.
%(versionadded_to_excel)s

Parameters
----------
excel_writer : string or ExcelWriter object
File path or existing ExcelWriter
File path or existing ExcelWriter.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we link to the class? I believe

:class:`pandas.ExcelWriter`

should work.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, in the extended description we say that an ExcelWriter object is necessary to be able to use .to_excel, but in the parameter description we say that we also accept a "file path". So the ExcelWriter is not really needed? What happens if we specify a file path? I guess that a new ExcelWriter gets automatically created with default options.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes this is allowed df1.to_excel("example.xlsx", sheet_name='Sheet3')

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the ExcelWriter is not required

sheet_name : string, default 'Sheet1'
Name of sheet which will contain DataFrame
Name of sheet which will contain DataFrame.
na_rep : string, default ''
Missing data representation
Missing data representation.
float_format : string, default None
Format string for floating point numbers
Format string for floating point numbers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you mention some examples and/or link to where the format of this parameter is documented?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Formatting takes place here using the string modulo operator which is described here. I've added an example.

columns : sequence, optional
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sequence of what? I think this should be "list of str or list of int" to select columns.

Also, add "If not specified, all columns will be written".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW I think this parameter probably makes no sense for Series.to_excel and the docstring is shared. We should find a way to not show this parameter in the docs in this case.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added list of strings

Columns to write
Columns to write.
header : boolean or list of string, default True
Write out the column names. If a list of strings is given it is
assumed to be aliases for the column names
assumed to be aliases for the column names.
index : boolean, default True
Write row names (index)
Write row names (index).
index_label : string or sequence, default None
Column label for index column(s) if desired. If None is given, and
`header` and `index` are True, then the index names are used. A
sequence should be given if the DataFrame uses MultiIndex.
startrow :
upper left cell row to dump data frame
startcol :
upper left cell column to dump data frame
startrow : integer, default 0
Upper left cell row to dump data frame.
startcol : integer, default 0
Upper left cell column to dump data frame.
engine : string, default None
write engine to use - you can also set this via the options
Write engine to use - you can also set this via the options
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which options? I understand the string is the fully qualified import part for the write engine class. Are the ones shown there examples? Can we specify that in the docs?

Copy link
Contributor Author

@robmarkcole robmarkcole Mar 13, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It appears the options are 'openpyxl', 'xlsxwriter', 'xlwt', although in my testing only 'openpyxl', 'xlsxwriter', work

``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and
``io.excel.xlsm.writer``.
merge_cells : boolean, default True
Write MultiIndex and Hierarchical Rows as merged cells.
encoding: string, default None
encoding of the resulting excel file. Only necessary for xlwt,
encoding : string, default 'ascii'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How did you figure this out? Reading the code of DataFrame.to_excel it looks like this parameter is ignored!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are correct

Encoding of the resulting excel file. Only necessary for xlwt,
other writers support unicode natively.
inf_rep : string, default 'inf'
Representation for infinity (there is no native representation for
infinity in Excel)
infinity in Excel).
verbose : boolean, default True
Display more information in the error logs.
freeze_panes : tuple of integer (length 2), default None
Specifies the one-based bottommost row and rightmost column that
is to be frozen
is to be frozen.

.. versionadded:: 0.20.0

Returns
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the function doesn't return anything I think it's better to omit this section.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK

-------
Nothing returned.

Notes
-----
If passing an existing ExcelWriter object, then the sheet will be added
Expand Down