8000 Move description of grouping options in format specification docs · Issue #131912 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

Move description of grouping options in format specification docs #131912

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.

Sign up for GitHub

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

Jump to bottom
Closed
Prometheus3375 opened this issue Mar 30, 2025 · 4 co 8000 mments
Closed

Move description of grouping options in format specification docs #131912

Prometheus3375 opened this issue Mar 30, 2025 · 4 comments
Labels
docs Documentation in the Doc dir

Comments

@Prometheus3375
Copy link
Contributor
Prometheus3375 commented Mar 30, 2025 •
edited by picnixz
Loading

The form of format specifier is the following

[[fill]align][sign]["z"]["#"]["0"][width][grouping_option]["." precision][type]

Docs describe each option in the following order:

  1. align and fill.
  2. sign.
  3. Option z.
  4. Option #.
  5. Option ,.
  6. Option _.
  7. width, then option 0.
  8. precision.
  9. type.

As you can notice, options , and _ are not present in format spec, because they are actually part of grouping_option. For whatever reason they are described before width, but most importantly, their descriptions never mention they are part of grouping_option.

It can be super confusing for the first readthrough, as descriptions are out of order and written similar to standalone options z and #. I suggest the following changes:

  1. Place descriptions of options , and _ after the description of width.
  2. Mention that they are part of grouping_option.
  3. Maybe change BNF specification of grouping_option to "," | "_" to match their description order and order of addition to Python.

Example change:

The grouping_option determines how digits in numbers are grouped. Its first option, ',', signals...

The other grouping_option, '_', signals...

Alternatively, these description can be placed in a table, similar for the list of string presentation types.

The grouping_option determines how digits in numbers are grouped. It can be one of the following:

==here goes the table==

Linked PRs
@Prometheus3375 Prometheus3375 added the docs Documentation in the Doc dir label Mar 30, 2025
@skirpichev
Copy link
Member

Place descriptions of options , and _ after the description of width.

That does make sense. Also, you maybe could group ',' and '_' descriptions (and versionchanged declarations).

Mention that they are part of grouping_option.

No, just specify that '_' or ',' may be specified after width.

Maybe change BNF specification of grouping_option to "," | "_" to match their description order and order of addition to Python.

Or rather reorder separators descriptions in your pt. 1.

Would you like to provide a pr?

@Prometheus3375
Copy link
Contributor Author

Sure, I will make one in a couple of days.

@bedevere-app bedevere-app bot mentioned this issue Apr 2, 2025
Merged
picnixz added a commit that referenced this issue Apr 5, 2025
@Prometheus3375 @picnixz
gh-131912: Improve description of grouping options in the format spec…
06a110f 
…ification docs (#132030)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
@bedevere-app bedevere-app bot mentioned this issue Apr 5, 2025
Merged
picnixz pushed a commit that referenced this issue Apr 7, 2025
@Prometheus3375
[3.13] gh-131912: Improve description of grouping options in the form…
07483c2 
…at specification docs (GH-132030) (#132123)

(cherry picked from commit 06a110f)
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Apr 7, 2025
@Prometheus3375 @miss-islington
[3.13] pythongh-131912: Improve description of grouping options in th…
be7c13a 
…e format specification docs (pythonGH-132030) (pythonGH-132123)

(cherry picked from commit 07483c2)

Co-authored-by: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com>
(cherry picked from commit 06a110f)
@bedevere-app bedevere-app bot mentioned this issue Apr 7, 2025
Merged
picnixz pushed a commit that referenced this issue Apr 7, 2025
@miss-islington @Prometheus3375
[3.12] gh-131912: Improve description of grouping options in the form…
ab78a37 
…at specification docs (GH-132030) (#132203)

(cherry picked from commit 06a110f)

Co-authored-by: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com>
picnixz pushed a commit that referenced this issue Apr 7, 2025
@Prometheus3375
gh-131912: Use different grouping options for the integral and fracti…
3169743 
…onal parts (#132170)
@picnixz picnixz mentioned this issue Apr 7, 2025
Merged
@picnixz
Copy link
Member
picnixz commented Apr 7, 2025

I think we're done with this issue, right?

@skirpichev
Copy link
Member

I think we're done with this issue, right?

Thanks, I think so.

seehwan pushed a commit to seehwan/cpython that referenced this issue Apr 16, 2025
@Prometheus3375 @picnixz @seehwan80
pythongh-131912: Improve description of grouping options in the forma…
32ab983 
…t specification docs (python#132030)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
seehwan pushed a commit to seehwan/cpython that referenced this issue Apr 16, 2025
@Prometheus3375 @seehwan80
pythongh-131912: Use different grouping options for the integral and …
e2e3e41 
…fractional parts (python#132170)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir
Projects
docs issues
Status: Todo
Milestone
No milestone
Development

No branches or pull requests
3 participants
@skirpichev @picnixz @Prometheus3375
0