DOC: fix docstring validation errors for pandas.Series #59592

natmokval · 2024-08-24T09:41:47Z

follow up on issues #56804, #59458 and #58063
pandas has a script for validating docstrings:

Lines 155 to 187 in 0cdc6a4

    
           -i "pandas.Series.sparse.fill_value SA01" \ 
        
           -i "pandas.Series.sparse.from_coo PR07,SA01" \ 
        
           -i "pandas.Series.sparse.npoints SA01" \ 
        
           -i "pandas.Series.sparse.sp_values SA01" \ 
        
           -i "pandas.Series.sparse.to_coo PR07,RT03,SA01" \ 
        
           -i "pandas.Series.std PR01,RT03,SA01" \ 
        
           -i "pandas.Series.str.capitalize RT03" \ 
        
           -i "pandas.Series.str.casefold RT03" \ 
        
           -i "pandas.Series.str.center RT03,SA01" \ 
        
           -i "pandas.Series.str.decode PR07,RT03,SA01" \ 
        
           -i "pandas.Series.str.encode PR07,RT03,SA01" \ 
        
           -i "pandas.Series.str.index RT03" \ 
        
           -i "pandas.Series.str.ljust RT03,SA01" \ 
        
           -i "pandas.Series.str.lower RT03" \ 
        
           -i "pandas.Series.str.lstrip RT03" \ 
        
           -i "pandas.Series.str.match RT03" \ 
        
           -i "pandas.Series.str.normalize RT03,SA01" \ 
        
           -i "pandas.Series.str.partition RT03" \ 
        
           -i "pandas.Series.str.repeat SA01" \ 
        
           -i "pandas.Series.str.replace SA01" \ 
        
           -i "pandas.Series.str.rindex RT03" \ 
        
           -i "pandas.Series.str.rjust RT03,SA01" \ 
        
           -i "pandas.Series.str.rpartition RT03" \ 
        
           -i "pandas.Series.str.rstrip RT03" \ 
        
           -i "pandas.Series.str.strip RT03" \ 
        
           -i "pandas.Series.str.swapcase RT03" \ 
        
           -i "pandas.Series.str.title RT03" \ 
        
           -i "pandas.Series.str.upper RT03" \ 
        
           -i "pandas.Series.str.wrap RT03,SA01" \ 
        
           -i "pandas.Series.str.zfill RT03" \ 
        
           -i "pandas.Series.struct.dtypes SA01" \ 
        
           -i "pandas.Series.to_markdown SA01" \ 
        
           -i "pandas.Series.update PR07,SA01" \

Currently, some methods fail docstring validation check.
The task here is:

take 2-4 methods
run: scripts/validate_docstrings.py <method-name>
fix the docstrings according to whatever error is reported
remove those methods from code_checks.sh script
commit, push, open pull request

Example:

scripts/validate_docstrings.py pandas.Series.prod

pandas.Series.prod fails with the ES01 and RT03 errors

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

2 Errors found for `pandas.Series.prod`:
        ES01    No extended summary found
        RT03    Return value has no description

Please don't comment take as multiple people can work on this issue. You also don't need to ask for permission to work on this, just comment on which methods are you going to work.

If you're new contributor, please check the contributing guide

The text was updated successfully, but these errors were encountered:

ivonastojanovic · 2024-08-24T12:54:55Z

I'll take these:

 -i "pandas.Series.sparse.fill_value SA01" \ 
 -i "pandas.Series.sparse.from_coo PR07,SA01" \ 
 -i "pandas.Series.sparse.npoints SA01" \ 
 -i "pandas.Series.sparse.sp_values SA01" \ 
 -i "pandas.Series.sparse.to_coo PR07,RT03,SA01" \

wenchen-cai · 2024-08-24T17:00:19Z

I'll take these:

 -i "pandas.Series.str.wrap RT03,SA01" \ 
 -i "pandas.Series.str.zfill RT03" \

ivonastojanovic · 2024-08-24T17:03:27Z

Working on these:

 -i "pandas.Series.str.match RT03" \ 
 -i "pandas.Series.str.normalize RT03,SA01" \ 
 -i "pandas.Series.str.repeat SA01" \ 
 -i "pandas.Series.str.replace SA01" \

githubalexliu · 2024-08-25T03:30:19Z

I'll take these:

-i "pandas.Series.struct.dtypes SA01" \ 
-i "pandas.Series.to_markdown SA01" \

hlakams · 2024-08-25T11:24:05Z

Here's a filtered list of pandas.Series docstring issues that still need to be addressed:

        ...
        -i "pandas.Series.dt.as_unit PR01,PR02" \
        ...
        -i "pandas.Series.dt.round PR01,PR02" \
        ...
        -i "pandas.Series.dt.unit GL08" \
        ...
        -i "pandas.Series.pad PR01,SA01" \
        ...

I went ahead and removed methods that were already claimed/addressed by open + merged PRs.
(Last updated 9/2/2024)

hlakams · 2024-08-25T12:52:54Z

I'll take these:

 -i "pandas.Series.pop SA01" \
 -i "pandas.Series.list.__getitem__ SA01" \
 -i "pandas.Series.list.flatten SA01" \
 -i "pandas.Series.list.len SA01" \
 -i "pandas.Series.reorder_levels RT03,SA01" \
 -i "pandas.Series.sparse.density SA01" \
 -i "pandas.Series.gt SA01" \
 -i "pandas.Series.lt SA01" \
 -i "pandas.Series.ne SA01" \
 -i "pandas.Series.prod RT03" \
 -i "pandas.Series.product RT03" \

Pranav-Wadhwa · 2024-08-26T21:06:17Z

I will take

-i "pandas.Series.dt.strftime PR01,PR02" \
        -i "pandas.Series.dt.to_period PR01,PR02" \
        -i "pandas.Series.dt.total_seconds PR01" \
        -i "pandas.Series.dt.tz_convert PR01,PR02" \
        -i "pandas.Series.dt.tz_localize PR01,PR02" \
        -i "pandas.Series.dt.unit GL08" \

james-magee · 2024-08-27T02:22:41Z

I'll take

 -i "pandas.Series.std PR01,RT03,SA01" \ 
 -i "pandas.Series.sem PR01,RT03,SA01" \

Tmthang1601 · 2024-08-27T08:52:32Z

I followed the instructions and encountered this issue: I added 'See Also' to the function fill_value(self) in ./pandas/core/arrays/sparse/array.py. After running the command python3 scripts/validate_docstrings.py pandas.Series.sparse.fill_value, I received the message:

thang123456@MSI:/mnt/c/Users/ADMIN/Desktop/pandas/pandas$ python3 scripts/validate_docstrings.py pandas.Series.sparse.fill_value

################################################################################
################# Docstring (pandas.Series.sparse.fill_value) #################
################################################################################

Elements in data that are fill_value are not stored.

For memory savings, this should be the most common value in the array.

Examples

ser = pd.Series([0, 0, 2, 2, 2], dtype="Sparse[int]")
ser.sparse.fill_value
0
spa_dtype = pd.SparseDtype(dtype=np.int32, fill_value=2)
ser = pd.Series([0, 0, 2, 2, 2], dtype=spa_dtype)
ser.sparse.fill_value
2

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

1 Errors found for pandas.Series.sparse.fill_value:
SA01 See Also section not found
I checked very carefully but still couldn't fix the error. Can someone help me understand what is going wrong?

Gesare5 · 2024-08-27T18:14:49Z

I will take:

-i "pandas.Series.dt.floor PR01,PR02" \
-i "pandas.Series.dt.ceil PR01,PR02" \

pol-rius · 2024-08-27T21:30:33Z

I'll take these:

-i "pandas.Series.sparse PR01,SA01" \
-i "pandas.Series.sparse.to_coo PR07,RT03,SA01" \

githubalexliu · 2024-08-27T22:15:01Z

I'll take these:

-i "pandas.Series.dt.normalize PR01" \
-i "pandas.Series.dt.qyear GL08" \

hlakams · 2024-08-28T00:59:11Z

@Tmthang1601 The pandas prefix is not needed for SparseDtype and SparseArray. Remove that prefix and the validation command should pass.

See Also
--------
SparseDtype : Dtype for sparse array.
SparseArray : Array of sparse data.

Tmthang1601 · 2024-08-28T01:16:12Z

@Tmthang1601 The pandas prefix is not needed for SparseDtype and SparseArray. Remove that prefix and the validation command should pass.
See Also
--------
SparseDtype : Dtype for sparse array.
SparseArray : Array of sparse data.

@hlakams
Originally there was no line "See Also

SparseDtype : Dtype for sparse array.
SparseArray : Array of sparse data." in the String Docs of the def fill_value function, I added it by mistake for the purpose of no more errors, I didn't think after I removed it it would go away, and I tried, of course it didn't go away

hlakams · 2024-08-28T01:21:50Z

@Tmthang1601 Can you push up your changes in a new PR?

Tmthang1601 · 2024-08-28T01:41:10Z

@hlakams According to the instructions, you need to complete 2 to 4 methods and run the script successfully before pushing to a new PR, but I'm having trouble.

hlakams · 2024-08-28T02:36:47Z

@Tmthang1601 I'm not sure what the issue is, but try replacing lines 620:639 from #59592 (comment) with the following docstring:

        """
        Elements in `data` that are `fill_value` are not stored.

        For memory savings, this should be the most common value in the array.

        See Also
        --------
        SparseDtype : Dtype for sparse array.
        SparseArray : Array of sparse data.

        Examples
        --------
        >>> ser = pd.Series([0, 0, 2, 2, 2], dtype="Sparse[int]")
        >>> ser.sparse.fill_value
        0
        >>> spa_dtype = pd.SparseDtype(dtype=np.int32, fill_value=2)
        >>> ser = pd.Series([0, 0, 2, 2, 2], dtype=spa_dtype)
        >>> ser.sparse.fill_value
        2
        """

Run pre-commit once this change from #59592 (comment) is committed (assuming it was configured correctly) + address possible lint errors and you should be able to push up to your fork.

yinglyu · 2024-09-03T03:52:37Z

I will take these:

        -i "pandas.Series.dt.day_name PR01,PR02" \
        -i "pandas.Series.dt.month_name PR01,PR02" \

doshi-kevin · 2024-09-03T18:40:53Z

I will take this -
-i "pandas.Series.update PR07,SA01" \

blackhole-hoop · 2024-09-06T19:05:30Z

I'll work on this:

-i "pandas.Series.str.swapcase RT03" \

chalky25 · 2024-09-06T19:37:38Z

I'll work on these:
-i "pandas.Series.dt.nanoseconds SA01" \\
-i "pandas.Series.dt.seconds SA01"

chalky25 · 2024-09-06T19:38:49Z

I'll work on this:

-i "pandas.Series.str.swapcase RT03" \

it seems that pandas.Series.str.swapcase has already been done.

blackhole-hoop · 2024-09-06T20:22:08Z

Sorry, I am a first time contributor. May I know how to check whether something is done or not? I searched for the keyword "swapcase" on this page and didn't see anyone was working on this. @chalky25

ammar-qazi · 2024-09-06T21:56:48Z

Welcome to contributing, @blackhole-hoop. I also started three days ago.

I'm also not sure who fixed it or how it got fixed — because none of the merged commits mention it.

That said, I just tested it using the following command:

scripts/validate_docstrings.py pandas.Series.str.swapcase

And, I got the following in the result.


################################################################################
#################### Docstring (pandas.Series.str.swapcase) ####################
################################################################################

Convert strings in the Series/Index to be swapcased.

Equivalent to :meth:`str.swapcase`.

Returns
-------
Series or Index of objects
    A Series or Index where the strings are modified by :meth:`str.swapcase`.

See Also
--------
Series.str.lower : Converts all characters to lowercase.
Series.str.upper : Converts all characters to uppercase.
Series.str.title : Converts first character of each word to uppercase and
    remaining to lowercase.
Series.str.capitalize : Converts first character to uppercase and
    remaining to lowercase.
Series.str.swapcase : Converts uppercase to lowercase and lowercase to
    uppercase.
Series.str.casefold: Removes all case distinctions in the string.

Examples
--------
>>> s = pd.Series(['lower', 'CAPITALS', 'this is a sentence', 'SwApCaSe'])
>>> s
0                 lower
1              CAPITALS
2    this is a sentence
3              SwApCaSe
dtype: object

>>> s.str.lower()
0                 lower
1              capitals
2    this is a sentence
3              swapcase
dtype: object

>>> s.str.upper()
0                 LOWER
1              CAPITALS
2    THIS IS A SENTENCE
3              SWAPCASE
dtype: object

>>> s.str.title()
0                 Lower
1              Capitals
2    This Is A Sentence
3              Swapcase
dtype: object

>>> s.str.capitalize()
0                 Lower
1              Capitals
2    This is a sentence
3              Swapcase
dtype: object

>>> s.str.swapcase()
0                 LOWER
1              capitals
2    THIS IS A SENTENCE
3              sWaPcAsE
dtype: object

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

Docstring for "pandas.Series.str.swapcase" correct. :)

In other words, you use the script given by the original poster to check the docstring.

pratik305 · 2024-09-13T04:45:38Z

i will work on this

"pandas.Series.str.lower RT03" \
"pandas.Series.str.center RT03,SA01" \
"pandas.Series.str.title RT03" \
"pandas.Series.str.lstrip RT03" \

pratik305 · 2024-09-13T07:02:24Z

i started contributing found some are already solve without mentioning.
I try to run some code that already merge they also showing error like
python scripts/validate_docstrings.py pandas.Series.str.swapcase

Result

################################################################################
#################### Docstring (pandas.Series.str.swapcase) ####################
################################################################################

Convert strings in the Series/Index to be swapcased.

Equivalent to :meth:`str.swapcase`.

Returns
-------
Series or Index of object

See Also
--------
Series.str.lower : Converts all characters to lowercase.
Series.str.upper : Converts all characters to uppercase.
Series.str.title : Converts first character of each word to uppercase and
    remaining to lowercase.
Series.str.capitalize : Converts first character to uppercase and
    remaining to lowercase.
Series.str.swapcase : Converts uppercase to lowercase and lowercase to
    uppercase.
Series.str.casefold: Removes all case distinctions in the string.

Examples
--------
>>> s = pd.Series(['lower', 'CAPITALS', 'this is a sentence', 'SwApCaSe'])
>>> s
0                 lower
1              CAPITALS
2    this is a sentence
3              SwApCaSe
dtype: object

>>> s.str.lower()
0                 lower
1              capitals
2    this is a sentence
3              swapcase
dtype: object

>>> s.str.upper()
0                 LOWER
1              CAPITALS
2    THIS IS A SENTENCE
3              SWAPCASE
dtype: object

>>> s.str.title()
0                 Lower
1              Capitals
2    This Is A Sentence
3              Swapcase
dtype: object

>>> s.str.capitalize()
0                 Lower
1              Capitals
2    This is a sentence
3              Swapcase
dtype: object

>>> s.str.swapcase()
0                 LOWER
1              capitals
2    THIS IS A SENTENCE
3              sWaPcAsE
dtype: object

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

1 Errors found for `pandas.Series.str.swapcase`:
        RT03    Return value has no description

and in code.sh file there is no pandas.String.str. related code line
is all str related doc fixed

Pekka20123 · 2024-09-17T17:17:07Z

I'll take these:

 -i "pandas.Series.str.rjust RT03,SA01" \ 
 -i "pandas.Series.str.rpartition RT03" \ 
 -i "pandas.Series.str.rstrip RT03" \

Don't know exactly .that does this work this the first time. I am contributing. Sorry for the mistake

syeda-fajar · 2024-09-22T12:57:55Z

I want to work on these issues:

-i "pandas.Series.sparse.sp_values SA01,ES01" \
-i "pandas.Series.str.match ES01" \

dhelms33 · 2024-09-26T00:11:39Z

Hello! I am new to the pandas community. It seems like most of these are already taken. Is there any way to filter which methods have been run already?

techie505 · 2024-10-22T05:15:23Z

/Assign

dylanpanton · 2024-11-10T15:02:20Z

Hi! I will take these:
-i "pandas.core.groupby.DataFrameGroupBy.nth PR02" \
-i "pandas.core.groupby.SeriesGroupBy.nth PR02" \

Ivruix · 2024-11-20T14:30:03Z

Seems that most of these were fixed. Working on this one:

-i "pandas.Series.dt.freq GL08" \

OscarGB · 2024-12-03T16:34:12Z

I'll take:

    -i "pandas.Series.dt.unit GL08" \
    -i "pandas.Series.pad PR01,SA01" \

#60481

karnbirrandhawa · 2024-12-06T23:34:55Z

I'll take

-i "pandas.arrays.NumpyExtensionArray SA01" \

Ishancorp · 2024-12-19T04:22:58Z

I'll take

-i "pandas.Series.str.rindex RT03" \

dajale423 · 2024-12-20T07:32:22Z

I'll take

-i "pandas.Series.str.strip RT03" \

natmokval added Docs Code Style Code style, linting, code_checks good first issue labels Aug 24, 2024

ivonastojanovic mentioned this issue Aug 24, 2024

DOCS: fix docstring validation errors for pandas.Series #59595

Closed

ivonastojanovic mentioned this issue Aug 24, 2024

DOCS: fix docstring validation errors for pandas.Series #59596

Merged

wenchen-cai mentioned this issue Aug 24, 2024

DOCS: fix docstring validation errors for pandas.Series.str #59597

Merged

githubalexliu mentioned this issue Aug 25, 2024

DOCS: fix docstring validation errors for pandas.Series #59600

Merged

This was referenced Aug 25, 2024

DOCS: fix docstring validation errors for pandas.Series #59602

Merged

DOC: fix docstring validation errors for pandas.io.formats.style.Styler #59606

Closed

specialkapa mentioned this issue Aug 26, 2024

Doc/59592/fix docstring validation errors #59611

Merged

james-magee mentioned this issue Aug 27, 2024

DOC: fix docstring validation errors for pandas.Series #59621

Merged

pol-rius mentioned this issue Aug 27, 2024

DOC: fix docstring validation errors for pandas.Series #59633

Merged

githubalexliu mentioned this issue Aug 30, 2024

DOCS: fix docstring validation error for pandas.Series #59655

Closed

saldanhad mentioned this issue Sep 12, 2024

DOC: Questions on Usage of *args, **kwargs, and inplace parameters in pandas.Series.cat methods #59783

Closed

1 task

Pranav-Wadhwa mentioned this issue Sep 13, 2024

Fix doc errors for various datetime functions #59791

Closed

1 task

jyotirjoshi added a commit to jyotirjoshi/pandas that referenced this issue Sep 21, 2024

Fixed pandas-dev#59592

79cec21

Don't know exactly .that does this work this the first time. I am contributing. Sorry for the mistake

syeda-fajar mentioned this issue Sep 22, 2024

Fix Docstring Issues for pandas.Series.sparse.sp_values and pandas.Series.str.match (Issue #59592) #59873

Closed

5 tasks

saldanhad mentioned this issue Sep 24, 2024

DOC: Refactor _create_delegator_method using functools #59878

Merged

Pranav-Wadhwa mentioned this issue Oct 11, 2024

Fix doc errors for various datetime functions #60022

Closed

1 task

Ivruix mentioned this issue Nov 20, 2024

DOC: fix docstring validation errors for pandas.Series.dt.freq #60377

Merged

OscarGB mentioned this issue Dec 3, 2024

DOC: Fix some docstring validations in pd.Series #60481

Merged

knowltod mentioned this issue Dec 6, 2024

DOC: Fix some core.resample.Resampler docstrings #60502

Open

karnbirrandhawa mentioned this issue Dec 7, 2024

DOC: fix docstring validation errors for pandas.arrays #60511

Closed

DOC: fix docstring validation errors for pandas.Series #59592

DOC: fix docstring validation errors for pandas.Series #59592

Comments

natmokval commented Aug 24, 2024 • edited Loading

ivonastojanovic commented Aug 24, 2024 • edited Loading

wenchen-cai commented Aug 24, 2024 • edited Loading

ivonastojanovic commented Aug 24, 2024

githubalexliu commented Aug 25, 2024 • edited Loading

hlakams commented Aug 25, 2024 • edited Loading

hlakams commented Aug 25, 2024 • edited Loading

Pranav-Wadhwa commented Aug 26, 2024

james-magee commented Aug 27, 2024

Tmthang1601 commented Aug 27, 2024 • edited Loading

Examples

Gesare5 commented Aug 27, 2024 • edited Loading

pol-rius commented Aug 27, 2024

githubalexliu commented Aug 27, 2024

hlakams commented Aug 28, 2024

Tmthang1601 commented Aug 28, 2024 • edited Loading

@hlakams Originally there was no line "See Also

hlakams commented Aug 28, 2024

Tmthang1601 commented Aug 28, 2024

hlakams commented Aug 28, 2024

yinglyu commented Sep 3, 2024

doshi-kevin commented Sep 3, 2024

blackhole-hoop commented Sep 6, 2024

chalky25 commented Sep 6, 2024 • edited Loading

chalky25 commented Sep 6, 2024

blackhole-hoop commented Sep 6, 2024

ammar-qazi commented Sep 6, 2024

pratik305 commented Sep 13, 2024

pratik305 commented Sep 13, 2024

Pekka20123 commented Sep 17, 2024 • edited Loading

syeda-fajar commented Sep 22, 2024

dhelms33 commented Sep 26, 2024

techie505 commented Oct 22, 2024

dylanpanton commented Nov 10, 2024 • edited Loading

Ivruix commented Nov 20, 2024

OscarGB commented Dec 3, 2024 • edited Loading

karnbirrandhawa commented Dec 6, 2024

Ishancorp commented Dec 19, 2024

dajale423 commented Dec 20, 2024

natmokval commented Aug 24, 2024 •

edited

Loading

ivonastojanovic commented Aug 24, 2024 •

edited

Loading

wenchen-cai commented Aug 24, 2024 •

edited

Loading

githubalexliu commented Aug 25, 2024 •

edited

Loading

hlakams commented Aug 25, 2024 •

edited

Loading

hlakams commented Aug 25, 2024 •

edited

Loading

Tmthang1601 commented Aug 27, 2024 •

edited

Loading

Gesare5 commented Aug 27, 2024 •

edited

Loading

Tmthang1601 commented Aug 28, 2024 •

edited

Loading

@hlakams
Originally there was no line "See Also

chalky25 commented Sep 6, 2024 •

edited

Loading

Pekka20123 commented Sep 17, 2024 •

edited

Loading

dylanpanton commented Nov 10, 2024 •

edited

Loading

OscarGB commented Dec 3, 2024 •

edited

Loading