[docs] [issue20364] Rename & explain sqlite3.Cursor.execute 'parameters' param

[Terry J. Reedy]

New submission from Terry J. Reedy:

"execute(sql[, parameters])
    Executes an SQL statement. The SQL statement may be parametrized (i. e. placeholders instead of SQL literals). The sqlite3 module supports two kinds of placeholders: question marks (qmark style) and named placeholders (named style)."

Experimental facts based on experiments with the code example in the doc, using 3.4.b2: 'parameters' is a single subscriptable collection parameter, sequence or dict, that might be called seq_dict. It is positional only, so whatever name is used is a dummy. Only one placeholder style can be used in a given SQL statement string. If question marks are used, seq_dict must be a sequence. If names are used, seq_dict can be either a sequence or dict or subclass thereof. A UserDict is treated as a sequence and raises KeyError(0).

Possible text that encompasses the above, replacing the last sentence:

"A statement may use one of two kinds of placeholders: question marks (qmark style) or named placeholders (named style). For qmark style, seq_dict must be a sequence. For named style, it can be either a sequence or dict instance. Len(seq_dict) must match the number of placeholders."

After cleaning up the test file, I will verify on 2.7 and upload.

----------
assignee: docs at python
components: Documentation, Library (Lib)
messages: 208908
nosy: docs at python, terry.reedy
priority: normal
severity: normal
stage: patch review
status: open
title: Rename & explain sqlite3.Cursor.execute 'parameters'  param
type: behavior
versions: Python 2.7, Python 3.3, Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue20364>
_______________________________________