[issue3490] Example Code Error in Tutorial Documentation Section 4.4
Change by Chas Belov : -- title: Example Code Error in Tutorial Documentation -> Example Code Error in Tutorial Documentation Section 4.4 ___ Python tracker <https://bugs.python.org/issue3490> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue11425] Cleanup sample code spacing and block arrangement in tutorial.
Change by Chas Belov : -- title: Cleanup sample codes in tutorial. -> Cleanup sample code spacing and block arrangement in tutorial. ___ Python tracker <https://bugs.python.org/issue11425> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1076955] Tutorial corrections (various issues spaced throughout the document)
Change by Chas Belov : -- title: Tutorial corrections -> Tutorial corrections (various issues spaced throughout the document) ___ Python tracker <https://bugs.python.org/issue1076955> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40620] Range tutorial shorthand could be made clearer
New submission from Chas Belov : I found https://docs.python.org/3.7/tutorial/controlflow.html#the-range-function section 4.3 confusing. The range() Function shows the following example: >>> for i in range(5): ... print(i) ... 0 1 2 3 4 [some instructional text] range(5, 10) 5, 6, 7, 8, 9 range(0, 10, 3) 0, 3, 6, 9 range(-10, -100, -30) -10, -40, -70 This appears to be an instruction to type, for example: range(5, 10) at the prompt, and that the response will be: 5, 6, 7, 8, 9 leading to a perceived bug when I type at the prompt: >>> range(5, 10) and receive the response range(5, 10) I ultimately figured out that the example is a shorthand to substitute range(5, 10) for the original range(5) >>> for i in range(5, 10): ... print(i) ... 5 6 7 8 9 It would be less confusing if the example instead read: Substituting "range(5, 10)" for "range(5)" results in (one number per line) 5, 6, 7, 8, 9 Substituting "range(0, 10, 3)" results in 0, 3, 6, 9 and substituting "range(-10, -100, -30)" results in -10, -40, -70 --- such that it is clear that the statements are not meant to be taken as literal stand-alone entries to be typed at the prompt but are instead substitutions. -- messages: 368817 nosy: docor...@sonic.net priority: normal severity: normal status: open title: Range tutorial shorthand could be made clearer versions: Python 3.7 ___ Python tracker <https://bugs.python.org/issue40620> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40640] Tutorial for Continue missing ... line
New submission from Chas Belov :
The tutorial code for Continue at
https://docs.python.org/3.7/tutorial/controlflow.html#break-and-continue-statements-and-else-clauses-on-loops
is missing a
...
null statement.
Actual code/result:
>>> for num in range(2, 10):
... if num % 2 == 0:
... print("Found an even number", num)
... continue
... print("Found a number", num)
Found an even number 2
Found a number 3
Found an even number 4
Found a number 5
Found an even number 6
Found a number 7
Found an even number 8
Found a number 9
Expected code/result:
>>> for num in range(2, 10):
... if num % 2 == 0:
... print("Found an even number", num)
... continue
... print("Found a number", num)
...
Found an even number 2
Found a number 3
Found an even number 4
Found a number 5
Found an even number 6
Found a number 7
Found an even number 8
Found a number 9
--
assignee: docs@python
components: Documentation
messages: 369014
nosy: docor...@sonic.net, docs@python
priority: normal
severity: normal
status: open
title: Tutorial for Continue missing ... line
versions: Python 3.7
___
Python tracker
<https://bugs.python.org/issue40640>
___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40641] Reserved word pair used in lambda tutorial without being noted as a reserved word
New submission from Chas Belov : In the tutorial for lambda expressions at https://docs.python.org/3.7/tutorial/controlflow.html#lambda-expressions the reserved word pair is introduced without noting that it is a reserved word. In the example given, I wasn't sure whether pair was a reserved word or whether the interpreter was parsing the plural "pairs" which is presumable an arbitrary name. Actual content: The above example uses a lambda expression to return a function. Another use is to pass a small function as an argument: >>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')] >>> pairs.sort(key=lambda pair: pair[1]) >>> pairs [(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')] Candidate expected content: The above example uses a lambda expression to return a function. Another use is to pass a small function as an argument, for example, the reserved word pair to designate the position in a tuple pair: >>> items = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')] >>> items.sort(key=lambda pair: pair[1]) >>> items [(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')] -- assignee: docs@python components: Documentation messages: 369017 nosy: docor...@sonic.net, docs@python priority: normal severity: normal status: open title: Reserved word pair used in lambda tutorial without being noted as a reserved word versions: Python 3.7 ___ Python tracker <https://bugs.python.org/issue40641> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40640] Tutorial for Continue missing ... line
Chas Belov added the comment: Um, Python newcomer here. What's a PR? Pull request? I'm happy to do it if you can point me to the how-to. I know my way around git, and not around Python community standards. You are also welcome to go ahead and make the change; thank you for asking. -- ___ Python tracker <https://bugs.python.org/issue40640> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40640] Tutorial for Continue missing ... line
Chas Belov added the comment: @DahlitzFlorian: I'm happy do to the PR provided I don't actually have to build Python to work on a documentation change. If it does require building Python then please go ahead. That said, I've looked at the Doc/tutorial/controlflow.rst and it appears to be a plain text file. I believe that I would have a PR up by May 26, 2020. Is the best practice to check out the 3.10 branch then add backport tags for the other versions to the PR? That wasn't clear to me from the docs you referred me to. -- ___ Python tracker <https://bugs.python.org/issue40640> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40640] Tutorial for Continue missing ... line
Change by Chas Belov : -- keywords: +patch pull_requests: +19602 stage: -> patch review pull_request: https://github.com/python/cpython/pull/20334 ___ Python tracker <https://bugs.python.org/issue40640> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40640] Tutorial for Continue missing ... line
Chas Belov added the comment: @Florian Dahlitz, thank you for your help. I have created a PR at https://github.com/python/cpython/pull/20334 and it is awaiting approval of my CLA and of the change itself. -- ___ Python tracker <https://bugs.python.org/issue40640> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts
New submission from Chas Belov : The tutorial on More on Defining Functions at https://docs.python.org/3.7/tutorial/controlflow.html#more-on-defining-functions is missing most of the >>> and ... screen prompts that show elsewhere in the tutorial. This is potentially confusing to readers. I am going to attempt a PR by May 26, 2020. -- assignee: docs@python components: Documentation messages: 369753 nosy: Chas Belov, docs@python priority: normal severity: normal status: open title: Tutorial 4.7 More on Defining Functions missing screen prompts versions: Python 3.10, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue40748> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40748] Tutorial 4 More Control Flow Tools missing screen prompts in some code blocks
Chas Belov added the comment: Also in For statements https://docs.python.org/3.10/tutorial/controlflow.html#for-statements (same issue) -- title: Tutorial 4.7 More on Defining Functions missing screen prompts -> Tutorial 4 More Control Flow Tools missing screen prompts in some code blocks ___ Python tracker <https://bugs.python.org/issue40748> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40748] Tutorial 4 More Control Flow Tools missing screen prompts in some code blocks
Chas Belov added the comment: Also in For statements https://docs.python.org/3.10/tutorial/controlflow.html#for-statements (same issue) However, a few of the code blocks having this issue don't exist in the documentation of earlier versions. Do I need a separate issue for each code block that is not common across 3.5 through 3.10? Or would this be handled during the back-porting process? -- ___ Python tracker <https://bugs.python.org/issue40748> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts
Chas Belov added the comment: @Ama Aje My Fren, thank you for the advice re backporting. As to your points on ..., both good points, and thank you for introducing me to the Documenting Python document, which I will review. While technically the Tutorial is indeed part of Python's documentation, I would argue that the Tutorial is not a place for shorthand. Learning a new language is hard enough without having to also struggle with inconsistencies in the tutorial interface. My intent with this issue and my (upcoming) pull request is to make the mentioned code blocks consistent with the rest of the page and, indeed, with most of the rest of the tutorial. Most of the tutorial does show >>> and ... at the beginning of each line where the learner would see a prompt. If we are to avoid ... so that learners can copy and paste multiple lines, then why would we not do that through the entire tutorial? I'm guessing your point is that we only need to show >>> and ... when there will be print output so that we need to distinguish between what is input and what is output. As someone who is currently learning Python, however, consistency in presentation is important to me and reduces cognitive load. There are other places in the tutorial where code blocks were used for things which are not typed in, or are not typed without other text. Showing >>> and ... for all verbatim input makes it unambiguous as to whether something is to be typed in. I'll leave it to psychologists as to whether having to type or copy and paste one line at a time leads to better learning. By REPL, do you mean Read-Eval-Print Loop? I'm not familiar with the acronym and that's what Google is telling me it means. But a Read-Eval-Print Loop would have output, and my understanding is that you are arguing against use of ... when there is no output. -- ___ Python tracker <https://bugs.python.org/issue40748> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts
Chas Belov added the comment: Actually, after reviewing the documentation standards, I will hold off my pull request on this issue and raise the cited section of documentation as a separate issue. -- ___ Python tracker <https://bugs.python.org/issue40748> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40758] For 7.2.7. Code Examples, distinguish between the Tutorial and other documentation
New submission from Chas Belov : 7.2.7. Code Examples https://devguide.python.org/documenting/#code-examples states: Short code examples can be a useful adjunct to understanding. Readers can often grasp a simple example more quickly than they can digest a formal description in prose. [snip] The ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations. - I am requesting, as a newcomer to Python who is attempting to navigate the Tutorials and encountering challenges, that this be reworded to something like: Short code examples can be a useful adjunct to understanding. Readers can often grasp a simple example more quickly than they can digest a formal description in prose. [snip] Outside of the Tutorial, the ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations. Within the Tutorial, however, make the appearance of code blocks as consistent with what the student will be experiencing as feasible, to reduce cognitive load and allow them to focus on the content. - While I can in fact suss out whether a particular unmarked code block is meant to be input or output, it is a distraction that uses up some of my attention that I would prefer to spend on learning the language. -- messages: 369825 nosy: Chas Belov priority: normal severity: normal status: open title: For 7.2.7. Code Examples, distinguish between the Tutorial and other documentation versions: Python 3.10 ___ Python tracker <https://bugs.python.org/issue40758> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40758] For 7.2.7. Code Examples, distinguish between the Tutorial and other documentation
Change by Chas Belov : -- versions: +Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue40758> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts
Chas Belov added the comment: I created new issue For 7.2.7. Code Examples, distinguish between the Tutorial and other documentation https://bugs.python.org/issue40758 -- ___ Python tracker <https://bugs.python.org/issue40748> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
