DOC: Expose ExcelWriter as part of the Generated API #22359

newinh · 2018-08-15T07:26:58Z

closes Expose ExcelWriter as part of the Generated API #21835
N/A tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
N/A whatsnew entry

codecov · 2018-08-15T18:41:35Z

Codecov Report

Merging #22359 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #22359   +/-   ##
=======================================
  Coverage   92.05%   92.05%           
=======================================
  Files         169      169           
  Lines       50733    50733           
=======================================
  Hits        46702    46702           
  Misses       4031     4031

Flag	Coverage Δ
#multiple	`90.46% <ø> (ø)`	⬆️
#single	`42.24% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	`96.44% <ø> (ø)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 68273a7...e69316f. Read the comment docs.

WillAyd

Thanks for the PR! Can you also add an examples section to the docstring so people know how to use it?

I think we should also prevent the abstract properties and methods from being rendered, but copying @datapythonista for input

newinh · 2018-08-16T16:27:50Z

@WillAyd yeap i'll try to add an example:)

jorisvandenbossche · 2018-08-17T07:35:11Z

I think we should also prevent the abstract properties and methods from being rendered

Yes, and I would also add a note in the docstring explicitly saying that none of the methods/properties are considered public? (only 'public' usage is what is in the example?)
To avoid this rendering with sphinx of all methods, you need to do something like this:

.. autosummary::
   :toctree: generated/
   :template: autosummary/class_without_autosummary.rst

   ExcelWriter

WillAyd · 2018-08-17T10:35:32Z

@newinh this is really shaping up! When I built your latest commit locally I was still seeing the methods and attributes we are trying to hide - were you not seeing these on your end? I think there is still something that needs to be tweaked there.

One other thing that would make this nice - the mode argument is getting added in v0.24. If you can expand your example to show how to subsequently append to an Excel file that would cover all the use cases here.

jorisvandenbossche · 2018-08-17T11:51:17Z

When I built your latest commit locally I was still seeing the methods and attributes we are trying to hide

Looking at how the Int64Index docstring is done (there everything is hidden in previous docs: https://pandas.pydata.org/pandas-docs/version/0.22.0/generated/pandas.Int64Index.html (in new docs, you get None listed, but will open a new issue for that, let's follow here the same practice)), I think this needs to be added to the docstring (a bit ugly ...):

Attributes
----------
None

Methods
-------
None

jorisvandenbossche · 2018-08-17T11:51:56Z

Can you also add a note in the docstring explicitly saying that none of the methods/properties are considered public?

newinh · 2018-08-18T17:06:48Z

@WillAyd Indeed, I've seen a abstract properties that shouldn't have appeared in docs page. But I thought it is a problem of my local environment. (I first built the document)

Thanks to @jorisvandenbossche, I hid it.

newinh · 2018-08-18T17:09:47Z

Added example cases and more details to note.

As you know, there may be some mistakes because of my lack of English. If so, Please let me know:)

WillAyd

Minor edits. There is also a note in the docstring to "See DataFrame.to_excel for typical usage" Can you instead create a "See Also" section that references that method?

WillAyd · 2018-08-18T21:35:33Z

pandas/io/excel.py

@@ -824,8 +824,56 @@ class ExcelWriter(object):

    Notes
    -----
+    None of methods and properties are considered public.


"None of methods" -> "None of the methods"

WillAyd · 2018-08-18T21:37:03Z

pandas/io/excel.py

+    >>> with ExcelWriter('path_to_file.xlsx') as writer:
+    ...     df.to_excel(writer)
+
+    If you want to set engine that can manipulate Excel,


I think this second example is better served in to_excel as it generic functionality. Would be OK if you removed here and added that to the to_excel docs in a separate change

WillAyd · 2018-08-18T21:37:13Z

pandas/io/excel.py

+
+    Examples
+    --------
+    Using ExcelWriter, some settings can be added.


Remove this line

WillAyd · 2018-08-18T21:38:02Z

pandas/io/excel.py

+    --------
+    Using ExcelWriter, some settings can be added.
+
+    Default usage.


Instead of a "." use ":"

WillAyd · 2018-08-18T21:43:34Z

pandas/io/excel.py

+
+    You can set date format or datetime format
+
+    >>> with ExcelWriter('path_to_file.xlsx',


I am actually surprised that we allow date / date time formatting with ExcelWriter but don't have the same usage in to_excel - if you are up to it aligning that functionality would be ideal (separate change)

WillAyd · 2018-08-18T21:44:00Z

pandas/io/excel.py

+    >>> with ExcelWriter('path_to_file.xlsx', engine='openpyxl') as writer:
+    ...     df.to_excel(writer)
+
+    In order to write separate DataFrames to separate sheets


Just say "To write to separate sheets in a single file:"

WillAyd · 2018-08-18T21:44:18Z

pandas/io/excel.py

+                          datetime_format='YYYY-MM-DD HH:MM:SS') as writer:
+    ...     df.to_excel(writer)
+
+    It also supports append mode.


"You can also append to an existing Excel file:"

newinh · 2018-08-20T13:00:30Z

I do not know why the Travis CI build failed. Where should i look to fix it?

WillAyd

The test failure is because you changed pd.ExcelWriter to ExcelWriter in the example so Python doesn't know what you are referencing. If you revert that back should be OK (couple other edits needed as commented)

WillAyd · 2018-08-20T17:19:21Z

pandas/core/generic.py

+    >>> with ExcelWriter('output2.xlsx', engine='openpyxl') as writer:
+    ...     df2.to_excel(writer)
+
+    You can set date format or datetime format:


Delete this example (keywords here are only applicable to ExcelWriter)

WillAyd · 2018-08-20T17:21:07Z

pandas/core/generic.py

+    ...     df1.to_excel(writer, sheet_name='Sheet_name_1')
+    ...     df2.to_excel(writer, sheet_name='Sheet_name_2')
+
+    If you want to set engine that can manipulate Excel,


Don't use ExcelWriter here - just use to_excel. Also move this example up above the one preceding it

pep8speaks · 2018-08-20T18:01:43Z

Hello @newinh! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on August 22, 2018 at 09:30 Hours UTC

* Also Update some examples of to_excel method

jorisvandenbossche · 2018-08-20T18:32:31Z

pandas/io/excel.py

+    You can also append to an existing Excel file:
+
+    >>> with ExcelWriter('path_to_file.xlsx', mode='a') as writer:
+    ...     df.to_excel(writer)


I would add here a sheet name? (I think you typically want to add a new sheet to an existing file?)

It seems more natural to do that:)

jorisvandenbossche · 2018-08-20T18:35:30Z

pandas/core/generic.py

@@ -1917,18 +1917,24 @@ def _repr_latex_(self):
    ...                   columns=['col 1', 'col 2'])
    >>> df1.to_excel("output.xlsx")

+    If you want to set engine that can manipulate Excel,
+    pass keyword argument named engine. Actually
+    engine is automatically chosen by file extension:


Suggestion with some changed language:

To set the library that used to write the Excel file, you can pass the `engine` keyword (the default engine is automatically chosen depending on the file extension):

…r-api

jorisvandenbossche

Minor comment, looks good to me!

jorisvandenbossche · 2018-08-21T15:36:29Z

pandas/io/excel.py

+    >>> with ExcelWriter('path_to_file.xlsx', mode='a') as writer:
+    ...     df.to_excel(writer, sheet_name='Sheet3')
+
+    .. versionadded:: 0.24.0


I think this one can be removed

WillAyd · 2018-08-21T16:35:09Z

pandas/core/generic.py

-    >>> writer.save()
+    >>> with pd.ExcelWriter('output.xlsx') as writer:
+    ...     df1.to_excel(writer, sheet_name='Sheet_name_1')
+    ...     df2 = df1.copy()


Can you do this copy outside of the context manager? On initial glance I assumed it to be some requirement with the context manager itself, though that's clearly not the case

WillAyd

I think this looks good and slightly prefer the example with append mode but am largely indifferent.
@jorisvandenbossche merge when satisfied.

jorisvandenbossche · 2018-08-22T09:31:06Z

slightly prefer the example with append mode but am largely indifferent

@WillAyd what do you mean exactly?

WillAyd · 2018-08-22T13:24:55Z

@WillAyd what do you mean exactly?

Your last comment asked to remove a piece that I would slightly prefer to keep in, but not going to lose sleep over it if you think its superfluous and still want to remove 👍

jreback · 2018-09-18T12:54:35Z

thanks @newinh

Expose ExcelWriter as part of the Generated API

e040ab0

jschendel added Docs IO Excel read_excel, to_excel labels Aug 15, 2018

jschendel added this to the 0.24.0 milestone Aug 15, 2018

WillAyd requested changes Aug 15, 2018

View reviewed changes

Add an exmaples section of ExcelWriter

76edcde

Use without_autosummary teamplate

a416f92

WillAyd mentioned this pull request Aug 17, 2018

DOC: html build of class docstrings without autosummary shows None #22398

Open

newinh added 2 commits August 19, 2018 01:58

Notice explicitly ExcelWriter hasn't public methods and properties

172257a

Add example usases of ExcelWriter cass

e218103

WillAyd requested changes Aug 18, 2018

View reviewed changes

Align with to_excel method

b2f1880

WillAyd requested changes Aug 20, 2018

View reviewed changes

Fix Travis Ci build failed

04b59a5

* Also Update some examples of to_excel method

newinh force-pushed the expose-excelwriter-api branch from 05884a7 to 04b59a5 Compare August 20, 2018 18:03

jorisvandenbossche reviewed Aug 20, 2018

View reviewed changes

newinh and others added 3 commits August 21, 2018 22:59

Change language expression of some exmples

546ce0a

Merge remote-tracking branch 'upstream/master' into expose-excelwrite…

ec2fe16

…r-api

typo

b74364e

jorisvandenbossche approved these changes Aug 21, 2018

View reviewed changes

Fix doctest

40fd6fe

WillAyd requested changes Aug 21, 2018

View reviewed changes

Use context manager cleary

1d0e833

WillAyd approved these changes Aug 21, 2018

View reviewed changes

remove versionadded

e69316f

jreback merged commit c44581f into pandas-dev:master Sep 18, 2018

newinh deleted the expose-excelwriter-api branch September 18, 2018 14:51

aeltanawy pushed a commit to aeltanawy/pandas that referenced this pull request Sep 20, 2018

DOC: Expose ExcelWriter as part of the Generated API (pandas-dev#22359)

9935305

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

DOC: Expose ExcelWriter as part of the Generated API (pandas-dev#22359)

3a4b501

rhshadrach mentioned this pull request Sep 2, 2021

ENH: Rename ExcelWriter to make clear attributes are not public #43088

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Expose ExcelWriter as part of the Generated API #22359

DOC: Expose ExcelWriter as part of the Generated API #22359

newinh commented Aug 15, 2018 •

edited

Loading

codecov bot commented Aug 15, 2018 •

edited

Loading

WillAyd left a comment

newinh commented Aug 16, 2018

jorisvandenbossche commented Aug 17, 2018

WillAyd commented Aug 17, 2018

jorisvandenbossche commented Aug 17, 2018

jorisvandenbossche commented Aug 17, 2018

newinh commented Aug 18, 2018 •

edited

Loading

newinh commented Aug 18, 2018

WillAyd left a comment

WillAyd Aug 18, 2018

WillAyd Aug 18, 2018

WillAyd Aug 18, 2018

WillAyd Aug 18, 2018

WillAyd Aug 18, 2018

WillAyd Aug 18, 2018

WillAyd Aug 18, 2018

newinh commented Aug 20, 2018

WillAyd left a comment

WillAyd Aug 20, 2018

WillAyd Aug 20, 2018

pep8speaks commented Aug 20, 2018 •

edited

Loading

jorisvandenbossche Aug 20, 2018

newinh Aug 21, 2018 •

edited

Loading

jorisvandenbossche Aug 20, 2018

jorisvandenbossche left a comment

jorisvandenbossche Aug 21, 2018

WillAyd Aug 21, 2018

WillAyd left a comment

jorisvandenbossche commented Aug 22, 2018

WillAyd commented Aug 22, 2018

jreback commented Sep 18, 2018


		You can set date format or datetime format

		>>> with ExcelWriter('path_to_file.xlsx',

DOC: Expose ExcelWriter as part of the Generated API #22359

DOC: Expose ExcelWriter as part of the Generated API #22359

Conversation

newinh commented Aug 15, 2018 • edited Loading

codecov bot commented Aug 15, 2018 • edited Loading

Codecov Report

WillAyd left a comment

Choose a reason for hiding this comment

newinh commented Aug 16, 2018

jorisvandenbossche commented Aug 17, 2018

WillAyd commented Aug 17, 2018

jorisvandenbossche commented Aug 17, 2018

jorisvandenbossche commented Aug 17, 2018

newinh commented Aug 18, 2018 • edited Loading

newinh commented Aug 18, 2018

WillAyd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

newinh commented Aug 20, 2018

WillAyd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pep8speaks commented Aug 20, 2018 • edited Loading

Comment last updated on August 22, 2018 at 09:30 Hours UTC

Choose a reason for hiding this comment

newinh Aug 21, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

WillAyd left a comment

Choose a reason for hiding this comment

jorisvandenbossche commented Aug 22, 2018

WillAyd commented Aug 22, 2018

jreback commented Sep 18, 2018

newinh commented Aug 15, 2018 •

edited

Loading

codecov bot commented Aug 15, 2018 •

edited

Loading

newinh commented Aug 18, 2018 •

edited

Loading

pep8speaks commented Aug 20, 2018 •

edited

Loading

newinh Aug 21, 2018 •

edited

Loading