SqlValue

class SqlValue(value=NOT_SPECIFIED)

A positional parameter placeholder. Created via SQL.value(value). Inherits from SqlParam.

Parameters:: value – Any Python value to be passed as a query parameter. If omitted, this is a template slot — the placeholder is emitted but no argument is collected.

Emits a placeholder appropriate to the formatter style (%s, ?, or :N) and appends value to the argument list:

SQL.value(42)
# format:  %s    args: [42]
# qmark:   ?     args: [42]
# numeric: :1    args: [42]

Template mode (no value):

SQL.value()
# format:  %s    args: []
# qmark:   ?     args: []

Typically used within SQL.cat():

SQL.cat('interval ', SQL.value('1 hour'))
# sql:  interval %s
# args: ['1 hour']

SqlNamedValue

class SqlNamedValue(name, value=NOT_SPECIFIED)

A named parameter placeholder. Created via SQL.named_value(name, value). Inherits from SqlParam.

Parameters:

name – The parameter name, used in the placeholder.
value – Any Python value to be passed as a query parameter. If omitted, this is a template slot.

Required for named and pyformat formatter styles. Emits a placeholder using the parameter name:

SQL.named_value('user_id', 42)
# named:    :user_id      args: {'user_id': 42}
# pyformat: %(user_id)s   args: {'user_id': 42}

Template mode (no value):

SQL.named_value('user_id')
# named:    :user_id      args: {}
# pyformat: %(user_id)s   args: {}

When the same name appears multiple times in a query, the value only needs to be supplied once. Conflicting values raise ValueError.