Fix PR02 issues in docstrings #27976
Comments
|
I made a pull request #28340 to solve "pandas.Series.astype: Unknown parameters {kwargs}". |
|
I made a PR to fix pandas.Series.clip: Unknown parameters {*args, **kwargs}. |
|
I've been working on this today, and it seems some of this is being caused by decorators. For instance, in strings.py, when the @forbid_nonstring_types decorator is commented out on one of the offending methods, it passes without the error. I've also seen this behavior on the @deprecate_kwarg decorator. I'm not sure what the fix should be yet, I'd have to look into it a bit more. |
|
Hi @Nabel0721 . I'm interested in knowing what you find. Thanks |
|
@WuraolaOyewusi So, it looks like the function If this is the issue, it would solve some of the errors we have, but likely introduce more as we catch more arguments in other function. |
|
@Nabel0721 . I will be following to learn how this is sorted. Please tag me as you make changes. Have a great day |
|
@WuraolaOyewusi I put together a PR (#28765) that switches the script to use |
* master: (22 commits) DOC: fix PR09,PR08 errors for pandas.Timestamp (pandas-dev#28739) WEB: Add diversity note to team.md (pandas-dev#28630) DOC: Minor fixes in pandas/testing.py docstring. (pandas-dev#28752) TST: port maybe_promote tests from pandas-dev#23982 (pandas-dev#28764) Bugfix/groupby datetime issue (pandas-dev#28569) reenable codecov (pandas-dev#28750) CLN: Centralised _check_percentile (pandas-dev#27584) DEPR: Deprecate Index.set_value (pandas-dev#28621) CLN: Fix typo in contributing.rst (pandas-dev#28761) Fixed docstring errors in pandas.period range and pandas.PeriodIndex (pandas-dev#28756) BUG: Fix TypeError raised in libreduction (pandas-dev#28643) DOC: Pandas.Series.drop docstring PR02 (pandas-dev#27976) (pandas-dev#28742) DOC: Fixed doctring errors PR08, PR09 in pandas.io (pandas-dev#28748) TST: Fix broken test cases where Timedelta/Timestamp raise (pandas-dev#28729) REF: Consolidate alignment calls in DataFrame ops (pandas-dev#28638) BUG: Fix dep generation (pandas-dev#28734) Added doctstring to fixture (pandas-dev#28727) DOC: Fixed PR06 docstrings errors in pandas.timedelta_range (pandas-dev#28719) replaced safe_import with a corresponding test decorator (pandas-dev#28731) BUG: Fix RangeIndex.get_indexer for decreasing RangeIndex (pandas-dev#28680) ...
|
Ok Abel. Thanks for letting me know.
I will look for the PR and continue to see how the whole process works.
…On Fri, 4 Oct 2019, 6:11 PM Nathan Abel, ***@***.***> wrote:
@WuraolaOyewusi <https://github.com/WuraolaOyewusi> I put together a PR
that switches the script to use signature. According to the documentation
for it, signature finds the source function by checking if a function has
the __wrapped__ attribute. If it does, it contains the function that was
wrapped by the current one. This is automatically set by the @wraps
decorator and other similar functions from the functools library. So, if
we're having issues with a decorator overriding the signature of a
function, we need to check if it has the @wraps decorator inside, or if
it's a class-made decorator if it has something like functools.update_wrapper(self,
func). This is only necessary if we need the signature of the underlying
function. For CPython, decorators should probably have the __wrapped__
attribute assigned directly.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#27976?email_source=notifications&email_token=AKDK7XA47MA5TOHPPY77RQ3QM52L7A5CNFSM4IMQON4KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEAMJUCA#issuecomment-538483208>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AKDK7XAUPDI3QQ6RJEFFLWTQM52L7ANCNFSM4IMQON4A>
.
|
|
@datapythonista Also for some random example like pandas.core.window.rolling.Rolling.apply: Unknown parameters {*args, **kwargs} Also as far as I could see most of them have parameters already present when I open the website to look at them. |
|
The link that you're sharing is for an old version of pandas. You should check the latest version at: https://pandas.pydata.org/docs/dev/ There are two parameters for any function: def my_function(actual_parameter):
"""
Does something.
Parameters
----------
unknown_parameter : str
This is unknown, and actual_parameter is missing, there are two incorrect things here.
"""
passSo, an unknown parameter as you can see in the example is a documented parameter that we don't know about, because it's not an actual parameter in the signature of the function. |
|
ohkk understood thanks @datapythonista |
|
@datapythonista Hi, I've checked out @classmethod
def from_spmatrix(cls, data, index=None, columns=None):
"""
Create a new DataFrame from a scipy sparse matrix.
.. versionadded:: 0.25.0
Parameters
----------
data : scipy.sparse.spmatrix
Must be convertible to csc format.
index, columns : Index, optional
Row and column labels to use for the resulting DataFrame.
Defaults to a RangeIndex.
Returns
-------
DataFrame
...
etc
"""Should I assume this is wrong and change it to a separate row for index and columns? Or is this correct and |
|
Ideally we would like to allow document two columns at a time. So, updating the script so |
|
This requirement is mentioned in the extended summary but from the pandas docstring guide,
How should the docstring be modified in this case or is this an issue with the validation script? |
|
Since the signature contains only I think in this case it could make sense to change the signature of the function to something like |
|
take |
|
When a user runs the command python ./scripts/validate_docstrings.py --errors=PR02 in a terminal they are presented with a list of errors with the docstrings for functions, such as what is shown in the errors.txt file (I created). In the errors' list, many errors point to the same line of code, such as /home/pandas/pandas/core/indexes/extension.py:92. However, when you look at the line in the file, line 92 def method(self, *args, **kwargs) it seems to just be defining a function within another wrapper function. Are these errors supposed to be at the same location or should the validate doc-strings only check the wrapper function's doc-string and not the inner function?
|
|
We did our best to point to the docstring, but many docstrings are build in a dynamic way, and it's not possible to know where the actual docstring content is defined. This seems to be the case here, so just ignore that information. You can better use grep with some sentence of the docstring you're looking for to see where it's defined. |
|
hi @datapythonista, should this issue be closed in favor of #58063, which is more up-to-date and clearer instruction about how to fix docstring errors? |
Fix the docstrings where an unknown parameter is documented (likely that they are typos, errors in the parameter format...).
Current errors:
The text was updated successfully, but these errors were encountered: