DOC: fix EX02 errors in docstrings

[natmokval]

Related to the issue #51236

This PR enables functions:
pandas.core.groupby.DataFrameGroupBy.take
pandas.Timestamp.fromtimestamp

[MarcoGorelli]

the exact output here depends on your tz's local time

In [1]: pd.Timestamp.fromtimestamp(1584199972)
Out[1]: Timestamp('2020-03-14 15:32:52')

In [2]: import os

In [3]: os.environ['TZ'] = 'Europe/Brussels'

In [4]: import time

In [5]: time.tzset()

In [6]: pd.Timestamp.fromtimestamp(1584199972)
Out[6]: Timestamp('2020-03-14 16:32:52')

I think this can probably be just removed directly from ci/code_checks.sh (I presume CI runs in UTC?), or could just doctest skip it

[natmokval]

Thank you, it was my mistake. I had to read the next line 1457.
I guess CI runs in UTC, because I get a one-hour difference running validation locally.

Can we leave pandas.Timestamp.fromtimestamp in ci/code_checks.sh to ignore this function while validating docstrings and use the original example for UTC?

[MarcoGorelli]

ideally we shoudn't have the excludes list in ci/code_checks.sh, the objective is to remove that - I think if you add # doctest skip (something like that, check other docstrings for the exact syntax) just to this doctest, and keep it removed from ci/code_checks, that should be enough

[natmokval]

Thank you. I did as you suggested and updated the PR.

[MarcoGorelli]

should be good, thanks - if you resolve the conflicts we can get this in

[MarcoGorelli]

is this intentional? looks like you're adding pandas.Series.sparse.sp_values to the ignore list - perhaps something didn't go quite right when merging?

[natmokval]

It wasn't intentional. I am not very familiar with resolving merge conflicts.

While I was working on the PR the functions pandas.Series.sparse.density, pandas.Series.sparse.npoints, pandas.Series.sparse.sp_values were in the ignore list. I deleted these functions from the ignore list in my next PR, which has been merged just a couple of hours ago. To resolve the conflict I have to delete these functions now.

I can do it locally and push a new commit. What do you think?

[MarcoGorelli]

sounds good, thanks!

[MarcoGorelli]

thanks for updating - could you run this test locally and check it passes please?

=================================== FAILURES ===================================
________________ test_nat_doc_strings[Timestamp.fromtimestamp] _________________
[gw0] linux -- Python 3.8.16 /home/runner/micromamba/envs/test/bin/python3.8

compare = (<class 'pandas._libs.tslibs.timestamps.Timestamp'>, 'fromtimestamp')

    @pytest.mark.parametrize(
        "compare",
        (
            _get_overlap_public_nat_methods(Timestamp, True)
            + _get_overlap_public_nat_methods(Timedelta, True)
        ),
        ids=lambda x: f"{x[0].__name__}.{x[1]}",
    )
    def test_nat_doc_strings(compare):
        # see gh-17327
        #
        # The docstrings for overlapping methods should match.
        klass, method = compare
        klass_doc = getattr(klass, method).__doc__
    
        # Ignore differences with Timestamp.isoformat() as they're intentional
        if klass == Timestamp and method == "isoformat":
            return
    
        if method == "to_numpy":
            # GH#44460 can return either dt64 or td64 depending on dtype,
            #  different docstring is intentional
            return
    
        nat_doc = getattr(NaT, method).__doc__
>       assert klass_doc == nat_doc
E       AssertionError: assert '\n        Ti...me.\n        ' == '\n        Ti...me.\n        '
E         Skipping 188 identical leading characters in diff, use -v to show
E         - 584199972)
E         + 584199972)  # doctest: +SKIP
E                   Timestamp('2020-03-14 15:32:52')
E           
E                   Note that the output may change depending on your local time.

pandas/tests/scalar/test_nat.py:325: AssertionError

[natmokval]

I've got 1 failure.

=================================================================================== FAILURES ====================================================================================
_________________________________________________________________ test_nat_doc_strings[Timestamp.fromtimestamp] _________________________________________________________________

compare = (<class 'pandas._libs.tslibs.timestamps.Timestamp'>, 'fromtimestamp')

    @pytest.mark.parametrize(
        "compare",
        (
            _get_overlap_public_nat_methods(Timestamp, True)
            + _get_overlap_public_nat_methods(Timedelta, True)
        ),
        ids=lambda x: f"{x[0].__name__}.{x[1]}",
    )
    def test_nat_doc_strings(compare):
        # see gh-17327
        #
        # The docstrings for overlapping methods should match.
        klass, method = compare
        klass_doc = getattr(klass, method).__doc__
    
        # Ignore differences with Timestamp.isoformat() as they're intentional
        if klass == Timestamp and method == "isoformat":
            return
    
        if method == "to_numpy":
            # GH#44460 can return either dt64 or td64 depending on dtype,
            #  different docstring is intentional
            return
    
        nat_doc = getattr(NaT, method).__doc__
>       assert klass_doc == nat_doc
E       AssertionError: assert '\n        Ti...me.\n        ' == '\n        Ti...me.\n        '
E         Skipping 188 identical leading characters in diff, use -v to show
E         - 584199972)
E         + 584199972)  # doctest: +SKIP
E                   Timestamp('2020-03-14 15:32:52')
E           
E                   Note that the output may change depending on your local time.

pandas/tests/scalar/test_nat.py:325: AssertionError

[MarcoGorelli]

yeah I think you just need to make the same change to the docstring in pandas/_libs/tslibs/nattype.pyx

[natmokval]

yeah I think you just need to make the same change to the docstring in pandas/_libs/tslibs/nattype.pyx

Thank you, I added the change in pandas/_libs/tslibs/nattype.pyx

[MarcoGorelli]

🤔 CI keeps failing with ci/code_checks.sh: Permission denied, which I've not seen on other jobs. Restarting / merging didn't help. Not sure what to do here

Do you feel like trying to reset to upstream/main and then push the same changes to a new branch and opening a new pull request? No idea if that'll fix it, but I don't know what else to try here

[natmokval]

🤔 CI keeps failing with ci/code_checks.sh: Permission denied, which I've not seen on other jobs. Restarting / merging didn't help. Not sure what to do here

Yes, I noticed that too and I have no clue what is the reason.

Do you feel like trying to reset to upstream/main and then push the same changes to a new branch and opening a new pull request? No idea if that'll fix it, but I don't know what else to try here

I agree it might be the best way to deal with the situation. I will push the same changes to a new branch and open a new PR.

[mroeschke]

Did you run chmod on ci/code_checks.sh @natmokval? It looks like the file permissions changed 100755 → 100644

Looks like it was originally 755

chmod 755 ci/code_checks.sh

[MarcoGorelli]

looks like we did this one in #51453, so we can close this PR