Skip to content

Commit 15d2a67

Browse files
committed
Improve docstring, comments in test_debug()
1 parent ec3b89f commit 15d2a67

File tree

1 file changed

+33
-15
lines changed

1 file changed

+33
-15
lines changed

message_ix_models/tests/model/transport/test_build.py

+33-15
Original file line numberDiff line numberDiff line change
@@ -240,6 +240,7 @@ def _join_levels(df):
240240
return True, "LDV input satisfies conditions"
241241

242242

243+
#: Inline checks for :func:`.test_debug`.
243244
CHECKS: dict["KeyLike", Collection["Check"]] = {
244245
"broadcast:t-c-l:transport+input": (HasUnits("dimensionless"),),
245246
"broadcast:t-c-l:transport+output": (
@@ -345,37 +346,54 @@ def _join_levels(df):
345346
),
346347
)
347348
def test_debug(
348-
test_context,
349-
tmp_path,
350-
build_kw,
351-
N_node,
352-
verbosity: Literal[0, 1, 2, 3] = 0, # NB Increase this to show more verbose output
349+
test_context, tmp_path, build_kw, N_node, *, verbosity: Literal[0, 1, 2, 3] = 0
353350
):
354-
"""Debug particular calculations in the transport build process."""
351+
"""Check and debug particular steps in the transport build process.
352+
353+
By default, this test applies all of the :data:`.CHECKS` using
354+
:func:`.insert_checks` and then runs the entire build process, asserting that all
355+
the checks pass.
356+
357+
It can also be used by uncommenting and adjusting the lines marked :py:`# DEBUG` to
358+
inspect the behaviour of a sub-graph of the :class:`.Computer`. Such changes
359+
**should not** be committed.
360+
361+
Parameters
362+
----------
363+
verbosity : int
364+
Adjust to show more verbose output:
365+
366+
0. Don't log anything
367+
1. Log 7 values at the start/end of each quantity.
368+
2. Log *all* data. This produces large logs; more than 1 GiB of text.
369+
3. Dump all data to files in `tmp_path`.
370+
"""
355371
# Get a Computer prepared to build the model with the given options
356372
c, info = configure_build(test_context, tmp_path=tmp_path, **build_kw)
357373

358374
# Construct a list of common checks
359-
verbose: dict[int, list["Check"]] = {
360-
0: [], # Don't log anything.
361-
1: [Log()], # Log 7 lines at the start/end of each quantity.
362-
2: [Log(None)], # Log *all* data. This is produces GHA logs >1 GiB.
363-
3: [Dump(tmp_path)], # Dump all data to a file.
364-
}
365-
common = [Size({"n": N_node}), NoneMissing()] + verbose[verbosity]
375+
v: dict[int, list] = {0: [], 1: [Log()], 2: [Log(None)], 3: [Dump(tmp_path)]}
376+
common = [Size({"n": N_node}), NoneMissing()] + v[verbosity]
366377

367378
# Insert key-specific and common checks
368379
k = "test_debug"
369380
result = insert_checks(c, k, CHECKS, common)
370381

371-
# Show and get a different key
382+
# DEBUG Show and compute a different key
372383
# k = key.pdt_cny
373384

374385
# Show what will be computed
386+
# verbosity = True # DEBUG Force printing the description
375387
if verbosity:
376388
print(c.describe(k))
377389

390+
# return # DEBUG Exit before doing any computation
391+
378392
# Compute the test key
379-
c.get(k)
393+
tmp = c.get(k)
394+
395+
# DEBUG Handle a subset of the result for inspection
396+
# print(tmp)
380397

381398
assert result, "1 or more checks failed"
399+
del tmp

0 commit comments

Comments
 (0)