Skip to content

DOC: Update series apply docstring. GH22459 #22510

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 6 commits into from
Nov 24, 2018
Merged

DOC: Update series apply docstring. GH22459 #22510

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9b17810
DOC: Updated Series.apply docstring. GH22459
eldritchideen Aug 26, 2018
817379f
DOC: Updated wording.
eldritchideen Aug 26, 2018
5baa4fd
DOC: Removed type from **kwds parameter.
eldritchideen Aug 28, 2018
d07650f
DOC: Updated Series.apply docstring based on review feedback.
eldritchideen Sep 4, 2018
0eb4e8c
DOC: Removed trailing whitespace.
eldritchideen Sep 4, 2018
d5c13b2
Merging from master, and last comments from review addressed
datapythonista Nov 24, 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
14 changes: 7 additions & 7 deletions pandas/core/series.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3104,17 +3104,19 @@ def apply(self, func, convert_dtype=True, args=(), **kwds):
"""
Invoke function on values of Series. Can be ufunc (a NumPy function
that applies to the entire Series) or a Python function that only works
on single values
on single values.
Copy link
Member

Choose a reason for hiding this comment

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

Can you have a single line description first, and the rest later. You have the documentation about this here:
https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html

If you run ./scripts/validate_docstrings.py pandas.Series.apply should report an error about it.


Parameters
----------
func : function
convert_dtype : boolean, default True
Python function or NumPy ufunc.
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 can say "Python function or NumPy ufunc to apply."?

convert_dtype : bool, default True
Try to find better dtype for elementwise function results. If
False, leave as dtype=object
False, leave as dtype=object.
args : tuple
Positional arguments to pass to function in addition to the value
Additional keyword arguments will be passed as keywords to the function
Positional arguments to pass to func in addition to the value.
Copy link
Member

Choose a reason for hiding this comment

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

"in addition to the value" - can we clarify what that means?

**kwds : dict
Copy link
Member

@gfyoung gfyoung Aug 27, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

@datapythonista : I wonder if we should standardize and use **kwargs everywhere.

(@eldritchideen : Don't worry about this comment. This is a larger question beyond this PR for the time being.)

Copy link
Member

Choose a reason for hiding this comment

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

In terms of documentation, the standard we defined was to always document *args and **kwargs if present, showing the stars in the name, but without the type (it'll always be tuple and dict).

Not sure if you mean using kwargs instead of kwds, or which standardization are you proposing here, but I'm +1 on being consistent everywhere.

I see that in this case args needs to be provided as a tuple (not as positional arguments) and kwds needs to be provided as keyword arguments (not as a dict). Not sure if there is a reason for this, but if it's not, I'd be in favor of changing it to be consistent (in a separate PR). @jreback ?

Copy link
Member

Choose a reason for hiding this comment

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

@datapythonista : Indeed, I was referring to using kwargs across the board. I'm also in favor of consistency in general.

Copy link
Member

Choose a reason for hiding this comment

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

That sounds good to me, and afaik it should be a backward compatible change in all cases, so +1 on this. Do you want to create an issue?

Additional keyword arguments passed to func.

Returns
-------
Expand Down Expand Up @@ -3193,8 +3195,6 @@ def apply(self, func, convert_dtype=True, args=(), **kwds):
New York 3.044522
Helsinki 2.484907
dtype: float64


"""
if len(self) == 0:
return self._constructor(dtype=self.dtype,
Expand Down