This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Documentation of math.pow, math.hypot, and complex.__abs__
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: mark.dickinson Nosy List: ddicato, georg.brandl, mark.dickinson
Priority: normal Keywords: patch

Created on 2010-02-16 22:41 by ddicato, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
math_docs.patch mark.dickinson, 2010-04-06 19:26
Messages (10)
msg99445 - (view) Author: David DiCato (ddicato) Date: 2010-02-16 22:41
The standard library documentation for the math module states "All functions return a quiet NaN if at least one of the args is NaN." However, there are some exceptions to this rule, including:

math.pow(1.0, float('nan')) == 1.0
math.hypot(float('inf'), float('nan')) == float('inf')
abs(complex(float('nan'), float('inf'))) == float('inf')

The docs should be updated to reflect that such corner cases exist.
msg99446 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-02-16 22:46
Thanks for reporting this.

Rather than documenting corner cases explicitly, maybe it would be enough to point to the C99 standard:  the corner cases for the math functions should (modulo bugs) all follow Annex F of the C standard, while the corner cases for the cmath functions follow Annex G.  This doesn't quite tell the complete story, because some functions (for example the cmath.rect function) don't appear in the C standards, but it would avoid cluttering the function descriptions with special cases.

Certainly the "All functions ..." sentence is inaccurate, and should be removed or revised.  I believe it's true for all single-argument functions, though.
msg99447 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-02-16 22:54
Hmm.  Looking at the docs, there are a number of revisions that would be useful.  For example, the docs mention signaling NaNs, but that doesn't make a lot of sense:  Python essentially treats all NaNs as quiet.  I'll add this to my to-do list.
msg102486 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-04-06 19:26
Proposed update to math docs.
msg102487 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-04-06 19:39
Looks good to me.  Is it intentional that the paragraph about signaling NaNs is gone completely?

And is it intentional that you changed behavior -> behaviour? :)
msg102488 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-04-06 19:41
Thanks, Georg.

Yes and No.

Yes:  Perhaps I should say something about signaling nans, but what was there was just nonsense.

No:  I'll drop the 'u' from behaviour, for the sake of consistency.
msg102489 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-04-06 19:48
You don't need to :)
msg102490 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-04-06 19:56
Too late!  Committed in r79858 (trunk) through r79861 (release31-maint).
I added a couple of sentences about signaling nans.

Thanks for reviewing!
msg102491 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-04-06 20:15
You didn't give me the chance to review the new sentences!  Now I have to tell you that there is now "NaN", "*NaN*" and "nan" which looks inconsistent... :)
msg102499 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-04-06 22:21
Rats.

nan->NaN in r79871 through r79874.

Then I reread your message...

*NaN* -> Nan in r79875 (trunk);  will merge to other branches tomorrow when my brain might be working again.
History
Date User Action Args
2022-04-11 14:56:57adminsetgithub: 52195
2010-04-12 20:00:59mark.dickinsonsetstatus: open -> closed
2010-04-06 22:21:43mark.dickinsonsetstatus: closed -> open

messages: + msg102499
2010-04-06 20:15:54georg.brandlsetmessages: + msg102491
2010-04-06 19:56:47mark.dickinsonsetstatus: open -> closed
resolution: fixed
messages: + msg102490

stage: resolved
2010-04-06 19:48:49georg.brandlsetmessages: + msg102489
2010-04-06 19:41:02mark.dickinsonsetmessages: + msg102488
2010-04-06 19:39:37georg.brandlsetmessages: + msg102487
2010-04-06 19:26:10mark.dickinsonsetfiles: + math_docs.patch
keywords: + patch
messages: + msg102486
2010-02-18 15:01:05mark.dickinsonsetpriority: normal
2010-02-16 22:54:39mark.dickinsonsetmessages: + msg99447
2010-02-16 22:50:29georg.brandlsetassignee: georg.brandl -> mark.dickinson
2010-02-16 22:46:06mark.dickinsonsetnosy: + mark.dickinson
messages: + msg99446
2010-02-16 22:41:39ddicatocreate