gh-96168: Add sqlite3 row factory how-to

[erlend-aasland]

• Issue: sqlite3 docs: extract row factory examples into row factory howto #96168

[CAM-Gerlach]

Thanks @erlend-aasland .

Overall, I found the examples helpful, and a good balance between concise and detailed. However, maybe this is just me, but to me the section did appear pretty heavy on examples, but without as much explicit focus on solving specific user problems, as would be appropriate for a how-to. In that sense, it almost feels more like a tutorial, having readers learn using row factories by example, as opposed to telling them how to solve specific problems using row factories.

@ezio-melotti , what do you think?

[erlend-aasland]

However, maybe this is just me, but to me the section did appear pretty heavy on examples, but without as much explicit focus on solving specific user problems, as would be appropriate for a how-to.

Yeah, maybe... but How To's are recipes. How can I create a foo row factory? How do I use a bar row factory? How do I use the sqlite3.Row row factory? I don't think it matters much that it is example heavy. IMO it is too thin for a tutorial, and definitely too thin for an explanation.

[erlend-aasland]

Ouch, it just occurred to me that the Cursor also has a row_factory attribute, with the following problems:

• it is not documented (easily fixed; we can do that in this PR done in this PR)
• it is copied from the connection in Cursor.__init__, so changing the connection row factory does not affect the row factories of the cursors belonging to that connection; vice versa

So, more prose coming up.

>>> import sqlite3
>>> cx = sqlite3.connect(":memory:")
>>> cx.row_factory = sqlite3.Row
>>> cu = cx.cursor()
>>> cx.row_factory = None
>>> cu.row_factory == cx.row_factory
False
>>> cu.connection.row_factory == cx.row_factory
True

[erlend-aasland]

@CAM-Gerlach: I've reworded the reference, hopefully to the better; IMO the current version reflects the difference between the two row factory attributes more clearly. I also removed the example from ab98877; IMO it is superfluous with the now (hopefully) improved reference. Looking forward to your comments.

[CAM-Gerlach]

This is indeed looking pretty good, thanks. Follow-up suggestions are basically just textual tweaks.

[CAM-Gerlach]

Looks pretty good to me now, personally, Just a couple minor suggestions and followups to others' comments.

[CAM-Gerlach]

Just one comment cleaning up my own mess, otherwise LGTM from my side, thanks.

[erlend-aasland]

Thanks again y'all for improving this part of the docs. I'm going to land this later today. A lot of back and forth, but IMO totally worth it.

[miss-islington]

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

[bedevere-bot]

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

[bedevere-bot]

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