SqlFormat

class SqlFormat(dialect, query, right_margin=80, indent=4)

Renders a query object into a SQL string using %s placeholders (DB-API format style). Not typically instantiated directly — use SQL.format(query), MYSQL.format(query), or MSSQL.format(query).

Parameters:

• dialect – A Dialect constant identifying the SQL dialect.

• query – The query object to render (any SqlObj with a .sql() method).

• right_margin – Maximum line width before wrapping. Default 80.

• indent – Number of spaces per indent level. Default 4.

get_sql()

Returns the formatted SQL string with placeholders.

Return type:

str

qb = SQL.select().from_table('users').column('name').where('id', '=', 42)
fmt = SQL.format(qb)
fmt.get_sql()  # 'SELECT name\nFROM users\nWHERE id = %s'

get_args()

Returns the collected parameter values. A list for positional styles, a dict for named styles.

Return type:

list or dict

fmt.get_args()  # [42]

get_sqlargs()

Returns (sql, args) tuple, suitable for passing directly to a DB-API cursor.

Return type:

tuple[str, list | dict]

cur.execute(*SQL.format(qb).get_sqlargs())

is_empty()

Returns True if no SQL was generated.

Return type:

bool

param(value_obj)

Emit a placeholder and collect the argument. Called internally by SqlValue and SqlNamedValue.

Parameters:

value_obj – A SqlValue or SqlNamedValue instance.

write_query(query)

Write a SqlQuery as a parenthesized, indented subquery.

Parameters:

query – A SqlQuery instance to render.

comment(comment)

Write a SQL comment block. Each line of the comment string is emitted prefixed with -- ``, followed by a newline. If *comment* is ``None or empty, nothing is written.

Parameters:

comment – A string (may contain newlines), or None.

class SqlFormatQmark(dialect, query, right_margin=80, indent=4)

Renders using ? placeholders (DB-API qmark style). Not typically instantiated directly — use SQLITE.format(query). Arguments collected as a list.

Inherits all methods from SqlFormat.

class SqlFormatNumeric(dialect, query, right_margin=80, indent=4)

Renders using :1, :2 placeholders (DB-API numeric style). Not typically instantiated directly — use ORACLE.format_numeric(query). Arguments collected as a list.

Inherits all methods from SqlFormat.

class SqlFormatNamed(dialect, query, right_margin=80, indent=4)

Renders using :name placeholders (DB-API named style). Not typically instantiated directly — use ORACLE.format(query). Arguments collected as a dict.

Requires all parameters to be SqlNamedValue instances. Raises TypeError if a positional SqlValue is encountered.

Inherits all methods from SqlFormat.

class SqlFormatPyformat(dialect, query, right_margin=80, indent=4)

Renders using %(name)s placeholders (DB-API pyformat style). Not typically instantiated directly — use SQL.format_pyformat(query) or MYSQL.format_pyformat(query). Arguments collected as a dict.

Requires all parameters to be SqlNamedValue instances. Raises TypeError if a positional SqlValue is encountered.

Inherits all methods from SqlFormat.