Report through logging instead of print()

[mmacferrin]

Closes #6.

Replaces IVERT's print() output with the standard logging module, so output can be filtered, redirected or silenced at runtime rather than only by wrapping the process. --verbosity debug|info|warning|error (and the verbosity config setting) already chose a level; it now actually governs the validation output, which was previously printed unconditionally.

Scope

The issue was written a while ago and is stale in places: it points at src/client.py, which no longer exists, and its item 4 — have the CLI configure the root logger — was already done. cli.py had --verbosity, a config default, and no prints.

The scope is also smaller than a raw grep suggests: all 37 "prints" in utils/cuboid_funcs.py sit inside commented-out dead code. That leaves 131 live statements, now 146 logger calls across 16 modules.

The part worth reviewing carefully

validate_dem() always runs its work in a spawn-started child process, and ~50 of that file's prints execute inside it. A spawned child inherits no logging configuration from its parent, so a mechanical print→logging swap would have silently dropped nearly all validation output at default verbosity — everything below WARNING falls through to logging's last-resort handler.

I checked this empirically rather than assuming it:

case	result
spawned child without the level handoff	only WARNING arrives — INFO lost
spawned child with the handoff at INFO	INFO + WARNING:-prefixed warning
spawned child with the handoff at DEBUG	all three levels, each labelled
via LoggerProc	logfile captured the records

The parent's level rides across in the worker's kwargs and configure_worker_logging() reinstates it as the child's first act. The handler is rebuilt there rather than reused: LoggerProc replaces sys.stdout/sys.stderr before calling its target, and a StreamHandler binds whichever stream it was constructed against — reusing one would have sent job output to the real terminal instead of the logfile.

Verifying the messages didn't change

Rather than eyeball 131 conversions, I rendered each original print() and its replacement with identical placeholder tokens and diffed them: 70 identical, and every one of the 46 differences is intentional —

• 10 literal WARNING:/ERROR: prefixes removed, because a formatter now supplies them (so terminal output is unchanged; info stays bare, warning+ gets labelled, and debug labels everything)
• 8 "Reading X ..." / "done." progress pairs collapsed into 5 completed-action records, since a log record is a whole line
• print(e) folded into logger.exception, which now carries the traceback

The two messages I restructured by hand were checked to render byte-identically at runtime.

Ruff runs select = ["ALL"], so G002/G003/G004 are live: every call uses lazy %s arguments, never f-strings. Thousands separators pass a pre-formatted argument, e.g. logger.info("%s cells", f"{n:,}").

Breaking change

The verbose parameter is gone from the validation API, since log levels now do its job. validate_dem(), validate_dem_parallel(), validate_list_of_dems(), write_summary_stats_file(), export_error_results(), IS2Database.open_gdf() and 19 others no longer accept it, and cli.py no longer translates a log level back into a boolean to pass down. Callers that passed verbose= should drop the argument and set the log level instead; passing it now raises TypeError. The external transformez.generate_grid(verbose=False) call is untouched.

A latent bug this surfaced

In _compute_photon_overlap(), the early return None for a DEM with no land cells sat inside the if verbose: block — so it only fired when verbose was on. The check immediately after it returns anyway, so the outcome is unchanged, but it no longer depends on the verbosity setting.

Lint

T201 (print) comes off the Ruff ignore list, which keeps this from regressing and continues #40. The 7 remaining prints are the ones whose output is the result rather than a report about it — a tabulate table, the is_aws/is_conda helpers whose whole purpose as scripts is the value they write to stdout, and loggerproc's self-test, whose prints are the fixture under test. Each carries a # noqa: T201 and a comment saying why. The convention is written up in CONTRIBUTING.md.

Checks

prek run --all-files passes, every module still imports, the CLI works, and --verbosity error correctly suppresses a config warning that appears at the default level.

Unrelated and pre-existing, not touched here: ivert.utils.list_photon_tiles imports a removed ivert.s3 module and fails to import on main too. Probably worth its own issue.

---

🔍 Docs preview: https://ivert--101.org.readthedocs.build/en/101/