Skip to content

DOC: Fix doc for first_valid_index #55236

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

Merged
merged 7 commits into from
Sep 22, 2023
Merged

DOC: Fix doc for first_valid_index #55236

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
828df86
Fix doc for first_valid_index
jfadia Sep 22, 2023
ce57be1
Merge branch 'main' into doc-55187-first-valid-index
jfadia Sep 22, 2023
a454340
Merge branch 'main' into doc-55187-first-valid-index
jfadia Sep 22, 2023
5c551ff
Merge branch 'main' into doc-55187-first-valid-index
jfadia Sep 22, 2023
f0c83dd
Replace notes with examples
jfadia Sep 22, 2023
99cd958
Merge branch 'main' into doc-55187-first-valid-index
jfadia Sep 22, 2023
2d13c97
Add explicit prints
jfadia Sep 22, 2023
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
46 changes: 41 additions & 5 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12466,11 +12466,6 @@ def first_valid_index(self) -> Hashable | None:
-------
type of index
Notes
-----
If all elements are non-NA/null, returns None.
Copy link
Member

Choose a reason for hiding this comment

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

Could you just remove this Notes section and demonstrate these points in the Examples section below?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done. One thing I was unsure of was how to handle returning None in the docs:

  • I ran it through the docstring validation script python scripts/validate_docstrings.py pandas.core.generic.NDFrame.first_valid_index
  • It was throwing errors about the output not matching the expected output because I had originally specified:
        >>> s = pd.Series()
        >>> s.first_valid_index()
        None
        >>> s.last_valid_index()
        None

I considered printing the outputs so that the outputs would match but didn't see print statements used in that way in other parts of the code so I did not keep them. Let me know if printing is the way to go here and I can make the change :)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

To clarify, option 1:

>>> s = pd.Series()
>>> s.first_valid_index()
>>> s.last_valid_index()

Option 2:

>>> s = pd.Series()
>>> print(s.first_valid_index())
None
>>> print(s.last_valid_index())
None

Copy link
Member

Choose a reason for hiding this comment

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

Option 2 would be fine to make it explicit in the docs

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Added the print statements

Also returns None for empty {klass}.
Examples
--------
For Series:
Expand All @@ -12481,6 +12476,22 @@ def first_valid_index(self) -> Hashable | None:
>>> s.last_valid_index()
2
>>> s = pd.Series([None, None])
>>> print(s.first_valid_index())
None
>>> print(s.last_valid_index())
None
If all elements in Series are NA/null, returns None.
>>> s = pd.Series()
>>> print(s.first_valid_index())
None
>>> print(s.last_valid_index())
None
If Series is empty, returns None.
For DataFrame:
>>> df = pd.DataFrame({{'A': [None, None, 2], 'B': [None, 3, 4]}})
Expand All @@ -12493,6 +12504,31 @@ def first_valid_index(self) -> Hashable | None:
1
>>> df.last_valid_index()
2
>>> df = pd.DataFrame({{'A': [None, None, None], 'B': [None, None, None]}})
>>> df
A B
0 None None
1 None None
2 None None
>>> print(df.first_valid_index())
None
>>> print(df.last_valid_index())
None
If all elements in DataFrame are NA/null, returns None.
>>> df = pd.DataFrame()
>>> df
Empty DataFrame
Columns: []
Index: []
>>> print(df.first_valid_index())
None
>>> print(df.last_valid_index())
None
If DataFrame is empty, returns None.
"""
return self._find_valid_index(how="first")

Expand Down