Groupbydocs
State: closed

Addresses #6944, by defining whitelisted methods in the `DataFrameGroupBy` and `SeriesGroupBy` class definitions.  After this change, users of the whitelisted methods now get useful results from `help`, argument name completion, and auto-generated api docs.  These `DataFrameGroupBy` and `SeriesGroupBy` methods are added to the api doc.  Existing unit tests are extended to check for the presence of the whitelisted methods in the class definitions, and a new unit test verifies that old and new paths produce the same results for methods supporting level, axis, skipna arguments.  (Existing methods already explicitly defined in `GroupBy` or derived classes are not overwritten.)


Labels:
name: Docs
name: Groupby

Comments:
can you indicate which of the checkboxes this will close from the issue.

This should close these checkboxes:
- document the whitelisted methods (These are now added to api.rst)
- More clearly document the DataFrameGroupBy and SeriesGroupBy classes at least mention them in the docs. (Both now appear in api.rst with their respective whitelist methods)
- Add docstrings to the wrapped whitelisted functions. (Their docstrings now contain the documentation from their respective DataFrame/Series methods.)

I moved the unit test into test_groupby.py, and tweaked the exec'ed strings to fix the syntax error that the CI build was raising.  These look like they are passing.

Should I submit another pull request?

@mcjcode Thanks for your work on this!

+1 that all the methods now have help messages (didn't look at the implementation yet)

But I am not sure I also like adding them all to api.rst. I mean having seperate `DataFrame/SeriesGroupby` methods listed. It should be clearly documented that in practice you work with these objects, but listing all methods of both seperately seems also like a lot of repetition (in many cases, they are the same for both, and also the same for Series/DataFrame). Plus, some things are documented on `GroupBy`, other things on `DataFrame/SeriesGroupby` which also does not make it more clear. Another option is to also add these methods to `GroupBy` in the same way and document these?

@jorisvandenbossche - I agree.  I put all of the additional methods under the `GroupBy` Computation/Descriptive functions heading in api.rst, and broke out the few cases there where a method is defined only for one of `DataFrameGroupBy` and `SeriesGroupBy` or the other.

@jreback - I put the `inspect` import inside the function def.  That makes sense.

The point of the additional tests were to check that ...
1.  in addition to being `getattr`-able from a GroupBy _object_,  the whitelisted methods are also _defined in the class_, and ...
2.  you get the same answer whether you use the `DataFrameGroupBy` method or call the same `DataFrame` method with the level argument.

The `dtypes` exclusion was a remnant of when I hadn't wrapped it as a class member.  Now that it is defined as a property in the class, this is unnecessary.  I also extended the second test to nine other methods, ones that don't take a `skipna` parameter.

@mcjcode small change, otherwise looks ok to me.

Moved make_signature from groupby.py to decorators.py.

merged via https://github.com/pydata/pandas/commit/0acfa4424697e064bc230199e5dbbcf570908bdb

thanks!

@mcjcode I checked off some boxed in #6944 pls lmk if I missed any (or didn't do some that need)

thanks!

This also "added docstrings to the wrapped whitelisted functions"

So we should check that one off as well.