SQLCommenter

SQLCommenter formatting, context management, and query comment injection.

Context and Attributes

class sqlspec.core.sqlcommenter.SQLCommenterContext

Bases: object

Request-scoped storage for sqlcommenter attributes via contextvars.

Framework middlewares set attributes per-request, and the sqlcommenter statement transformer reads them at compile time.

classmethod get()

Get the current request-scoped attributes.

Return type:

dict[str, str] | None

classmethod set(attrs)

Set request-scoped attributes.

Return type:

None

classmethod scope(cls, attrs)

Context manager that sets attributes for the duration of a block.

Return type:

Generator[None, None, None]

Functions

sqlspec.core.sqlcommenter.generate_comment(attrs)

Serialize attributes into a sqlcommenter comment body.

Parameters:

attrs (Mapping[str, str | None]) -- Key-value pairs to serialize. None values are skipped.

Return type:

str

Returns:

Comma-separated key='value' pairs sorted lexicographically, or empty string if no attributes.

sqlspec.core.sqlcommenter.append_comment(expression, attrs)

Add sqlcommenter attributes as a comment on a parsed expression.

Uses sqlglot's add_comments() API so the comment coexists with existing comments and optimizer hints.

Parameters:

• expression (Expr) -- Parsed sqlglot expression tree.

• attrs (Mapping[str, str | None]) -- Attributes to serialize into the comment.

Return type:

Expr

Returns:

The expression with the sqlcommenter comment added (mutated in place).

sqlspec.core.sqlcommenter.parse_comment(expression)

Extract sqlcommenter attributes from a parsed expression's comments.

Identifies sqlcommenter comments by their key='value' structure, extracts the attributes, and removes the sqlcommenter comment from the expression while preserving other comments.

Parameters:

expression (Expr) -- Parsed sqlglot expression tree.

Return type:

tuple[Expr, dict[str, str]]

Returns:

Tuple of (expression_without_sqlcommenter_comment, parsed_attributes). If no sqlcommenter comment is found, returns the expression unchanged and an empty dict.

sqlspec.core.sqlcommenter.create_sqlcommenter_statement_transformer(*, attributes=None, enable_traceparent=False, enable_context=False)

Create a statement_transformer that adds sqlcommenter comments to the AST.

Static attributes are pre-serialized at creation time. When enable_traceparent or enable_context is True, dynamic attributes are resolved per invocation.

Parameters:

• attributes (dict[str, str | None] | None) -- Static key-value pairs to include in every comment.

• enable_traceparent (bool) -- If True, auto-populate traceparent from the current OpenTelemetry span context on each invocation.

• enable_context (bool) -- If True, read request-scoped attributes from SQLCommenterContext and merge them with static attributes.

Return type:

Callable[[Expr, Any], tuple[Expr, Any]]

Returns:

A callable suitable for StatementConfig(statement_transformers=[...]).