Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc] Error in functional how-to example #84152

Closed
dxflores mannequin opened this issue Mar 15, 2020 · 6 comments
Closed

[doc] Error in functional how-to example #84152

dxflores mannequin opened this issue Mar 15, 2020 · 6 comments
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy

Comments

@dxflores
Copy link
Mannequin

dxflores mannequin commented Mar 15, 2020

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
    Copy link
    Mannequin Author

    dxflores mannequin commented Mar 15, 2020

    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'

    @dxflores dxflores mannequin added the 3.8 only security fixes label Mar 15, 2020
    @dxflores dxflores mannequin assigned docspython Mar 15, 2020
    @dxflores dxflores mannequin added docs Documentation in the Doc dir 3.8 only security fixes labels Mar 15, 2020
    @dxflores dxflores mannequin assigned docspython Mar 15, 2020
    @dxflores dxflores mannequin added the docs Documentation in the Doc dir label Mar 15, 2020
    @ericvsmith
    Copy link
    Member

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

    @dxflores
    Copy link
    Mannequin Author

    dxflores mannequin commented Mar 16, 2020

    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
    Copy link
    Member

    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 terryjreedy added 3.7 (EOL) end of life 3.9 only security fixes labels Mar 20, 2020
    @terryjreedy terryjreedy changed the title Error on documentation - Quick fix. Error in functional how-to example Mar 20, 2020
    @terryjreedy terryjreedy added 3.7 (EOL) end of life 3.9 only security fixes labels Mar 20, 2020
    @terryjreedy terryjreedy changed the title Error on documentation - Quick fix. Error in functional how-to example Mar 20, 2020
    @terryjreedy
    Copy link
    Member

    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
    Copy link
    Member

    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'.

    @iritkatriel iritkatriel added easy 3.10 only security fixes 3.11 only security fixes and removed 3.7 (EOL) end of life 3.8 only security fixes labels Mar 20, 2022
    @iritkatriel iritkatriel changed the title Error in functional how-to example [doc] Error in functional how-to example Mar 20, 2022
    @iritkatriel iritkatriel added easy 3.10 only security fixes 3.11 only security fixes and removed 3.7 (EOL) end of life 3.8 only security fixes labels Mar 20, 2022
    @iritkatriel iritkatriel changed the title Error in functional how-to example [doc] Error in functional how-to example Mar 20, 2022
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy
    Projects
    None yet
    Development

    No branches or pull requests

    3 participants