DOC: add docstring for Index.get_duplicates

[csfarkas]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
################### Docstring (pandas.Index.get_duplicates)  ###################
################################################################################

        Extract duplicated index elements.

        Returns a sorted list of index elements which appear more than once in
        the index.

        Returns
        -------
        array-like
            List of duplicated indexes.

        See Also
        --------
        Index.duplicated : Return boolean array denoting duplicates.
        Index.drop_duplicates : Return Index with duplicates removed.

        Examples
        --------

        Works on different Index of types.

        >>> pd.Index([1, 2, 2, 3, 3, 3, 4]).get_duplicates()
        [2, 3]
        >>> pd.Index([1., 2., 2., 3., 3., 3., 4.]).get_duplicates()
        [2.0, 3.0]
        >>> pd.Index(['a', 'b', 'b', 'c', 'c', 'c', 'd']).get_duplicates()
        ['b', 'c']
        >>> dates = pd.to_datetime(['2018-01-01', '2018-01-02', '2018-01-03',
        ...                         '2018-01-03', '2018-01-04', '2018-01-04'],
        ...                        format='%Y-%m-%d')
        >>> pd.Index(dates).get_duplicates()
        DatetimeIndex(['2018-01-03', '2018-01-04'],
                      dtype='datetime64[ns]', freq=None)

        Sorts duplicated elements even when indexes are unordered.

        >>> pd.Index([1, 2, 3, 2, 3, 4, 3]).get_duplicates()
        [2, 3]

        Return empty array-like structure when all elements are unique.

        >>> pd.Index([1, 2, 3, 4]).get_duplicates()
        []
        >>> dates = pd.to_datetime(['2018-01-01', '2018-01-02', '2018-01-03'],
        ...                        format='%Y-%m-%d')
        >>> pd.Index(dates).get_duplicates()
        DatetimeIndex([], dtype='datetime64[ns]', freq=None)

        Notes
        -----
        In case of datetime-like indexes, the function is overridden where the
        result is converted to DatetimeIndex.

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Index.get_duplicates" correct. :)

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[pep8speaks]

Hello @csfarkas! Thanks for updating the PR.

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

Comment last updated on March 11, 2018 at 10:51 Hours UTC

[jorisvandenbossche]

Nice docstring! Added some comments

[jorisvandenbossche]

In the See Also section, it is not needed to make an explicit link with the :meth:`..` syntax, you can just use Index.duplicated

[jorisvandenbossche]

you don't need to repeat the to_datetime here.

Can you also add a sentence here before the example explaining that for DatetimeIndex, it does not return a list but a DatetetimeIndex ?

[jorisvandenbossche]

I would put this explanation above the actual example where you show this

[csfarkas]

Updated docstring based on the suggestions by @jorisvandenbossche. Thanks for the review.

[jreback]

thanks @csfarkas

[jorisvandenbossche]

Added a small comment about the "Notes" that is not clear for me.
The PR is already merge, but feel free to open an new PR to address that comment!

[jorisvandenbossche]

This note is not really clear to me. What do you want to explain?
You already show above that the return value in case of DatetimeIndex is different.

[csfarkas]

Basically, I wanted to explain why get_duplicates return a DatetimeIndex instead of a list when dates are used.

When dates are passed to the Index class, the DatetimeIndexOpsMixin.get_duplicates function is used. This function calls the Index.get_duplicates and converts the results to DatetimeIndex.

I did not want to get into such details, since I could not mention private classes in the docstring.

Should I get into even less detail? I was wondering whether the following note is enough:
"In case of datetime-like indexes, DatetimeIndex is returned instead of a list."

[jorisvandenbossche]

OK, I understand. What is important to the user is what is returned, and you already show in the examples that for DatetimeIndex a DatetimeIndex and not a list is returned.
The fact that this internally is implemented by overwriting that method in DatetimeIndex is not really important for users, so I would then just remove this comment.

Feel free to open a PR for it!

[csfarkas]

Removed Notes section:
DOC: update the Index.get duplicates docstring #20322