Step one of gh-90016: reword adapter/converter section and add recipes. The latter point is very much a work in progress; I will incorporate some of Serhiy's suggestions here before marking this as ready for review.

We will backport this to 3.11 and 3.10, and then deprecate the default adapters/converters (in main only).

I also took the liberty of normalising the argument spec of register_adapter and register_converter; they are positional only, so the naming is irrelevant to the functionality of these methods. However, I would like to use this opportunity to normalise the docstrings.

For new reviewers: suggestions to how to help reviewing this PR:

• rewording: improve my English; I'm not a native speaker
• userfriendlyness: is the rewritten docs more userfriendly or less userfriendly? why? how can it be improved?
• examples: do the examples make sense? are they easily understood? how can they be improved?
• brevity/verboseness: is this part of the docs too verbose? or the opposite? are there redundant passages (I said the same thing twice using different wordings)?
• are there obvious reST markup issues?

A fair few comments ;)

Fantastic, thank you so much :) I've addressed your review in 0b6f381. I've left two of the conversations unresolved.

Now, onto the recipes.

A few more tiny nits :)

Thanks again! Addressed in 72013ef

I'm marking this as ready for review, although I expect more work on the recipes before this can land.

@malemburg, would you mind taking a look at this PR?

Thank you so much for reviewing, everyone! I believe I've addressed everything1. I believe there is still room for improvement on this particular area, but this PR is already long and unwieldy.

Here are some quick'n dirty notes I made while reading this through for the umpteenth time:

• The doc section for sqlite3.connect is very long and messy... it mentions type detection and SQLite types in probably three places (!), IIRC
• The examples, guides, and tutorial'ish section (for adapters/converters) seem to repeat each other all the time... could benefit from consolidation... diataxis can perhaps help here. Perhaps it is time to create Doc/howto/sqlite3.rst?
• The SQLite types (ref sqlite3-types) section could be made more to the point

Anyways, I'll leave this open for a few more days before merging, in case y'all want to review the recent updates yet again :)

Footnotes

1. Well, almost everything. Some concerns will be addressed in future PRs, like for example documenting the obscure PrepareProtocol class. ↩

The examples, guides, and tutorial'ish section (for adapters/converters) seem to repeat each other all the time... could benefit from consolidation... diataxis can perhaps help here. Perhaps it is time to create Doc/howto/sqlite3.rst?

Yeah—the split itself should be fairly clean and straightforward since the high-level organization is already along these lines, though there's plenty of internal improvement to be done in helping address the other issues mentioned. Of course, this would be a followup PR.

The doc section for sqlite3.connect is very long and messy... it mentions type detection and SQLite types in probably three places (!), IIRC

Out of scope for this immediate PR, but here's a peak at a draft of how it could look rewritten as Reference documentation following Diataxis guidelines, using a consistent, structured format (Sphinxdoc) to be clearer, more concise/less repetitive, easier to navigate, and more complete (including param types, default values, etc), as discussed on Discourse.

Its around 1/3 shorter (despite including more information), and much easier to quickly scan and efficiently retrieve the specific information a user is looking for (what a param does, its type, default values, etc), without having to wade through paragraph after paragraph of narrative text, infer key details from implicit information, and jump through a chain of links to find something as simple as a default value.

(FYI, I'll reflow the changes right before merging.)

@erlend-aasland Here's the reST source from the draft of the reorganization above, if you'd prefer to use that as a base for a followup PR and iterate further on it yourself, as opposed to me submiting that as a PR on its own.

Sidenote: my intention was to move the "trips and tricks with uri" example block to the "Guide" section/document, to avoid belaboring the API reference too much; otherwise, it contains all the same key information as the original + your changes here.

@erlend-aasland Here's the reST source from the draft of the reorganization above, if you'd prefer to use that as a base for a followup PR and iterate further on it yourself, as opposed to me submiting that as a PR on its own.

Thanks a lot!

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

Sorry, @erlend-aasland, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker bd3c1c187e0e4fde5aec6835d180e9eddde8ceb6 3.11

Sorry @erlend-aasland, I had trouble checking out the 3.10 backport branch.
Please backport using cherry_picker on command line.
cherry_picker bd3c1c187e0e4fde5aec6835d180e9eddde8ceb6 3.10

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

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