Skip to content

math.isnormal and math.issubnormal referring to "normality" without context #135308

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
Open
Alex-Wasowicz opened this issue Jun 9, 2025 · 4 comments
Open

math.isnormal and math.issubnormal referring to "normality" without context #135308

Alex-Wasowicz opened this issue Jun 9, 2025 · 4 comments
Labels
docs Documentation in the Doc dir

Comments

@Alex-Wasowicz
Copy link

Alex-Wasowicz commented Jun 9, 2025 •
edited by bedevere-app bot
Loading

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
@Alex-Wasowicz Alex-Wasowicz added the docs Documentation in the Doc dir label Jun 9, 2025
@StanFromIreland
Copy link
Contributor

cc @skirpichev @picnixz

@picnixz
Copy link
Member

picnixz commented Jun 9, 2025 •
edited
Loading

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")

@picnixz picnixz added the pending The issue will be closed if no feedback is provided label Jun 9, 2025
@collinfunk
Copy link
Contributor

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

@skirpichev
Copy link
Contributor

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.

@skirpichev skirpichev removed the pending The issue will be closed if no feedback is provided label Jun 10, 2025
skirpichev added a commit to skirpichev/cpython that referenced this issue Jun 10, 2025
@skirpichev
pythongh-135308: clarify math.issubnormal() description
2fe9e1c
@bedevere-app bedevere-app bot mentioned this issue Jun 10, 2025
Open
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
5 participants
@skirpichev @picnixz @collinfunk @StanFromIreland @Alex-Wasowicz