coolqlite.query¶

Query processing.

You probably won’t need to use this module if you’re just using coolqlite.Connection.query(), but it may be handy if you want to debug your queries or conversions.

Query proccessing happens in two steps, arbitrarily (but alphabetically!) named “analyze” and “build”.

Analyze takes a string.templatelib.Template (t-string) and turns it into an AnalyzedQuery, which holds the sql query string and named parameters. The values of those parameters haven’t been converted yet though.
Build takes that AnalyzedQuery and turns it into a BuiltQuery, which has run all conversions. This step can fail, but it will collect all errors into a CoolqliteExceptionGroup so you can see each one.

Warning

These names will likely change, especially if we eventually get an actual query builder.

These mostly exist for you to debug your queries and conversions; it should not be a stable API to depend upon for now.

coolqlite.query.analyze_query(query: Template) → AnalyzedQuery¶: Anlyze a template.

class coolqlite.query.AnalyzedQuery(query_str: str, params: dict[str, Param])¶

Bases: object

A template that has been analyzed into the query string and (possibly name-mangled) parameters, ready to be converted.

query_str: str¶

params: dict[str, Param]¶: Maps (possibly mangled) param name to the param.

class coolqlite.query.Param(*, param_name: str, original_param_expr: str, converter_name: str, original_value: Any)¶

Bases: object

An analyzed input parameter.

param_name: str¶

The name assigned to the parameter.

May be mangled if a filter was applied or it wasn’t a valid identifier.

original_param_expr: str¶: The original expression used in the t-string.

converter_name: str¶

The name of the converter to use.

(Has not been validated to be present, that happens during building.)

original_value: Any¶: The value of the original expression in the t-string.

class coolqlite.query.ConvertedParam(*, param_name: str, original_param_expr: str, converter_name: str, original_value: Any, converted_value: Any)¶

Bases: Param

A param that has been converted.

converted_value: Any¶: The converted value.

class coolqlite.query.BuiltQuery(query_str: str, params: dict[str, ConvertedParam])¶

Bases: object

A query that has been “built” from an AnalyzedQuery, with its parameters converted.

query_str: str¶

params: dict[str, ConvertedParam]¶: Maps (possibly mangled) param name to the param.

exception coolqlite.query.ParamMissingToSqlFnError(param: Param, cause: MissingToSqlFnError)¶

Bases: CoolqliteError

A converter fn was missing. See error message for details.

param: Param¶: The parameter whose converter couldn’t be found.

cause: MissingToSqlFnError¶: This should be the same as __cause__ but this helps guarantee it’s there.

exception coolqlite.query.ToSqlFnFailure(param: Param)¶

Bases: CoolqliteError

A converter itself threw an exception.

param: Param¶: The parameter being processed when this error occurred.

exception coolqlite.query.QueryBuilderErrorGroup(message, exceptions, *_args, **kwargs)¶

Bases: CoolqliteExceptionGroup[ParamMissingToSqlFnError | ToSqlFnFailure]

Errors that occurred during query building.