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

f-string's "debug" feature is undocumented #85217

Closed
ericvsmith opened this issue Jun 19, 2020 · 16 comments
Closed

f-string's "debug" feature is undocumented #85217

ericvsmith opened this issue Jun 19, 2020 · 16 comments
Labels
3.8 only security fixes 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@ericvsmith
Copy link
Member

BPO 41045
Nosy @gvanrossum, @ericvsmith, @ezio-melotti, @eamanu, @miss-islington, @amaajemyfren, @rishi93
PRs
  • bpo-41045: Add documentation for f-string's self documenting expressions #21464
  • bpo-41045: Document debug feature of f-strings ('=') #21509
  • gh-85583: Document f-strings in library/stdtypes.rst #21552
  • [3.8] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) #21644
  • [3.9] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) #21645
  • [3.8] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) #21647
  • 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 = <Date 2020-07-27.23:23:16.235>
    created_at = <Date 2020-06-19.23:53:12.742>
    labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
    title = 'f-string\'s "debug" feature is undocumented'
    updated_at = <Date 2020-07-27.23:23:16.234>
    user = 'https://github.com/ericvsmith'

    bugs.python.org fields:

    activity = <Date 2020-07-27.23:23:16.234>
    actor = 'gvanrossum'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2020-07-27.23:23:16.235>
    closer = 'gvanrossum'
    components = ['Documentation']
    creation = <Date 2020-06-19.23:53:12.742>
    creator = 'eric.smith'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 41045
    keywords = ['patch']
    message_count = 16.0
    messages = ['371912', '371913', '373607', '373608', '373611', '373975', '374120', '374394', '374397', '374399', '374428', '374430', '374431', '374435', '374440', '374441']
    nosy_count = 8.0
    nosy_names = ['gvanrossum', 'eric.smith', 'ezio.melotti', 'docs@python', 'eamanu', 'miss-islington', 'amaajemyfren', 'rishi93']
    pr_nums = ['21464', '21509', '21552', '21644', '21645', '21647']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue41045'
    versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

    @ericvsmith
    Copy link
    Member Author

    The feature of f-strings using '=' for "debugging" formatting is not documented.

    >>> foo = 'bar'
    >>> f'{foo=}'
    "foo='bar'"

    I'm not sure where this should fit in to the documentation, but it needs to be in there somewhere.

    Basically the documentation needs to say:

    1. The entire string from the opening brace { to the start of the expression appears in the output. This allows things like f'{foo = }' to evaluate to "foo = 'bar'" (notice the extra spaces).

    2. If no format spec (like :20) is given, repr() is used on the expression. If a format spec is given, then str() is used on the expression. You can use repr() with a format spec by using the !r conversion, like:

    >>> f'{foo=:20}'
    'foo=bar                 '
    
    >>> f'{foo=!r:20}'
    "foo='bar'               "

    @ericvsmith ericvsmith added 3.8 only security fixes 3.9 only security fixes 3.10 only security fixes labels Jun 19, 2020
    @ericvsmith ericvsmith added docs Documentation in the Doc dir 3.8 only security fixes 3.9 only security fixes 3.10 only security fixes labels Jun 19, 2020
    @ericvsmith ericvsmith added the docs Documentation in the Doc dir label Jun 19, 2020
    @gvanrossum
    Copy link
    Member

    Every other detail about f-strings is spelled out meticulously in the reference manual: https://docs.python.org/3/reference/lexical_analysis.html#formatted-string-literals

    I think it needs to be added here.

    PS OT: I can't find anything about f-strings in pydoc.

    @rishi93
    Copy link
    Mannequin

    rishi93 mannequin commented Jul 13, 2020

    Hello all,

    Could I help by adding this to the documentation ?

    @ericvsmith
    Copy link
    Member Author

    @rishi93: yes, please do!

    @rishi93
    Copy link
    Mannequin

    rishi93 mannequin commented Jul 13, 2020

    Thank you very much. I have made a pull request. Looking forward to your review on my first open-source contribution :)

    @amaajemyfren
    Copy link
    Mannequin

    amaajemyfren mannequin commented Jul 19, 2020

    Hello all,

    I have attempted to resolve this issue by adding some comments to PR21464 and later provided a reworded PR21509 that attempts to resolve this using ideas from @rishi93.

    Finally I have tried to document f-string within pydoc itself with PR21552.

    I request please that they be marked with skip-news. Also request feedback on the PRs.

    @gvanrossum
    Copy link
    Member

    I've reviewed your first PR (bpo-21509).

    Regarding your second one, I think there's a misunderstanding. With "pydoc" I didn't mean "the Python docs". IMO the documentation of f-strings in the language reference is sufficient, there's no need for another section about it in the library reference.

    What I meant was that the pydoc module doesn't have any text about f-strings. The help() builtin calls pydoc.help(), and there are some special topics that you can invoke whose source text is generated
    by running make pydoc-topics in the Doc directory and copying the output into Lib/pydoc_data/. There is a list of topics included in Doc/tools/extensions/pyspecific.py (pydoc_topic_labels) and something has to be added there. But beware! This code is tricky. You also need to add an entry to pydoc.py itself, to the dict named 'topics' around line 1891. I think you can just add an entry FSTRINGS to the latter and make it point to the section labeled f-strings in the language reference (which you are updating in PR 21509).

    Let me know if you need more help (I had a fun hour figuring out how all this works :-).

    @ezio-melotti
    Copy link
    Member

    I was just just trying to link to someone the documentation for f-strings, but:

    1. Searching "fstring" only returns two results about xdrlib0;
    2. Searching "f-string" returns many unrelated results1;
    3. The first (and closer) result (string -- Common string operations2) yields nothing while using ctrl+f with fstring, f-string, f', f";
    4. at the top of that page there are two links in a "see also":
    • Text Sequence Type — str3: it mentions raw strings at the beginning, but also yields no results for fstring, f-string, f', f";
    • String Methods4: that is another section of the previous page (so ctrl+f doesn't find anything), but has a link to "Format String Syntax"5;
    1. The "Format String Syntax" page5 has another link in the middle of a paragraph that points to "formatted string literals", that eventually brings us to the right page6;
    2. the "right page"6 has a wall of text with a block of code containing the grammar, luckily followed by a few examples.

    I think we should:

    1. add index entries for "f-string" and "fstring" in the relevant sections of the docs, so that they appear in the search result;
    2. in the Text Sequence Type — str3 section, have a bullet list for f-strings, raw-strings, and possibly u-strings;
    3. possibly use the term "f-string" in addition (or instead) of "formatted string literal", to make the pages more ctrl+f-friendly throughout the docs;
    4. possibly have another more newbie-friendly section on f-string (compared to the lexical analysis page) in the tutorial, in the stdtypes page7 (e.g. before the printf-style String Formatting" section8), or in the string page2 (e.g. after the "Format String Syntax" section[10]);
    5. possibly reorganize and consolidate the different sections about strings, string methods, str.format(), the format mini-language, f-strings, raw/unicode-strings, %-style formatting in a single page or two (a page for the docs and one for the grammar), since it seems to me that over the years these sections got a bit scattered around as they were being added.

    If you think this is out of the scope of this issue, I can open a separate one.

    @ezio-melotti ezio-melotti added type-feature A feature request or enhancement labels Jul 27, 2020
    @gvanrossum
    Copy link
    Member

    Those are really good observations and proposals, Ezio! I agree that it might be better to separate them into a new issue. Can you also review #21552 (the second PR here by amaajemyfren)? Maybe it would actually make a good candidate for part (4) of your proposed solutions.

    @ama Aje My Fren: please look at my review of #21509 and implement my suggestions, then we can merge that one and close *this* issue.

    @ezio-melotti
    Copy link
    Member

    I agree that it might be better to separate them into a new issue.

    I created bpo-41411.

    @amaajemyfren
    Copy link
    Mannequin

    amaajemyfren mannequin commented Jul 27, 2020

    then we can merge that one and close *this* issue.

    I am looking at the pydoc issue now. It will take me more than an hour but I will figure it. Can that be under this issue also or (since you raised it as an OT) make that another issue?

    @gvanrossum
    Copy link
    Member

    I think your PR 21552 and any work you're doing on pydoc could go under the new bpo-41411 that Ezio just opened.

    @miss-islington
    Copy link
    Contributor

    New changeset 13efaec by amaajemyfren in branch 'master':
    bpo-41045: Document debug feature of f-strings ('=') (GH-21509)
    13efaec

    @gvanrossum
    Copy link
    Member

    New changeset e962e3f by Guido van Rossum in branch '3.9':
    [3.9] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) (GH-21645)
    e962e3f

    @gvanrossum
    Copy link
    Member

    New changeset 3baff21 by Guido van Rossum in branch '3.8':
    [3.8] bpo-41045: Document debug feature of f-strings ('=') (GH-21509) (bpo-21647)
    3baff21

    @gvanrossum
    Copy link
    Member

    Thanks Ama Aje My Fren! You can transfer your other PR to a different bpo issue by editing the subject on GitHub.

    @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.8 only security fixes 3.9 only security fixes 3.10 only security fixes docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    4 participants