gh-122450: Expand documentation for Rational and Fraction

[skirpichev]

• add docstrings for numerator/denominator attributes
• removes sphinx docs for above properties in the fractions module
• reverts eb8ac4c

Co-authored-by: Hugo Sansaqua [email protected]

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

Links:

• https://cpython-previews--136800.org.readthedocs.build/en/136800/library/numbers.html#numbers.Rational
• https://cpython-previews--136800.org.readthedocs.build/en/136800/library/fractions.html

[serhiy-storchaka]

Look also at the paragraph before the constructor description: "A Fraction instance can be constructed from a pair of integers, from another rational number, or from a string." It is outdated. The numbers in the pair can be not only integers, and the single numerical argument can be not only rational. Making it more precise will only lead to repetition, so I would make it more generic instead.

[AA-Turner]

I'll wait until tomorrow to merge in case others have comments.

A

[AA-Turner]

Can you handle the backports?

A

[miss-islington-app]

Thanks @skirpichev for the PR, and @AA-Turner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @skirpichev and @AA-Turner, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker b266fbc9ecd25d08ab572ecb91913e86b6ddc75e 3.14

[miss-islington-app]

Sorry, @skirpichev and @AA-Turner, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker b266fbc9ecd25d08ab572ecb91913e86b6ddc75e 3.13

[skirpichev]

Can you handle the backports?

Sure, I will.

[bedevere-app]

GH-137363 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-137367 is a backport of this pull request to the 3.13 branch.

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot AMD64 Windows PGO NoGIL 3.x (tier-1) has failed when building commit b266fbc.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/1622/builds/2370) and take a look at the build logs.
4. Check if the failure is related to this commit (b266fbc) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/1622/builds/2370

Failed tests:

• test_launcher

Failed subtests:

• test_py_handle_64_in_ini - test.test_launcher.TestLauncher.test_py_handle_64_in_ini
• test_search_major_2 - test.test_launcher.TestLauncher.test_search_major_2
• test_search_major_3 - test.test_launcher.TestLauncher.test_search_major_3
• test_py2_shebang - test.test_launcher.TestLauncher.test_py2_shebang
• test_list_paths - test.test_launcher.TestLauncher.test_list_paths

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "C:\Users\Administrator\buildarea\3.x.itamaro-win64-srv-22-aws.nogil.pgo\build\Lib\test\test_launcher.py", line 465, in test_search_major_2
    self.assertEqual("PythonCore", data["env.company"])
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 'PythonCore' != 'PythonTestSuite'
- PythonCore
+ PythonTestSuite


Traceback (most recent call last):
  File "C:\Users\Administrator\buildarea\3.x.itamaro-win64-srv-22-aws.nogil.pgo\build\Lib\test\test_launcher.py", line 652, in test_py_handle_64_in_ini
    data = self.run_py([], allow_fail=True, expect_returncode=103)
  File "C:\Users\Administrator\buildarea\3.x.itamaro-win64-srv-22-aws.nogil.pgo\build\Lib\test\test_launcher.py", line 252, in run_py
    raise subprocess.CalledProcessError(p.returncode, [self.py_exe, *args], out, err)
subprocess.CalledProcessError: Command '[WindowsPath('C:/Users/Administrator/buildarea/3.x.itamaro-win64-srv-22-aws.nogil.pgo/build/PCbuild/amd64/py.exe')]' returned non-zero exit status 0.


Traceback (most recent call last):
  File "C:\Users\Administrator\buildarea\3.x.itamaro-win64-srv-22-aws.nogil.pgo\build\Lib\test\test_launcher.py", line 445, in test_search_major_3
    self.assertEqual("PythonCore", data["env.company"])
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 'PythonCore' != 'PythonTestSuite'
- PythonCore
+ PythonTestSuite


Traceback (most recent call last):
  File "C:\Users\Administrator\buildarea\3.x.itamaro-win64-srv-22-aws.nogil.pgo\build\Lib\test\test_launcher.py", line 385, in test_list_paths
    self.assertDictEqual(expect, actual)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^
AssertionError: {'-V:[238 chars]rv-22-aws.nogil.pgo\\build\\PCbuild\\amd64\\python3.15t.exe'} != {'-V:[238 chars]rv-22-aws.x64.nogil\\build\\PCbuild\\amd64\\python3.15t_d.exe'}
Diff is 727 characters long. Set self.maxDiff to None to see it.


Traceback (most recent call last):
  File "C:\Users\Administrator\buildarea\3.x.itamaro-win64-srv-22-aws.nogil.pgo\build\Lib\test\test_launcher.py", line 579, in test_py2_shebang
    data = self.run_py([script, "-postarg"])
  File "C:\Users\Administrator\buildarea\3.x.itamaro-win64-srv-22-aws.nogil.pgo\build\Lib\test\test_launcher.py", line 254, in run_py
    self.assertEqual(expect_returncode, p.returncode)
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 0 != 103