Debug Utilities

Debug and diagnostic utilities for NextORM.

Provides SQL debug logging and per-instance / global query statistics.

Example:

from nextorm import set_sql_debug, sql_debugging

set_sql_debug(True)
results = db.select(User).fetch_all()
# prints: >>> SELECT id, name FROM "user"
#           params: []

with sql_debugging():
    result = db.select(User).filter(User.id == 1).fetch_one()
nextorm.debug.set_sql_debug(debug=True)[source]

Enable or disable global SQL debug logging.

When enabled, every SQL statement executed by Database or AsyncDatabase is printed to stdout before execution. Use sql_debugging as a context manager for scoped temporary debugging.

Parameters

debug:

True to enable (default), False to disable.

Parameters:

debug (bool)

Return type:

None

class nextorm.debug.sql_debugging[source]

Bases: object

Context manager that temporarily enables SQL debug output.

On exit the previous debug state is restored, regardless of exceptions:

with sql_debugging():
    users = db.select(User).fetch_all()
# debug logging is off again here
__init__()[source]
Return type:

None

class nextorm.debug.QueryStat[source]

Bases: object

Per-query-string execution statistics.

Attributes

count:

Number of times the query was executed.

sum_time:

Total execution time in seconds.

min_time:

Minimum single execution time (inf when count is 0).

max_time:

Maximum single execution time in seconds.

avg_time:

Average execution time in seconds (computed property).

count: int = 0
sum_time: float = 0.0
min_time: float = inf
max_time: float = 0.0
property avg_time: float

Average execution time in seconds.

__init__(count=0, sum_time=0.0, min_time=inf, max_time=0.0)
Parameters:
Return type:

None

nextorm.debug.global_stats: dict[str, QueryStat] = {}

Module-level global query statistics.

Populated by merge_local_stats(); cleared by clear_global_stats().

nextorm.debug.clear_global_stats()[source]

Clear the module-level global_stats dictionary.

Return type:

None