[3.14] gh-122450: Indicate that Fraction denominators are always positive (GH-136789)

[miss-islington]

(cherry picked from commit eb8ac4c)

Co-authored-by: nacind 107233139+nacind@users.noreply.github.com

• Issue: denominator of Fraction is positive, which should be documented #122450

---

📚 Documentation preview 📚: https://cpython-previews--136792.org.readthedocs.build/

[python-cla-bot]

The following commit authors need to sign the Contributor License Agreement:

• 107233139+nacind@users.noreply.github.com

[AA-Turner]

@nacind please could you sign the CLA here?

A

[AA-Turner]

@serhiy-storchaka was "do-not-merge" intentional?

[skirpichev]

was "do-not-merge" intentional?

See #136789 (review).

This change is incorrect and should be reverted.

[AA-Turner]

I disagree that this is incorrect. At worst, I would say that it has an ambiguous interpretation. In general, I think statements like the above are generally less helpful, especially in cases like this where we are discussing linguistic merits of word choice and not a technical implementation. I'm happy to hold this PR in 'draft', though, whilst we continue to make improvements to the fractions documentation.

A

[skirpichev]

I disagree that this is incorrect.

Two core devs disagree with you. I think it's a good argument against merging such changes and for a quick revert.

At worst, I would say that it has an ambiguous interpretation.

Well, it's math. You can't interpret same term differently in same sentence. That doesn't make any sense.

I accept, documentation can be later improved. But now it's just plain wrong: it asserts that denominator argument is positive.

[AA-Turner]

it asserts that denominator argument is positive.

Our style guide notes that arguments are italicised. Indeed, that is the case here -- the denominator argument is stated as being a Rational and that if it is 0, an exception is raised. We then say that the Fraction object will have value equal to $numerator/denominator$. In that same part, we note that the denominator will be converted to a positive number. I contend that equal to is not identical to in this case, so noting that the resulting denominator will be positive is fine. I think the PR to further improve this is nearly ready, I've just made two suggestions within the last hour.

A

[AA-Turner]

Closing this now in favour of #136800 (which will need manual backports).

A