djblets.db.query_catcher¶

Utilities for capturing and inspecting database queries.

class ExecutedQueryType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: str, Enum

A type of executed query that can be inspected.

New in version 3.4.

DELETE = 'DELETE'[source]¶

A DELETE query.

INSERT = 'INSERT'[source]¶

An INSERT query.

SELECT = 'SELECT'[source]¶

A SELECT query.

UPDATE = 'UPDATE'[source]¶

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 ExecutedQueryInfo[source]¶

Bases: TypedDict

Information on an executed query.

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

New in version 3.4.

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='djblets.db.query_catcher'), 'result_type': ForwardRef("Literal['query']", module='djblets.db.query_catcher'), 'sql': ForwardRef('List[str]', module='djblets.db.query_catcher'), 'subqueries': ForwardRef('List[ExecutedSubQueryInfo]', module='djblets.db.query_catcher'), 'traceback': ForwardRef('List[str]', module='djblets.db.query_catcher'), 'type': ForwardRef('ExecutedQueryType', module='djblets.db.query_catcher')}¶

__closed__ = False¶

__extra_items__ = None¶

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

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__readonly_keys__ = frozenset({})¶

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

__total__ = True¶

class ExecutedSubQueryInfo[source]¶

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.

New in version 3.4.

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='djblets.db.query_catcher'), 'instance': ForwardRef('Union[AggregateQuery, QuerySet, Subquery]', module='djblets.db.query_catcher'), 'query': ForwardRef('SQLQuery', module='djblets.db.query_catcher'), 'result_type': ForwardRef("Literal['subquery']", module='djblets.db.query_catcher'), 'subqueries': ForwardRef('List[ExecutedSubQueryInfo]', module='djblets.db.query_catcher'), 'type': ForwardRef('Literal[ExecutedQueryType.SELECT]', module='djblets.db.query_catcher')}¶

__closed__ = False¶

__extra_items__ = None¶

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

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__readonly_keys__ = frozenset({})¶

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

__total__ = True¶

class CatchQueriesContext(executed_queries: Sequence[ExecutedQueryInfo], queries_to_qs: Dict[Query, Q])[source]¶

Bases: object

Context for captured query information.

This is provided and populated when using catch_queries().

New in version 3.4.

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__ = {'executed_queries': 'Sequence[ExecutedQueryInfo]', 'queries_to_qs': 'Dict[SQLQuery, Q]'}¶

__dataclass_fields__ = {'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,match_args=True,kw_only=False,slots=False,weakref_slot=False)¶

__eq__(other)¶

Return self==value.

__hash__ = None¶

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

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

__repr__()¶

Return repr(self).

catch_queries(*, _check_subqueries: bool = True) → Iterator[CatchQueriesContext][source]¶

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.

To use this, kgb must be installed.

New in version 3.4.

Parameters:

_check_subqueries (bool, optional) –

Whether to check subqueries.

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

Context:

CatchQueriesContext – The context populated with query information.