Proposal of an improvement in documentation.
Hii, It's nice reading python documentation which is free and open-source, helping most of the people out there to expedite their tasks with such ease. I find that for every method parameters, we are keeping optional parameters inside square brackets. But in the two cases below, I see it differently. Shouldn't here also the sep and maxsplit parameters be inside square brackets. https://docs.python.org/3/library/stdtypes.html#str.split https://docs.python.org/3/library/stdtypes.html#str.rsplit like, str.split([*sep=None[*, *maxsplit=- 1]]*)¶ <https://docs.python.org/3/library/stdtypes.html#str.split> str.rsplit([*sep=None[*, *maxsplit=- 1]]*)¶ <https://docs.python.org/3/library/stdtypes.html#str.rsplit> Let me know if I am missing something. Thanks and regards, Naveen
Hi, I believe there is indeed a slight issue. However, I fear it is not the one you suggested. All examples I see in the pages you linked, key word arguments do not uses square brackets. Square brackets are used to indicate optional arguments which can not be called with a keyword. For example
str.rstrip([chars])
can be call with " an example\t".strip() or " an example\t".strip('\t') but it can't be called with " an example\t".strip(chars='\t') indeed, if you try, you get the error message:
TypeError: strip() takes no keyword arguments
Admittedly, this can be confusing, and I do not know how anyone reading stdlib documentation can understand it if they don't already know Python enough to know the difference between args, kwargs and why that matters. The biggest issue in my mind is that I see no way to properly improve this documentation; even if you explained in some place why some functions uses square bracket and some other don't, it would be hard to find (actually, I suspect it's explained somewhere; I've no idea where) Regards, Arthur On 02.12.21 07:52, naveensai moyya wrote:
Hi, I believe there is indeed a slight issue. However, I fear it is not the one you suggested. All examples I see in the pages you linked, key word arguments do not uses square brackets. Square brackets are used to indicate optional arguments which can not be called with a keyword. For example
str.rstrip([chars])
can be call with " an example\t".strip() or " an example\t".strip('\t') but it can't be called with " an example\t".strip(chars='\t') indeed, if you try, you get the error message:
TypeError: strip() takes no keyword arguments
Admittedly, this can be confusing, and I do not know how anyone reading stdlib documentation can understand it if they don't already know Python enough to know the difference between args, kwargs and why that matters. The biggest issue in my mind is that I see no way to properly improve this documentation; even if you explained in some place why some functions uses square bracket and some other don't, it would be hard to find (actually, I suspect it's explained somewhere; I've no idea where) Regards, Arthur On 02.12.21 07:52, naveensai moyya wrote:
participants (2)
-
Arthur Milchior -
naveensai moyya