[issue44344] Documentation for pow() should include the possibility of complex numbers as a return type

[Erik Y. Adams]

New submission from Erik Y. Adams :

https://docs.python.org/3/library/functions.html#pow

The built-in pow() function will return a complex number if the base is 
negative and the exponent is a float between 0 and 1. For example, the value 
returned by `pow(-1, 1.0/3)` is `(1.0002+1.7320508075688772j)`

The answer is mathematically correct, but `-2.0` is also mathematically 
correct. There is nothing in the documentation currently to suggest that a 
complex number might be returned; in fact, given the statement "[with] mixed 
operand types, the coercion rules for binary arithmetic operators apply", one 
might reasonably expect `-2.0` as the answer. 

I suggest the following sentences be added to the end of the second paragraph:

"If `base` is negative and the `exp` is a `float` between 0 and 1, a complex 
number will be returned. For example, `pow(-8, 1.0/3)` will return 
`(1.0002+1.7320508075688772j)`, and not `-2.0.`"

--
assignee: docs@python
components: Documentation
messages: 395305
nosy: docs@python, eyadams
priority: normal
severity: normal
status: open
title: Documentation for pow() should include the possibility of complex 
numbers as a return type
type: enhancement
versions: Python 3.9

___
Python tracker 
<https://bugs.python.org/issue44344>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44344] Documentation for pow() should include the possibility of complex numbers as a return type

[Erik Y. Adams]

Erik Y. Adams  added the comment:

I still think the most important aspect of this is that pow() will return 
complex numbers, contrary to what is implied by the statement I quoted at the 
beginning of this thread. 

Perhaps we should just borrow from the documentation for the power operator, 
which says:

Raising 0.0 to a negative power results in a ZeroDivisionError. Raising a 
negative number to a fractional power results in a complex number. (In earlier 
versions it raised a ValueError.)

https://docs.python.org/3/reference/expressions.html#the-power-operator

--

___
Python tracker 
<https://bugs.python.org/issue44344>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com