infer_or_check_handler_id#
- penzai.data_effects.effect_base.infer_or_check_handler_id(tag: str, subtree: Any, explicit_id: str | None = None, min_hash_length: int = 5) HandlerId[source]#
Tries to generate a unique handler ID from the structure of a subtree.
Each handler in Penzai’s effect system needs to have a unique ID that identifies which effects it is responsible for handling. Since effect requests and effect handlers are both PyTree nodes that appear inside the PyTree structure, we can generate handler IDs by hashing the structure of the subtree, which should almost always result in a unique ID for each handler. (Failing this would mean there exists a hash such that hashing that hash inside its structure yields the structure again.)
- Parameters:
tag – User-readable tag for this handler ID. Mostly to help identify what kind of handler this is for debugging purposes.
subtree – Subtree with effects that is being wrapped by the effect handler.
explicit_id – An explicit ID requested by the user. We will use this if provided and if it does not already appear in the structure.
min_hash_length – Minimum number of hash characters to append to try to make IDs unique. Note that we may append more characters as needed to ensure uniqueness.
- Returns:
A unique handler ID which does not already appear in this structure.
- Raises:
RuntimeError – If there is a hash collision, and increasing the length of the hash did not resolve the collision.
ValueError – If there was an explicit ID provided, but it conflicts with an existing ID in the model.