[issue22725] improve documentation for enumerate() (built-in function)

R. David Murray added the comment: Per Raymond's last message, closing this as rejected. -- assignee: rhettinger -> docs@python stage: needs patch -> resolved ___ Python tracker

[issue22725] improve documentation for enumerate() (built-in function)

Raymond Hettinger added the comment: I'm sorry but I do not like the proposed patch at all. The wording is awkward "which when iterated" and has weird terminology "the sequence number". The OP's concern about the *sequence* versus *iterable* parameter name has been addressed (it is part of th

[issue22725] improve documentation for enumerate() (built-in function)

Georg Brandl added the comment: Missing keyword argument support is not the norm, it's the exception that is only due to implementation details in C code. Eventually, we'd like every C function to support keyword arguments. Converting everything is tedious work, though, and still makes things

[issue22725] improve documentation for enumerate() (built-in function)

Tshepang Lekhonkhobe added the comment: Oh, I see now. The documentation doesn't make it clear. Anyways, what were the advantages of making it a keyword, instead of just a positional argument? -- ___ Python tracker

[issue22725] improve documentation for enumerate() (built-in function)

Changes by Arfrever Frehtes Taifersar Arahesis : -- nosy: +Arfrever ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscri

[issue22725] improve documentation for enumerate() (built-in function)

R. David Murray added the comment: Specifically, this works (in 2.7): >>> enumerate(sequence=myvar) Changing sequence to iterable would break any code that was written like the above. -- ___ Python tracker ___

[issue22725] improve documentation for enumerate() (built-in function)

Raymond Hettinger added the comment: static PyObject * > Why do you say that 'sequence' is a keyword? It is a keyword argument to enumerate(). Here's the relevant section of code: enum_new(PyTypeObject *type, PyObject *args, PyObject *kwds) { enumobject *en; PyObject *seq = NULL; P

[issue22725] improve documentation for enumerate() (built-in function)

Tshepang Lekhonkhobe added the comment: @raymond Why do you say that 'sequence' is a keyword? >>> enumerate() Traceback (most recent call last): File "", line 1, in TypeError: Required argument 'sequence' (pos 1) not found That means that 'sequence' can be changed to 'iterable' without worr

[issue22725] improve documentation for enumerate() (built-in function)

Changes by R. David Murray : Added file: http://bugs.python.org/file37112/enumerate_doc-3.4.patch ___ Python tracker ___ ___ Python-bugs-list

[issue22725] improve documentation for enumerate() (built-in function)

Changes by R. David Murray : -- keywords: +patch Added file: http://bugs.python.org/file37111/enumerate-doc.2.7.patch ___ Python tracker ___ _

[issue22725] improve documentation for enumerate() (built-in function)

Raymond Hettinger added the comment: Can you attach a proposed patch and I will make a decision. FWIW, I'm very happy with the current documentation at https://docs.python.org/2.7/library/functions.html#enumerate Between the text, example, and pure python equivalent, it does a great job com

[issue22725] improve documentation for enumerate() (built-in function)

R. David Murray added the comment: We have a suggestion for a wording improvement (that does not change the sentence to which you refer) that has been accepted as better than the existing wording by a couple of committers. This improvement is actually independent of what the variable is named

[issue22725] improve documentation for enumerate() (built-in function)

Raymond Hettinger added the comment: The "sequence" parameter name is an unfortunate hold-over from olden times were many things that accepted iterables were marked as taking sequences. This was fixed in Python 3, but it can't be changed in Py2.7 because the parameter name is exposed as a keyw

[issue22725] improve documentation for enumerate() (built-in function)

Terry J. Reedy added the comment: The first argument of enumerate is 'iterable' in the 2.7 docstring also. "enumerate(iterable[, start]) -> iterator for index, value of iterable Return an enumerate object. iterable must be another object that supportsniteration. The enumerate object yields p

[issue22725] improve documentation for enumerate() (built-in function)

Georg Brandl added the comment: rdm: your suggestion sounds good. Note that the argument name is "iterable" in Py3. -- ___ Python tracker ___ ___

[issue22725] improve documentation for enumerate() (built-in function)

R. David Murray added the comment: That would not be consistent with the rest of the docs. Consider, for example, that the full documetation of dictionary views (https://docs.python.org/3/library/stdtypes.html#dictionary-view-objects), which are iterables in much the same way that the enumera

[issue22725] improve documentation for enumerate() (built-in function)

Ethan Furman added the comment: I do not think 'next' is needed in this context. Unlike 'match' and 'search', 'next' is a function that can be used with any iterator and mentioning it here is unnecessary. -- ___ Python tracker

[issue22725] improve documentation for enumerate() (built-in function)

Van Ly added the comment: While next() is rarely used directly on iterators, as you say, it may help to remind the experienced reader of the mechanical characteristic in essence which a new reader on first approach uses to construct a mental model. -- _

[issue22725] improve documentation for enumerate() (built-in function)

Georg Brandl added the comment: next() is quite unlike match() and search(), as you almost never use next() on iterators directly. Rather, the iterator is iterated by constructs like a for loop or a comprehension, or another function that consumes it (list, map, ...) -- nosy: +georg.br

[issue22725] improve documentation for enumerate() (built-in function)

Van Ly added the comment: Reference by the guide to next() should stay for the same reason in re.compile() a regular expression object is returned and the two methods are mentioned, match() and search(). They are useful to know in that context in as much as next() is useful to know here. IMO.

[issue22725] improve documentation for enumerate() (built-in function)

Ethan Furman added the comment: +1 for rdm's change. -- ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: https:/

[issue22725] improve documentation for enumerate() (built-in function)

Changes by Georg Brandl : -- nosy: -georg.brandl ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.

[issue22725] improve documentation for enumerate() (built-in function)

R. David Murray added the comment: I think you misunderstand the purpose of the documentation you are suggesting modifying. It is a *reference guide*, and as such it needs to be technically precise and *must* correctly use the "jargon" of the language. Especially since it also functions as t

[issue22725] improve documentation for enumerate() (built-in function)

Van Ly added the comment: The first mention of iterator should link to 'glossary.html#term-iterator'. There is a builtin iter() function. This may cause confusion in earlier suggested inline sample code. -- Use the following inline sample code -- in place of 'iter = enumerate(led)'to avoid co

[issue22725] improve documentation for enumerate() (built-in function)

Van Ly added the comment: > "sequence must be a sequence" The subtle minutiae of aficionados necessary to interpret the meaning of those two words in their distinct relation is opaque to a new comer and doesn’t serve the widest possible audience usefully to get the job done quick. The second

[issue22725] improve documentation for enumerate() (built-in function)

Georg Brandl added the comment: > I felt the problem was self evident with "sequence must be a sequence". The two words are not used in the same sense: the first names the argument of the function, the second is one of several possible object types you can pass for that argument. -- n

[issue22725] improve documentation for enumerate() (built-in function)

Van Ly added the comment: Understood. I felt the problem was self evident with "sequence must be a sequence". -- ___ Python tracker ___ _

[issue22725] improve documentation for enumerate() (built-in function)

Ethan Furman added the comment: rdm was not asking for an argument, he was asking for a more detailed explanation of what was confusing. Your initial response lacked courtesy and respect, and is not appreciated. The rest of your reply was much better. Next time, please skip the non-construc

[issue22725] improve documentation for enumerate() (built-in function)

Van Ly added the comment: I don't want to argue. Ask a 12-year old and their English teacher, "Does the second sentence qualify as gobbledygook even if it is technically correct and complete and not verbose?" To be constructive and take on what has been said, an iteration on improving the wor

[issue22725] improve documentation for enumerate() (built-in function)

R. David Murray added the comment: The existing documentation is technically correct, while your replacement leaves some things out, such as the fact that enumerate accepts an iteratable and returns an iterator that is specifically a special 'enumerate object'. (A sequence is an iteratable, bu

[issue22725] improve documentation for enumerate() (built-in function)

Changes by Ezio Melotti : -- nosy: +ezio.melotti versions: +Python 3.4, Python 3.6 -Python 3.3 ___ Python tracker ___ ___ Python-bugs-

[issue22725] improve documentation for enumerate() (built-in function)

New submission from Van Ly: The existing documentation is confusing. — improve wording as follows enumerate(sequence, start=0) Returns pairings of index into sequence[link to glossary.html#term-sequence] with the object at that index in the sequence. — wording as found in v.2.7.5 enumerate