Add named parameter support

[bgunebakan]

Summary of the changes / Why this is an improvement

Adds client-side named parameter support (pyformat paramstyle) to the CrateDB Python client, addressing the request in #774.

Previously, cursor.execute() only accepted positional ? placeholders. Users with complex SQL had to maintain a positional list that was error-prone and hard to read.

With this change, a dict can be passed as the parameters argument using %(name)s placeholders:

cursor.execute(
    "SELECT * FROM t WHERE city = %(city)s AND kiez = %(kiez)s",
    {"city": "Berlin", "kiez": "Kreuzberg"},
)

The same parameter name may appear multiple times in the query, each occurrence is resolved independently:

cursor.execute(
    "SELECT * FROM t WHERE state = %(q)s OR city = %(q)s",
    {"q": "Berlin"},
)

Positional ? queries continue to work unchanged, no breaking change.

Known limitation

Supporting named params in bulk operations are not supported because it requires a different approach from execute(). We need to extract the ordered parameter name list from the SQL. Excluded from this PR to keep this PR focused on the core execute() case.

Checklist

• Link to issue this PR refers to (if applicable): Fixes Parameter binding failure with string containing "{{value}}" and lack of named parameter support #774

[mfussenegger]

Thank you for the contribution.
Could you also add an entry to the CHANGES.rst? Otherwise lgtm

[mfussenegger]

I'd tend to move the method into the cursor module and prefix it with _.

It's not supposed to be public API and a dedicated module doesn't seem warranted for this tiny and simple function.

[bgunebakan]

Good call. I was thinking to isolate the regex logic in its own module to keep cursor.py focused on DB-API concerns and make the function independently testable.

I'm moving to _convert_named_to_positional and _NAMED_PARAM_RE directly into cursor.py at module level (not inside the class, since it doesn't touch self or any class state). And will delete params.py. What do you think about this structure?

[mfussenegger]

I'm moving to _convert_named_to_positional and _NAMED_PARAM_RE directly into cursor.py at module level (not inside the class, since it doesn't touch self or any class state). And will delete params.py. What do you think about this structure?

Sounds good

[bgunebakan]

Thank you for your review. I refactored the code based on that.

[mfussenegger]

Btw. as a follow up we should change this behavior to have this return "SELECT $1, $1", [42]

[bgunebakan]

Thanks for suggestion. We can keep track of of already seen names and reuse them inside _convert_named_to_positional() How should we follow up? should I open a new issue or create a PR directly?

[mfussenegger]

I already created a PR: #796

[bgunebakan]

ok super!