gh-101693: In sqlite3, deprecate using named placeholders with parameters supplied as a sequence #101698
- Loading branch information
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -1435,6 +1435,10 @@ Cursor objects | |||||
| :raises ProgrammingError: | ||||||
| If *sql* contains more than one SQL statement. | ||||||
|
|
||||||
| :raises DeprecationWarning: | ||||||
| If :ref:`named placeholders <sqlite3-placeholders>` are used | ||||||
| and *parameters* is a sequence. | ||||||
|
|
||||||
| If :attr:`~Connection.autocommit` is | ||||||
| :data:`LEGACY_TRANSACTION_CONTROL`, | ||||||
| :attr:`~Connection.isolation_level` is not ``None``, | ||||||
|
|
@@ -1444,10 +1448,13 @@ Cursor objects | |||||
|
|
||||||
| .. versionchanged:: 3.12 | ||||||
|
||||||
| .. versionchanged:: 3.12 | |
| .. deprecated-removed:: 3.12 3.14 |
There was a problem hiding this comment.
Are you sure about that? The API itself is not deprecated, we're just changing it. I'm not sure what's the recommended practice here.
There was a problem hiding this comment.
Yeah, I know what you mean. I feel like ideally this notice would be phrased along the lines of "X behaviour/practice is now deprecated" rather than "a DeprecationWarning is now emitted". That would be more to-the-point, and it would also work more naturally with this directive (X behaviour/practice is deprecated in 3.12, and will be removed entirely in 3.14).
But I was struggling to come to with a concrete suggestion for how to reword these notices :/
There was a problem hiding this comment.
(The whatsnew and NEWS entries look great btw, it's just the notices in the API docs that feel slightly clunky to me)
There was a problem hiding this comment.
I feel like ideally this notice would be phrased along the lines of "X behaviour/practice is now deprecated" rather than "a DeprecationWarning is now emitted". That would be more to-the-point, and it would also work more naturally with this directive (X behaviour/practice is deprecated in 3.12, and will be removed entirely in 3.14).
Yes, but documented as deprecated and emitting a DeprecationWarning are similar, but not equal, things 🙂 With the former, we don't need to emit a warning in the code.
There was a problem hiding this comment.
To your original question, btw: I think it's pretty standard to use .. deprecated or .. deprecated-removed, even if it's just a particular usage of an API, rather than the API itself. See e.g. https://docs.python.org/3.12/library/asyncio-policy.html#asyncio.DefaultEventLoopPolicy, where the directive is used even though the class itself hasn't been deprecated at all; or #19867, which deprecated just a specific parameter; or lots of other examples in our docs 🙂
There was a problem hiding this comment.
Aight! I'll try to reword it.
There was a problem hiding this comment.
I've updated it to use deprecated-removed, and I put in an extra line regarding what happens in 3.14. I'm too tired to reword the text 🙂
Uh oh!
There was an error while loading. Please reload this page.