`denominator` of `Fraction` is positive, which should be documented

[privet-kitty]

Documentation

This suggestion is to clarify the current behavior of the fractions module.

The current implementation of Fraction reduces an input numerator and a denominator so that the latter is positive, which is implemented in the following places:

cpython/Lib/fractions.py

Lines 299 to 303 in d27a53f

	g = math.gcd(numerator, denominator)
	if denominator < 0:
	g = -g
	numerator //= g
	denominator //= g

This behavior is partially documented in https://docs.python.org/3.14/library/fractions.html:

• numerator
  • Numerator of the Fraction in lowest term.
• denominator
  • Denominator of the Fraction in lowest term.
• as_integer_ratio()
  • Return a tuple of two integers, whose ratio is equal to the original Fraction. The ratio is in lowest terms and has a positive denominator.

It says that a denominator returned by as_integer_ratio is positive, but doesn't mention to the sign of the denominator property. I think there should be no problem with making that explicit also in the explanation of denominator.

Linked PRs

• gh-122450: Fix docs to state denominator positivity of Fraction #122464
• gh-122450: Indicate that Fraction denominators are always positive #136789
• [3.14] gh-122450: Indicate that Fraction denominators are always positive (GH-136789) #136792
• gh-122450: Expand documentation for Rational and Fraction #136800
• [3.14] gh-122450: Expand documentation for Rational and Fraction (GH-136800) #137363
• [3.13] gh-122450: Expand documentation for Rational and Fraction (#136800) #137367

[picnixz]

This is not necessarily the case if the input is a rational (which could be a custom class where the denominator is not always positive):

cpython/Lib/fractions.py

Lines 241 to 244 in d27a53f

	elif isinstance(numerator, numbers.Rational):
	self._numerator = numerator.numerator
	self._denominator = numerator.denominator
	return self

[privet-kitty]

@picnixz Thanks for the information. I didn't realize that.

So what is not true is actually the description of as_integer_ratio? This is a bad news...

[picnixz]

Nevermind, the online docs actually say that the denominator of a rational should be positive: https://docs.python.org/3/library/numbers.html#numbers.Rational.

So actually, we can indeed improve the docs by saying that the denominator is positive.

[privet-kitty]

Thank you! I'll fix it.

[skirpichev]

This is not necessarily the case if the input is a rational (which could be a custom class where the denominator is not always positive):

No, it couldn't. But it seems you already realized that.

So actually, we can indeed improve the docs by saying that the denominator is positive.

I'm not sure it's a real improvement as the numbers module already documents that.

Never mind, it seems that docstrings for numerator/denominator are missing. That looks as an issue. I think we should add them (to be like int.numerator/denominator).

[picnixz]

But it seems you already realized that.

Yes, it's just that I don't read the online docs, I usually read the docstring when I can (just because it's easier with an IDE...).

I'm not sure it's a real improvement as the numbers module already documents that.

Since it's in another module (and webpage) people might forget about it. I think it's worth the redundancy.