gh-101117: Improve accuracy of sqlite3.Cursor.rowcount docs

[erlend-aasland]

The SQLite C API sqlite3_changes() can only be relied upon when the
statment has been run to completion.

• Issue: SQLite rowcount is corrupted when combining UPDATE RETURNING w/ id IN (?) #101117

---

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

[erlend-aasland]

@rt121212121, would this docs update be an improvement?

[rt121212121]

As a developer in the Python ecosystem I have had more breaking changes than I would like in both standard library modules and core tools like the packaging tools, this is the third recently. Each of these is regrettable and incurs both unwanted work and confusion.

Documentation would be good. I would recommend that all breaking changes are clearly and explicitly documented, both in what's new and in the library documentation. I understand that you have a lot of demands on your time, so that would be appreciated.

Personally, I would break this further. I would have the rowcount error if the problem case is encountered, rather than being incorrect. But that is asking someone to do more work, and that someone is not going to be myself.

[erlend-aasland]

As a developer in the Python ecosystem I have had more breaking changes than I would like in both standard library modules and core tools like the packaging tools, this is the third recently. Each of these is regrettable and incurs both unwanted work and confusion.

I understand your frustration, and thank you for speaking up. Note that we really strive to avoid these kinds of changes; backwards compatibility is a priority. Unfortunately, as I wrote on the issue, we sometimes take the wrong step. In this case, the backwards compatibility issues were not immediately obvious.

Documentation would be good. I would recommend that all breaking changes are clearly and explicitly documented, both in what's new and in the library documentation. I understand that you have a lot of demands on your time, so that would be appreciated.

All known breaking changes are always documented, both in the changelog (NEWS entries) and in What's New. We've also introduced a new category in What's New for pending breaking changes, in order to better prepare users of stuff like deprecated APIs being removed in a future version. Of course, this implies that we know that a change is a breaking change; this was unfortunately not the case for the changes that lead to your specific problem here. IMO, the best we can do now, is to improve the existing documentation, which is what I'm trying to do with this PR.

Personally, I would break this further. I would have the rowcount error if the problem case is encountered, rather than being incorrect. But that is asking someone to do more work, and that someone is not going to be myself.

That is a slight change in the existing semantics of rowcount, so we'd have to think that through very carefully, as it may be another breaking change. For the sake of stability, I'd prefer to keep the status quo, and simply document how to use the APIs.

[miss-islington]

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

[miss-islington]

Sorry @erlend-aasland, I had trouble checking out the 3.11 backport branch.
Please retry by removing and re-adding the "needs backport to 3.11" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 7470321f8171dce96a604ba2c24176837f999ca0 3.11

[erlend-aasland]

Thanks for the review, Alex, and thanks for your input Roger.

[bedevere-bot]

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