[aka-bo]

Problem

set_log_hook installed its sink at warn with no way to change it, so debug and info records from the Rust core (key loads and creations, metastore calls, per-region KMS failure detail) could not be observed from Python. The Python docs also described a set_log_hook_sync(..., min_level=...), which asherah-py does not provide.

Change

• set_log_hook(callback, min_level=None) accepts "error", "warn" (or "warning"), "info", "debug" and "trace", case-insensitively. The default is warn.
• An unknown string raises ValueError and a non-string raises TypeError, in both cases before the installed hook is touched.
• The level is applied to both the async dispatcher, which drives log::max_level, and the inner sink.
• The type stub, README and the getting-started, aws-production-setup, testing and troubleshooting guides now describe the real API. The examples that expected debug events from a default hook install it at min_level="debug", and getting-started no longer mentions synchronous hook variants.

Behavior changes

None for existing callers. callback remains required, as on main; passing None still clears the hook; the default level is still warn.

Scope

Python binding only. Stacked on the KMS error-message PR (#400).

Out of scope: a min_level option for the Node and Java log hooks, which are also fixed at warn.

Tests

In asherah-py/tests/test_hooks.py:

• test_log_hook_min_level_debug_delivers_debug_records: the default hook receives only warn and error records during an encrypt; with min_level="debug" debug records arrive and trace records do not.
• test_log_hook_invalid_min_level_raises_value_error: unknown names (empty, "verbose", "critical") raise ValueError listing the accepted values, a non-string raises TypeError, and "WARNING" is accepted.
• test_log_hook_callback_is_required_and_rejected_calls_keep_the_hook: set_log_hook() raises TypeError, and calls rejected for a missing callback or a bad level leave the installed debug hook receiving events.

A Rust unit test covers the level-name parsing, including case, warning and rejected names such as off.

🤖 Generated with Claude Code