`math.isnormal` and `math.issubnormal` referring to "normality" without context

[Alex-Wasowicz]

Problem

Descriptions of those functions assume everyone knows what "normalized float" means. Which itself is a mental shorthand to "float valve represented in normalized scientific notation". And even that can raise questions.

On the other hand those descriptions shouldn't be bloated by long specification for any technical term.

Previous discussion

https://discuss.python.org/t/add-cmath-isnormal-and-cmath-issubnormal/94736/15

Linked PRs

• gh-135308: clarify math.issubnormal() description #135324

[StanFromIreland]

cc @skirpichev @picnixz

[picnixz]

I'd agree with Tim's comment on DPO:

Reference docs aren’t meant to be tutorials, and explaining basic concepts of fp representation would be as out of place as, e.g., bloating the docs with explanations about what math.gamma() does. 'If you have to ask …" applies there too.

If someone needs to know the definition of normal and subnormal numbers, I don't think they actually need to use math.isnormal and math.issubnormal. So I'd rather not explain more. What we can do, however, is to link to the Wikipedia's page of normal & subnormal numbers (https://en.wikipedia.org/wiki/Normal_number_(computing) and https://en.wikipedia.org/wiki/Subnormal_number) (we can make it an external URL for the words "normal" and "subnormal")

[collinfunk]

@picnixz I was thinking the same. I am +1 for just linking the Wikipedia pages.

[skirpichev]

Descriptions of those functions assume everyone knows what "normalized float" means.

No. Both terms are defined in descriptions. I appreciate, if someone could explain that better, but please make concrete proposals.

[terryjreedy]

Any reason to not backport this improvement? Would there be a merge conflict

[picnixz]

The function was new in 3.15.