Skip to content
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

DOC: Improve docstring for pandas.Index.repeat #19985

Merged
merged 8 commits into from
Mar 9, 2018
Merged

DOC: Improve docstring for pandas.Index.repeat #19985

Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3e33406
Fix docstring
alysivji Mar 4, 2018
1fc4b33
Update location of underlying numpy function
alysivji Mar 4, 2018
5270363
Update with PR comments
alysivji Mar 7, 2018
d4fd529
Simplify docstring
alysivji Mar 7, 2018
9a57c25
Update for change in the docstring guide
jorisvandenbossche Mar 8, 2018
cf4999f
Add kwargs to parameters list
alysivji Mar 9, 2018
4cbaa48
Merge branch 'doc_index-repeat' of github.com:alysivji/pandas into do…
alysivji Mar 9, 2018
8486969
Fix keyword argument parameter in docstring
alysivji Mar 9, 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
34 changes: 30 additions & 4 deletions pandas/core/indexes/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -696,12 +696,38 @@ def memory_usage(self, deep=False):
@deprecate_kwarg(old_arg_name='n', new_arg_name='repeats')
def repeat(self, repeats, *args, **kwargs):
"""
Repeat elements of an Index. Refer to `numpy.ndarray.repeat`
for more information about the `repeats` argument.
Repeat elements of an Index.

See also
Returns a new index where each element of the current index
is repeated consecutively a given number of times.

Parameters
----------
repeats : int
The number of repetitions for each element.
Copy link
Member

Choose a reason for hiding this comment

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

There is still some discussion on whether we want to document args and kwargs, but I think we should. If they are ignored, I think it'd be useful for users (and also developers) to know it, and why they are present. If they are being sent to numpy, that's also something worth mentioning.

Copy link
Contributor

Choose a reason for hiding this comment

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

these are for numpy compat (only a small set of methods are like this). see the validate_repeat below.

Copy link
Member

Choose a reason for hiding this comment

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

In this case the *kwargs are not ignored, but you get an informative error message if you try to pass any additional keyword (also in case of the numpy ones like axis). So therefore I would personally not document them.

Copy link
Contributor

Choose a reason for hiding this comment

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

I would agree that mentioned **kwargs are for numpy compat is not a bad idea

Copy link
Member

Choose a reason for hiding this comment

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

I thought it was only for the nice error message, but indeed it is also accepting (not raising) the argument when it is the default value (in this case axis=None).
In that case, it's fine for me as well to actually document this

kwargs : keyword, value pairs
Copy link
Member

Choose a reason for hiding this comment

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

I think we have a bug in the validate_docstrings.py script, but I don't think we want to have type for kwargs as it's always a dict of {str: anything}. Also the name should be **kwargs, that's definitely a bug in the script, that has been reported before.

Not sure if I'm missing something, but why don't we have *args in the docstrings?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Will fix to use **kwargs.

I think it's confusing to use args.

idx = pd.Index([1, 2]).repeat(2, 1) gives the following error:
ValueError: the 'axis' parameter is not supported in the pandas implementation of repeat().

You'd have to go digging into the numpy implementation to see what this whole axis thing is about.

Copy link
Member

Choose a reason for hiding this comment

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

+1 for using **kwargs instead of kwargs (sphinx does not seem to complain about it, that was what I first feared)

Copy link
Contributor

Choose a reason for hiding this comment

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

I'm now confused @datapythonista . Should we use kwargs or **kwargs as the argument name in the docstring? Because in the mailing list you said kwargs is more common.

Copy link
Member

Choose a reason for hiding this comment

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

I'll answer on the mailing list. Let's go for **kwargs, and I am trying to fix the validation script: #20072

Additional keywords have no effect but might be accepted for
compatibility with numpy.

Returns
-------
pandas.Index
Newly created Index with repeated elements.

See Also
--------
Series.repeat : Equivalent function for Series
numpy.repeat : Underlying implementation
Copy link
Member

Choose a reason for hiding this comment

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

May be we could have the is_unique methods? Just an idea, not sure if it's so related...


Examples
--------
numpy.ndarray.repeat
>>> idx = pd.Index([1, 2, 3])
>>> idx
Int64Index([1, 2, 3], dtype='int64')
>>> idx.repeat(2)
Int64Index([1, 1, 2, 2, 3, 3], dtype='int64')
>>> idx.repeat(3)
Int64Index([1, 1, 1, 2, 2, 2, 3, 3, 3], dtype='int64')
"""
nv.validate_repeat(args, kwargs)
return self._shallow_copy(self._values.repeat(repeats))
Expand Down