random.vonmisesvariate() and random.lognormvariate() accept invalid parameters despite docs constraints

[denini08]

Bug report

Bug description:

While reading the Python documentation for the random module, I noticed something that looks inconsistent between the documentation and the actual behavior of the code.

The documentation for the functions random.vonmisesvariate() and random.lognormvariate() states some restrictions for their parameters link:

• For vonmisesvariate(mu, kappa), it says that "kappa must be greater than or equal to zero".
• For lognormvariate(mu, sigma), it says that "sigma must be greater than zero".

However, the functions do not raise any error when invalid values are passed:

import random

print(random.vonmisesvariate(1, -2))   # No error
print(random.lognormvariate(1, -2))    # No error

Both functions run without any exception, even though the parameters do not meet the constraints described in the documentation.

I am wondering if this is something that should be addressed. Should the functions validate their parameters and raise an error (e.g., ValueError) for invalid inputs? Or maybe the documentation should be updated to clarify that these constraints are mathematical recommendations rather than enforced by code?

I just wanted to report this inconsistency between the documentation and the code behavior and ask for your opinion about whether this should be considered a bug or a documentation issue.

CPython versions tested on:

3.15

Operating systems tested on:

macOS

[tim-one]

I vote for "code bug" rather than "doc issue".

[terryjreedy]

I had to wonder what the function does with the arguments.

normal_variate returns mu + z * sigma. A negative sigma returns each random normal with the sign flipped, which, since the distribution is symmetric, is a random normal. A zero sigma always returns mu. The only reason not to check is pure speed. But I am fairly sure that difference after adding if sigma <= 0.0:... would be insignificant. Normal sigma should also be documented as > 0.0.

vonmises already tests kappa for near 0 is a way that treats all negatives as 0. if kappa <= 1e-6: return TWOPI * random(). We should add a 2nd check:

        if kappa <= 1e-6:  # Small (treat as 0.0) or negative (raise).
            if kappa >= 0:
                return TWOPI * random()
            else:
                raise ValueError("vonmisesvariate:  kappa must be >= 0.0")

The exception message follows style of gamma_variate, but I might prefer "vonmises variate kappa ...". @denini08 did you check the other argument restrictions in the module?

[denini08]

@terryjreedy
I found in the gammavariate function:

cpython/Lib/random.py

Lines 687 to 688 in 9877d19

	if alpha <= 0.0 or beta <= 0.0:
	raise ValueError('gammavariate: alpha and beta must be > 0.0')

and in binomialvariate function:

cpython/Lib/random.py

Lines 812 to 819 in 9877d19

	if n < 0:
	raise ValueError("n must be non-negative")
	if p <= 0.0 or p >= 1.0:
	if p == 0.0:
	return 0
	if p == 1.0:
	return n
	raise ValueError("p must be in the range 0.0 <= p <= 1.0")

and others like getrandbits...