djblets.db.query_catcher¶

Utilities for capturing and inspecting database queries.

class 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.

__annotations__ = {'deleted_objects': 'Mapping[int, Any]', 'executed_queries': 'Sequence[ExecutedQueryInfo]', 'queries_to_qs': 'Dict[SQLQuery, Q]'}¶

__dataclass_fields__ = {'deleted_objects': Field(name='deleted_objects',type='Mapping[int, Any]',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'executed_queries': Field(name='executed_queries',type='Sequence[ExecutedQueryInfo]',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'queries_to_qs': Field(name='queries_to_qs',type='Dict[SQLQuery, Q]',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)}¶

__dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False)¶

__eq__(other)¶

Return self==value.

__hash__ = None¶

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

__match_args__ = ('deleted_objects', 'executed_queries', 'queries_to_qs')¶

__repr__()¶

Return repr(self).

class 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.

__annotations__ = {'query': ForwardRef('SQLQuery', module='django_assert_queries.query_catcher'), 'result_type': ForwardRef("Literal['query']", module='django_assert_queries.query_catcher'), 'sql': ForwardRef('List[str]', module='django_assert_queries.query_catcher'), 'subqueries': ForwardRef('List[ExecutedSubQueryInfo]', module='django_assert_queries.query_catcher'), 'traceback': ForwardRef('List[str]', module='django_assert_queries.query_catcher'), 'type': ForwardRef('ExecutedQueryType', module='django_assert_queries.query_catcher')}¶

__closed__ = None¶

__extra_items__ = typing_extensions.NoExtraItems¶

__mutable_keys__ = frozenset({'query', 'result_type', 'sql', 'subqueries', 'traceback', 'type'})¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (typing_extensions.TypedDict,)¶

__readonly_keys__ = frozenset({})¶

__required_keys__ = frozenset({'query', 'result_type', 'sql', 'subqueries', 'traceback', 'type'})¶

__total__ = True¶

class 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 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[Union[AggregateQuery, QuerySet, Subquery]]¶

The type of class managing the subquery.

instance: Union[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: SELECT: 'SELECT'>]¶

The type of executed query.

__annotations__ = {'cls': ForwardRef('Type[Union[AggregateQuery, QuerySet, Subquery]]', module='django_assert_queries.query_catcher'), 'instance': ForwardRef('Union[AggregateQuery, QuerySet, Subquery]', module='django_assert_queries.query_catcher'), 'query': ForwardRef('SQLQuery', module='django_assert_queries.query_catcher'), 'result_type': ForwardRef("Literal['subquery']", module='django_assert_queries.query_catcher'), 'subqueries': ForwardRef('List[ExecutedSubQueryInfo]', module='django_assert_queries.query_catcher'), 'type': ForwardRef('Literal[ExecutedQueryType.SELECT]', module='django_assert_queries.query_catcher')}¶

__closed__ = None¶

__extra_items__ = typing_extensions.NoExtraItems¶

__mutable_keys__ = frozenset({'cls', 'instance', 'query', 'result_type', 'subqueries', 'type'})¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (typing_extensions.TypedDict,)¶

__readonly_keys__ = frozenset({})¶

__required_keys__ = frozenset({'cls', 'instance', 'query', 'result_type', 'subqueries', 'type'})¶

__total__ = True¶

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.