gh-94017: Improve clarity of sqlite3 transaction handling docs

[erlend-aasland]

Fixesgh-94017

[erlend-aasland]

cc. @CAM-Gerlach, @AlexWaygood. Would you two mind reviewing this? I'll go over it later today, to be sure the docs align with the actual implementation. Other that, I worry that the new tone of the docs may come across as ... perhaps a trifle strict, or negative sounding (in lack of more appropriate words). I also worry about the added verbosity. I do hope this makes things clearer, though.

[CAM-Gerlach]

Thanks @erlend-aasland , this is a definite improvement. I do have some clarity, textual and reST fixes and suggestions.

[AlexWaygood]

+1 to most of Cam's thoughts

[erlend-aasland]

Thanks, both of you; highly appreciated. I'm finally getting around to address the reviews.

[erlend-aasland]

Reviews addressed in a530b3e.
I mostly went for ~Connection.isolation_level style links instead of the more explicit Connection.isolation_level style links. I can use the latter if that's preferred.

[CAM-Gerlach]

I mostly went for ~Connection.isolation_level style links instead of the more explicit Connection.isolation_level style links. I can use the latter if that's preferred.

That's fine with me, since it isn't used on multiple classes in the module and links directly to them in either case. I wasn't very consistent about using that myself.

[CAM-Gerlach]

LGTM, thanks @erlend-aasland

I had one comment, but that might be out of scope here and better addressed in a future PR.

[erlend-aasland]

I'm sorry, but I did a last rewrite of things, trying to address #94320 (comment). Hopefully to the better. I'd be happy if you could review commit 1473e94. If it was for the worse, I'll revert it.

For the "Controlling Transactions" section, I tried to improve the visual separation of the two sqlite3 transaction modes.

[CAM-Gerlach]

I'm sorry, but I did a last rewrite of things, trying to address #94320 (comment). Hopefully to the better. I'd be happy if you could review commit 1473e94. If it was for the worse, I'll revert it.

No need to apologize for doing more work and making the docs better! I'll review it now—sorry myself for the delay; it was a holiday weekend and I was with family.

[CAM-Gerlach]

Review feedback on the final revisisions

[erlend-aasland]

Thanks again for the reviews; I'll land this later tonight.

[miss-islington]

Thanks @erlend-aasland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-94617 is a backport of this pull request to the 3.11 branch.

[bedevere-bot]

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