[doc] Error in functional how-to example

[dxflores]

BPO	39971
Nosy	@rhettinger, @terryjreedy, @ericvsmith, @dxflores, @slateny
PRs	bpo-39971: Change examples to be runnable #32172

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-03-15.16:39:23.863>
labels = ['easy', '3.11', '3.9', '3.10', 'docs']
title = '[doc] Error in functional how-to example'
updated_at = <Date 2022-03-29.07:57:47.314>
user = 'https://github.com/dxflores'

bugs.python.org fields:

activity = <Date 2022-03-29.07:57:47.314>
actor = 'eric.smith'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-03-15.16:39:23.863>
creator = 'dxflores'
dependencies = []
files = []
hgrepos = []
issue_num = 39971
keywords = ['patch', 'easy']
message_count = 6.0
messages = ['364247', '364275', '364346', '364708', '364709', '364710']
nosy_count = 6.0
nosy_names = ['rhettinger', 'terry.reedy', 'eric.smith', 'docs@python', 'dxflores', 'slateny']
pr_nums = ['32172']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue39971'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[dxflores]

Hello,

A code example from the 'functional programming how-to' raises an error.

The simplest fix would be to remove the Ellipsis object from the 'line_list'.

Thank you,
Diogo

Please check below for the commands issued:

# https://docs.python.org/3/howto/functional.html#generator-expressions-and-list-comprehensions

>>> line_list = ['  line 1\n', 'line 2  \n', ...]
>>> 
>>> # Generator expression -- returns iterator
>>> stripped_iter = (line.strip() for line in line_list)
>>> 
>>> # List comprehension -- returns list
>>> stripped_list = [line.strip() for line in line_list]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 1, in <listcomp>
AttributeError: 'ellipsis' object has no attribute 'strip'

[ericvsmith]

I don't think that was meant to be a literal example. I think that "..." here means "and other strings".

[dxflores]

Agreed, Eric. Nevertheless, I think that this example might raise unnecessary confusion to someone new to Python, and hence the reason why I decided to open the issue. Anyhow, I trust your judgement and please feel free to leave things as is and close this issue.

PS: I really the work you did with dataclasses, and I actually explored the idea further with a small (300 LoC) library that adds runtime type checking for instances of dataclasses - if you are ever curious you can find the code on my GitHub at /dxflores/invis.

Thank you,
Diogo

[terryjreedy]

In think examples should run and that '...' should be replaced by something like "' \n', ''". The blank string looks ahead to the next example, which adds ' if line != ""' to the comprehension.

[terryjreedy]

Working on PR. The example 1 further on has a stray meaningless ellipsis.

         for expr3 in sequence3 ...
         if condition3

Perhaps this was meant to follow the next line, but I will remove it.

[terryjreedy]

Looking around further, examples meant to be executable as is are given interactive prompts and needed doctest directives

    >>> gen  #doctest: +ELLIPSIS
    <generator object generate_ints at ...>

I think that this example should get the same treatment. Non-executable examples are usually clearly non-executable because then contain undefined names line 'expr2' and 'sequence2', whereas this example starts by defining 'line_list'.