Document default numeric string formats

[kpinc]

BPO	39416
Nosy	@ericvsmith, @merwok, @kpinc, @miss-islington
PRs	bpo-39416: Document some restrictions on the default string representations of numeric classes #18111 [3.9] bpo-39416: Document some restrictions on the default string representations of numeric classes (GH-18111) #22860 [3.8] bpo-39416: Document some restrictions on the default string representations of numeric classes (GH-18111) #22861 Fix bpo-39416: Change "Numeric" to lower case; an english word, not a class name #22867 [3.9] Fix bpo-39416: Change "Numeric" to lower case; an english word, not a class name (GH-22867) #22868 [3.8] bpo-39416: change word case to not imply ABC (GH-22867) (GH-22869) #22869

^{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-10-21.18:57:12.011>
created_at = <Date 2020-01-22.02:35:29.555>
labels = ['3.8', '3.9', '3.10', 'docs']
title = 'Document default numeric string formats'
updated_at = <Date 2020-12-16.03:18:24.940>
user = 'https://github.com/kpinc'

bugs.python.org fields:

activity = <Date 2020-12-16.03:18:24.940>
actor = 'eric.araujo'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-10-21.18:57:12.011>
closer = 'eric.araujo'
components = ['Documentation']
creation = <Date 2020-01-22.02:35:29.555>
creator = 'kop'
dependencies = []
files = []
hgrepos = []
issue_num = 39416
keywords = ['patch']
message_count = 10.0
messages = ['360442', '360449', '360465', '379224', '379232', '379233', '379234', '379249', '379252', '383115']
nosy_count = 5.0
nosy_names = ['eric.smith', 'eric.araujo', 'docs@python', 'kop', 'miss-islington']
pr_nums = ['18111', '22860', '22861', '22867', '22868', '22869']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue39416'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[kpinc]

Seems sane to put _some_ restrictions on the string representations of the Numeric classes. This would be a change to the Python language
specification.

Suggestions made in a pull request.

See the email thread:
Subject: Documenting Python's float.__str__()
https://mail.python.org/archives/list/python-dev@python.org/thread/FV22TKT3S2Q3P7PNN6MCXI6IX3HRRNAL/

[ericvsmith]

Is the lack of this documentation causing some confusion somewhere? This isn't rhetorical, I'm genuinely curious what problem you're trying to solve.

Is there any mainstream programming language where the basics of what you've laid out aren't true? It all seems pretty obvious to me. For example, I can't see anyone looking at this and saying "Ah, base 10. That's why it's producing the output I'm seeing."

[kpinc]

On Wed, 22 Jan 2020 06:09:41 +0000
"Eric V. Smith" <report@bugs.python.org> wrote:

Eric V. Smith <eric@trueblade.com> added the comment:

Is the lack of this documentation causing some confusion somewhere?
This isn't rhetorical, I'm genuinely curious what problem you're
trying to solve.

I'd say no, there's no real confusion anywhere.

This started with a search for documentation on Python's
default string representation for float. This accidentally
wound up on the python-dev mailing list and became a
more general discussion during which I suggested that
some fundamentals are clear. This is pretty much just
a follow-up to that discussion.

Is there any mainstream programming language where the basics of what
you've laid out aren't true? It all seems pretty obvious to me. For
example, I can't see anyone looking at this and saying "Ah, base 10.
That's why it's producing the output I'm seeing."

Well, I just got done looking at YAML which has a lot of base-related
syntax including base 60. :)

The problem that would be solved is that it's easy to rely
on the default Numeric output formats. Most output probably
does not go through a formatter, although this may change
now that f-strings are so easy. Anyway, this would guarantee
"normal output" for numbers, even when switching between
Python implementations.

Likewise, immutability of value when round-tripping through a
string is also obvious. But is still an important property.

So if these properties are important then include them in the spec.
That's what specs are for. (I could probably find some non-mainstream
languages (scheme perhaps) that have specs which include
similar documentation. You pretty have to have a formatter
in compiled languages, so those won't specify a default.
Anyway, it shouldn't matter what other language specs do.)

I understand if nobody sees this as a real problem. And
I don't want to stand up as a big proponent. I'll
point out the argument here and let others decide.

Regards,

Karl <kop@karlpinc.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

[miss-islington]

New changeset c60394c by kpinc in branch 'master':
bpo-39416: Document some restrictions on the default string representations of numeric classes (GH-18111)
c60394c

[miss-islington]

New changeset ec62b47 by Miss Skeleton (bot) in branch '3.9':
[3.9] bpo-39416: Document some restrictions on the default string representations of numeric classes (GH-18111) (GH-22860)
ec62b47

[miss-islington]

New changeset 89fac4c by Miss Skeleton (bot) in branch '3.8':
[3.8] bpo-39416: Document some restrictions on the default string representations of numeric classes (GH-18111) (GH-22861)
89fac4c

[merwok]

Thanks for the patch!