django_assert_queries.query_catcher

Utilities for capturing and inspecting database queries.

New in version 1.0.

Functions

catch_queries(*[, _check_subqueries])

Catch queries and provide information for further inspection.

Classes

CatchQueriesContext(deleted_objects, ...)	Context for captured query information.
ExecutedQueryInfo	Information on an executed query.
ExecutedQueryType(value[, names, module, ...])	A type of executed query that can be inspected.
ExecutedSubQueryInfo	Information on a subquery within an executed query.

class django_assert_queries.query_catcher.ExecutedQueryType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

A type of executed query that can be inspected.

New in version 1.0.

DELETE = 'DELETE'

A DELETE query.

INSERT = 'INSERT'

An INSERT query.

SELECT = 'SELECT'

A SELECT query.

UPDATE = 'UPDATE'

An UPDATE query.

__format__(format_spec)

Return a formatted version of the string as described by format_spec.

__new__(value)

__repr__()

Return repr(self).

__str__()

Return str(self).

class django_assert_queries.query_catcher.ExecutedQueryInfo

Bases: TypedDict

Information on an executed query.

This contains information seen at execution time that can be used for inspection of the queries.

This should not be populated by consumers, only by this library.

New in version 1.0.

query: Query

The query that was executed.

result_type: Literal['query']

The type of result information.

This is used to distinguish between query and subquery information.

sql: List[str]

The list of lines of SQL that was executed.

subqueries: List[ExecutedSubQueryInfo]

Any subqueries within this query, in the orders found.

traceback: List[str]

The lines of traceback showing where the query was executed.

type: ExecutedQueryType

The type of executed query.

class django_assert_queries.query_catcher.ExecutedSubQueryInfo

Bases: TypedDict

Information on a subquery within an executed query.

This contains information seen at execution time that can be used for inspection of the queries.

This should not be populated by consumers, only by this library.

New in version 1.0.

cls: Type[AggregateQuery | QuerySet | Subquery]

The type of class managing the subquery.

instance: AggregateQuery | QuerySet | Subquery

The instance of the subquery class.

query: Query

The query that was executed.

result_type: Literal['subquery']

The type of result information.

This is used to distinguish between query and subquery information.

subqueries: List[ExecutedSubQueryInfo]

Any subqueries within this query, in the orders found.

type: Literal[ExecutedQueryType.SELECT]

The type of executed query.

class django_assert_queries.query_catcher.CatchQueriesContext(deleted_objects: Mapping[int, Any], executed_queries: Sequence[ExecutedQueryInfo], queries_to_qs: Dict[Query, Q])

Bases: object

Context for captured query information.

This is provided and populated when using catch_queries().

This should not be populated by consumers, only by this library.

New in version 1.0.

deleted_objects: Mapping[int, Any]

A mapping of deleted instance IDs to their original primary keys.

New in version 2.0.

executed_queries: Sequence[ExecutedQueryInfo]

Information on the queries that were executed.

queries_to_qs: Dict[Query, Q]

A mapping of SQL queries to their Q expressions.

__eq__(other)

Return self==value.

__hash__ = None

__init__(deleted_objects: Mapping[int, Any], executed_queries: Sequence[ExecutedQueryInfo], queries_to_qs: Dict[Query, Q]) → None

__repr__()

Return repr(self).

django_assert_queries.query_catcher.catch_queries(*, _check_subqueries: bool = True) → Iterator[CatchQueriesContext]

Catch queries and provide information for further inspection.

Any database queries executed during this context will be captured and provided in the context. For each query, this will capture:

1. The type of query.

2. The SQL Query objects

3. The generated SQL statements

4. Tracebacks showing where the SQL was executed.

It will also provide a mapping of the Query objects to their Q expressions.

New in version 1.0.

Parameters:

_check_subqueries (bool, optional) –

Whether to check subqueries.

This is internal for compatibility with the old behavior for assert_queries>() and will be removed in a future release without a deprecation period.

Context:

CatchQueriesContext – The context populated with query information.