Hi! After reviewing the source files on master, I found three bugs in docs/writing/style.rst (and a few related URLs in other docs files). All are reproducible against the current master branch.
Bug 1: Misspelling — "falsey" should be "falsy" (style.rst, line ~598)
In the "Check if a variable equals a constant" section, the comment in the "Good" code example reads:
# or check for the opposite
if not attr:
print('attr is falsey!') # <-- incorrect spelling
The correct Python community term is "falsy" (not "falsey"). This is the spelling used consistently in PEP 8, the Python docs, and throughout the Python community. A quick search confirms "falsey" appears nowhere in the official Python documentation.
Fix: Change 'attr is falsey!' to 'attr is falsy!'
Bug 2: Broken code example — while i in a: has no i defined (style.rst, "Filtering a list" section)
In the "Filtering a list" section, there are two separate .. code-block:: python blocks both listed under Bad. The second one is:
while i in a:
a.remove(i)
This block is presented as a standalone example but i is never defined within it. It silently relies on i leaking from the previous for loop. Worse, in the context of the preceding example (a = [3, 4, 5], remove items > 4), after the for loop runs, a = [3, 4] and i = 5 — so the while loop condition 5 in [3, 4] is immediately False and the loop never executes at all. The example fails to demonstrate what it intends to show.
Fix: Give the while loop its own self-contained setup, e.g.:
# Don't make multiple passes through the list
a = [3, 4, 5]
i = 5
while i in a:
a.remove(i)
Or, more clearly, change i to the literal value it's meant to represent:
while 5 in a:
a.remove(5)
Bug 3: Stale / unversioned Python 2 documentation URLs (multiple files)
Several links use the old unversioned http://docs.python.org/... URL format, which redirects to Python 2 documentation. These should be updated to explicitly point to Python 3.
Affected lines in docs/writing/style.rst:
- Line ~575: Truth Value Testing link →
http://docs.python.org/library/stdtypes.html#truth-value-testing
-
- Line ~637: List comprehensions link →
http://docs.python.org/tutorial/datastructures.html#list-comprehensions
-
-
- Line ~641: Generator expressions link →
http://docs.python.org/tutorial/classes.html#generator-expressions
Also affected:
docs/writing/structure.rst line ~396: http://docs.python.org/tutorial/modules.html#packages
-
docs/scenarios/cli.rst line ~49: explicit Python 2 link → http://docs.python.org/2/library/argparse.html (in the Plac section)
-
-
docs/intro/learning.rst lines ~20 and ~370: unversioned Python tutorial and language reference links
Fix for all: Replace http://docs.python.org/ with https://docs.python.org/3/ in all instances.
Happy to submit a PR for any or all of these if that would be helpful!
Hi! After reviewing the source files on master, I found three bugs in
docs/writing/style.rst(and a few related URLs in other docs files). All are reproducible against the current master branch.Bug 1: Misspelling — "falsey" should be "falsy" (
style.rst, line ~598)In the "Check if a variable equals a constant" section, the comment in the "Good" code example reads:
The correct Python community term is "falsy" (not "falsey"). This is the spelling used consistently in PEP 8, the Python docs, and throughout the Python community. A quick search confirms "falsey" appears nowhere in the official Python documentation.
Fix: Change
'attr is falsey!'to'attr is falsy!'Bug 2: Broken code example —
while i in a:has noidefined (style.rst, "Filtering a list" section)In the "Filtering a list" section, there are two separate
.. code-block:: pythonblocks both listed under Bad. The second one is:This block is presented as a standalone example but
iis never defined within it. It silently relies onileaking from the previousforloop. Worse, in the context of the preceding example (a = [3, 4, 5], remove items> 4), after the for loop runs,a = [3, 4]andi = 5— so the while loop condition5 in [3, 4]is immediatelyFalseand the loop never executes at all. The example fails to demonstrate what it intends to show.Fix: Give the
whileloop its own self-contained setup, e.g.:Or, more clearly, change
ito the literal value it's meant to represent:Bug 3: Stale / unversioned Python 2 documentation URLs (multiple files)
Several links use the old unversioned
http://docs.python.org/...URL format, which redirects to Python 2 documentation. These should be updated to explicitly point to Python 3.Affected lines in
docs/writing/style.rst:http://docs.python.org/library/stdtypes.html#truth-value-testinghttp://docs.python.org/tutorial/datastructures.html#list-comprehensionshttp://docs.python.org/tutorial/classes.html#generator-expressionsAlso affected:
docs/writing/structure.rstline ~396:http://docs.python.org/tutorial/modules.html#packagesdocs/scenarios/cli.rstline ~49: explicit Python 2 link →http://docs.python.org/2/library/argparse.html(in the Plac section)docs/intro/learning.rstlines ~20 and ~370: unversioned Python tutorial and language reference linksFix for all: Replace
http://docs.python.org/withhttps://docs.python.org/3/in all instances.Happy to submit a PR for any or all of these if that would be helpful!