gh-91134: Correct docstrings for built-in in-place operators

[nickovs]

The whitespace in the example code included in the doc string has also been made PEP-8 compliant.

https://bugs.python.org/issue46978

Automerge-Triggered-By: GH:rhettinger

• Issue: Doc strings for built-in, in-place operators are misleading #91134

[the-knights-who-say-ni]

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

CLA Missing

Our records indicate the following people have not signed the CLA:

@nickovs

For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

If you have recently signed the CLA, please wait at least one business day
before our records are updated.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

[MaxwellDupre]

Couldn't find out how to test slots so ran full suite:
412 tests OK.
2 tests failed:
test_asyncio test_embed
I think this qualifies as a pass. Anyway this has no side effects.

[rhettinger]

Closing and reopening to trigger the bots.

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[miss-islington]

@nickovs: Status check is done, and it's a failure ❌ .

[rhettinger]

Please sign the CLA or we can't go forward.

[nickovs]

I already signed the CLA, back on March 11th, but it seems that there is a bug in the CLA-checking bot that means that if you have multiple email addresses on your GitHub account it needs you to sign multiple CLAs, in the same name but listing the different addresses. I've signed a second CLA so hopefully this can proceed.

[JelleZijlstra]

Unfortunately the CLA check is still failing.

As a workaround, maybe you can re-commit with the email address you signed the CLA with and force-push the branch.

[miss-islington]

@nickovs: Status check is done, and it's a failure or timed out ❌.

[nickovs]

OK. The system seems to now be showing the CLA is signed and all checks are passing.

[CuriousLearner]

That's amazing!! Thanks for your help Nicko!

@rhettinger / @JelleZijlstra We can get this merged in now :)

[arhadthedev]

The CLA check is green; merging main to retrigger the automerge label processing.

[arhadthedev]

MacOS failure is known and is being fixed on the GitHub side. @iritkatriel could you merge this PR (with its backports) manually please? All other tests successfully pass.

[miss-islington]

Thanks @nickovs for the PR, and @iritkatriel for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[miss-islington]

Sorry, @nickovs and @iritkatriel, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 128379b8cdb88a6d3d7fed24df082c9a654b3fb8 3.11

[miss-islington]

Sorry @nickovs and @iritkatriel, I had trouble checking out the 3.10 backport branch.
Please retry by removing and re-adding the "needs backport to 3.10" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 128379b8cdb88a6d3d7fed24df082c9a654b3fb8 3.10

[arhadthedev]

@iritkatriel I backported the PR but the bot failed to link them here:

• [3.10] gh-31802: Correct docstrings for in-place builtin operators #102043
• [3.11] gh-31802: Correct docstrings for in-place builtin operators #102042

[merwok]

Before backporting, could people go to the issue first to discuss the relevance of this change?

@rhettinger does not agree that there is a bug to be fixed here and requested to revert.

[iritkatriel]

@rhettinger does not agree that there is a bug to be fixed here and requested to revert.

This PR was approved by @rhettinger .

[iritkatriel]

PR to revert the change: #102146

Let's close the issue once we've come to a decision on this.

[JelleZijlstra]

For ease of reference, the issue is #91134 and the relevant comment is #91134 (comment).

[bedevere-bot]

GH-102041 is a backport of this pull request to the 3.10 branch.