Skip to content

Commit 171076c

Browse files
robmarkcoleTomAugspurger
authored andcommitted
DOC: update the to_excel docstring (#20185)
1 parent 3e48393 commit 171076c

File tree

1 file changed

+68
-35
lines changed

1 file changed

+68
-35
lines changed

pandas/core/generic.py

+68-35
Original file line numberDiff line numberDiff line change
@@ -1836,65 +1836,98 @@ def _repr_latex_(self):
18361836
# I/O Methods
18371837

18381838
_shared_docs['to_excel'] = """
1839-
Write %(klass)s to an excel sheet
1840-
%(versionadded_to_excel)s
1839+
Write %(klass)s to an excel sheet.
1840+
1841+
To write a single %(klass)s to an excel .xlsx file it is only necessary to
1842+
specify a target file name. To write to multiple sheets it is necessary to
1843+
create an `ExcelWriter` object with a target file name, and specify a sheet
1844+
in the file to write to. Multiple sheets may be written to by
1845+
specifying unique `sheet_name`. With all data written to the file it is
1846+
necessary to save the changes. Note that creating an ExcelWriter object
1847+
with a file name that already exists will result in the contents of the
1848+
existing file being erased.
18411849
18421850
Parameters
18431851
----------
18441852
excel_writer : string or ExcelWriter object
1845-
File path or existing ExcelWriter
1853+
File path or existing ExcelWriter.
18461854
sheet_name : string, default 'Sheet1'
1847-
Name of sheet which will contain DataFrame
1855+
Name of sheet which will contain DataFrame.
18481856
na_rep : string, default ''
1849-
Missing data representation
1850-
float_format : string, default None
1851-
Format string for floating point numbers
1852-
columns : sequence, optional
1853-
Columns to write
1857+
Missing data representation.
1858+
float_format : string, optional
1859+
Format string for floating point numbers. For example
1860+
``float_format="%%.2f"`` will format 0.1234 to 0.12.
1861+
columns : sequence or list of string, optional
1862+
Columns to write.
18541863
header : boolean or list of string, default True
18551864
Write out the column names. If a list of strings is given it is
1856-
assumed to be aliases for the column names
1865+
assumed to be aliases for the column names.
18571866
index : boolean, default True
1858-
Write row names (index)
1859-
index_label : string or sequence, default None
1860-
Column label for index column(s) if desired. If None is given, and
1867+
Write row names (index).
1868+
index_label : string or sequence, optional
1869+
Column label for index column(s) if desired. If not specified, and
18611870
`header` and `index` are True, then the index names are used. A
18621871
sequence should be given if the DataFrame uses MultiIndex.
1863-
startrow :
1864-
upper left cell row to dump data frame
1865-
startcol :
1866-
upper left cell column to dump data frame
1867-
engine : string, default None
1868-
write engine to use - you can also set this via the options
1869-
``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and
1872+
startrow : integer, default 0
1873+
Upper left cell row to dump data frame.
1874+
startcol : integer, default 0
1875+
Upper left cell column to dump data frame.
1876+
engine : string, optional
1877+
Write engine to use, 'openpyxl' or 'xlsxwriter'. You can also set this
1878+
via the options ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and
18701879
``io.excel.xlsm.writer``.
18711880
merge_cells : boolean, default True
18721881
Write MultiIndex and Hierarchical Rows as merged cells.
1873-
encoding: string, default None
1874-
encoding of the resulting excel file. Only necessary for xlwt,
1882+
encoding : string, optional
1883+
Encoding of the resulting excel file. Only necessary for xlwt,
18751884
other writers support unicode natively.
18761885
inf_rep : string, default 'inf'
18771886
Representation for infinity (there is no native representation for
1878-
infinity in Excel)
1879-
freeze_panes : tuple of integer (length 2), default None
1887+
infinity in Excel).
1888+
verbose : boolean, default True
1889+
Display more information in the error logs.
1890+
freeze_panes : tuple of integer (length 2), optional
18801891
Specifies the one-based bottommost row and rightmost column that
1881-
is to be frozen
1892+
is to be frozen.
18821893
1883-
.. versionadded:: 0.20.0
1894+
.. versionadded:: 0.20.0.
18841895
18851896
Notes
18861897
-----
1887-
If passing an existing ExcelWriter object, then the sheet will be added
1888-
to the existing workbook. This can be used to save different
1889-
DataFrames to one workbook:
1898+
For compatibility with :meth:`~DataFrame.to_csv`,
1899+
to_excel serializes lists and dicts to strings before writing.
18901900
1891-
>>> writer = pd.ExcelWriter('output.xlsx')
1892-
>>> df1.to_excel(writer,'Sheet1')
1893-
>>> df2.to_excel(writer,'Sheet2')
1894-
>>> writer.save()
1901+
Once a workbook has been saved it is not possible write further data
1902+
without rewriting the whole workbook.
1903+
1904+
See Also
1905+
--------
1906+
pandas.read_excel
1907+
pandas.ExcelWriter
1908+
1909+
Examples
1910+
--------
18951911
1896-
For compatibility with to_csv, to_excel serializes lists and dicts to
1897-
strings before writing.
1912+
Create, write to and save a workbook:
1913+
1914+
>>> df1 = pd.DataFrame([['a', 'b'], ['c', 'd']],
1915+
... index=['row 1', 'row 2'],
1916+
... columns=['col 1', 'col 2'])
1917+
>>> df1.to_excel("output.xlsx")
1918+
1919+
To specify the sheet name:
1920+
1921+
>>> df1.to_excel("output.xlsx", sheet_name='Sheet_name_1')
1922+
1923+
If you wish to write to more than one sheet in the workbook, it is
1924+
necessary to specify an ExcelWriter object:
1925+
1926+
>>> writer = pd.ExcelWriter('output2.xlsx', engine='xlsxwriter')
1927+
>>> df1.to_excel(writer, sheet_name='Sheet1')
1928+
>>> df2 = df1.copy()
1929+
>>> df2.to_excel(writer, sheet_name='Sheet2')
1930+
>>> writer.save()
18981931
"""
18991932

19001933
def to_json(self, path_or_buf=None, orient=None, date_format=None,

0 commit comments

Comments
 (0)