Ki7UdZddlmZddlZddlmZmZddlmZddl m Z m Z m Z m Z mZmZddlmZmZej&eZGd d eZed Gd dZeGddZGddeZeGddZGddZGddZdaded<ddZ d d!dZ d"dZ!d#dZ"y)$z Core hook system implementation.) annotationsN) dataclassfield)Enum)AnyCallableDictListOptionalProtocol)HookExecutionErrorHookRejectionErrorceZdZdZdZdZy)HookTypezHook execution timing types.prepostN)__name__ __module__ __qualname____doc__PREPOSTb/home/cursorai/projects/django-wallet-utils/venv/lib/python3.12/site-packages/django_hooks/core.pyrrs& C DrrT)frozenc8eZdZUdZded<eeZded<y) HookContexta Immutable context passed to hooks containing operation details. This is a base class that should be extended by specific implementations to add domain-specific fields. All operation parameters are frozen to prevent hooks from modifying them. Use the metadata dict to share data between hooks. Attributes: operation: The operation being performed (e.g., 'add', 'delete', 'execute') metadata: Mutable dictionary for inter-hook communication and data sharing Example: @dataclass(frozen=True) class CronjobHookContext(HookContext): job_id: str schedule: str command: str user_id: int str operation)default_factoryDict[str, Any]metadataN)rrrr__annotations__rdictr$rrrrrs,N$T:Hn:rrcDeZdZUdZded<ded<ded<ded<ded <y ) PostHookErrora Represents an error that occurred in a POST hook. POST hooks cannot reject operations, but their errors are captured and returned so they can be logged or displayed without affecting the operation's success. Attributes: hook_name: Name of the hook that raised the error error_code: Machine-readable error code (ALL_CAPS) message: Human-readable error message details: Additional error context exception: The original exception that was raised r hook_name error_codemessager#details Exception exceptionN)rrrrr%rrrr(r(2s$ NO L rr(ceZdZdZddZy) HookFunctionz3Protocol defining the signature for hook functions.cy)a Execute hook logic. Args: context: Immutable operation context with mutable metadata Returns: - For PRE hooks: True to continue, False to reject, or raise HookRejectionError - For POST hooks: Return value is ignored Raises: HookRejectionError: To reject operation with error code (PRE hooks only) Exception: Any other exception is wrapped in HookExecutionError Nr)selfcontexts r__call__zHookFunction.__call__Ms rN)r3rreturnz bool | None)rrrrr4rrrr0r0Js = rr0cHeZdZUdZded<ded<ded<ded<d Zd ed <y ) HookaW Represents a registered hook. Attributes: name: Unique identifier for the hook hook_type: When the hook executes (PRE or POST) operation: Which operation triggers this hook ('*' = all operations) callback: The function to execute priority: Execution order (lower number = higher priority) r namer hook_typer!r0callbackdintpriorityN)rrrrr%r=rrrr7r7_s)  INHcrr7cVeZdZdZdd dZ d d dZd dZd dZddZy) HookRegistrya Registry for managing hooks with priority support. Hooks are stored per operation type and executed by priority (lower = higher priority). Example: registry = HookRegistry(operations=['schedule', 'execute', 'pause', 'delete']) registry.register( name='check_permissions', hook_type=HookType.PRE, callback=check_permissions_func, operation='delete', priority=10 ) NcHdgi|_|r|D]}g|j|<yy)z Initialize hook registry. Args: operations: List of valid operation names. If None, defaults to ['*'] *N)_hooks)r2 operationsops r__init__zHookRegistry.__init__s./22Y  "$ B! rc ||jvr8td|ddj|jj|jj D]%}t fd|Dstddt ||||}|j|j||j|jd tjd |jd d |d |y)a Register a new hook. Args: name: Unique identifier for the hook hook_type: HookType.PRE or HookType.POST callback: Function to execute operation: Operation name or '*' for all operations priority: Execution priority (lower number = higher priority, default=100) Raises: ValueError: If operation is invalid or hook name already exists Example: registry.register( name="check_daily_limit", hook_type=HookType.PRE, callback=check_daily_limit_hook, operation="execute", priority=50, ) zInvalid operation: z. Must be one of: z, c3<K|]}|jk(ywNr8).0hr8s r z(HookRegistry.register..s15a166T>5szHook with name 'z' already registered)r8r9r!r:r=c2|j|jfSrHr=r8rKs rz'HookRegistry.register..s1::qvv2Frkeyz Registered z hook 'z' for operation 'z' with priority N) rB ValueErrorjoinkeysvaluesanyr7appendsortloggerinfovalue)r2r8r9r:r!r=hookshooks ` rregisterzHookRegistry.registers< DKK '%i[0B499T[[M]M]M_C`Bab  [['')E1511 #3D69M!NOO*   I%%d+ I##(F#G )//*'$7H Scdlcm n rc |jjD]K\}}|D]A}|j|k(s|j|tj d|d|dyMy)z Unregister a hook by name. Args: name: Hook name to remove Returns: True if hook was found and removed, False otherwise zUnregistered hook 'z' from operation ''TF)rBitemsr8removerZr[)r2r8r!r]r^s r unregisterzHookRegistry.unregistersh!% 1 1 3 Iu99$LL&KK"5dV;Mi[XY Z[ !4 rc|jj|g}|jjdg}||z}|Dcgc]}|j|k(s|}}|jd|Scc}w)a Get all hooks for a specific operation and type, sorted by priority. Args: operation: Operation name hook_type: HookType.PRE or HookType.POST Returns: List of hooks sorted by priority (lower number first) rAc2|j|jfSrHrNrOs rrPz(HookRegistry.get_hooks..sQZZ$8rrQ)rBgetr9rY)r2r!r9operation_hooks global_hooks all_hooksrKfiltereds r get_hookszHookRegistry.get_hooksss++//)R8{{sB/ $l2 (Ey!AKK9,DAyE  8 9 Fs A2A2c|jD]}|j|j!tjdy)z0Clear all registered hooks (useful for testing).zCleared all hooksN)rBclearrZr[)r2r!s rrnzHookRegistry.clears2I KK " ( ( *% '(rrH)rCzOptional[List[str]]rAr; r8r r9rr:r0r!r r=r<r5Noner8r r5bool)r!r r9rr5z List[Hook]r5rq) rrrrrEr_rdrlrnrrrr?r?ssc %$ 6 6 6  6  6  6  6 p$0)rr?c*eZdZdZdddZddZd dZy) HookManagera Manages hook execution for operations. Executes PRE hooks before operation (can reject) and POST hooks after (cannot reject). Example: manager = HookManager(registry) # Before operation context = MyHookContext(operation='delete', user_id=123) try: manager.execute_pre_hooks(context) except HookRejectionError as e: return {"error": e.error_code, "message": e.message} # Perform operation result = perform_operation() # After operation errors = manager.execute_post_hooks(context) return {"success": True, "post_hook_errors": errors} Nc*|xs t|_y)z Initialize hook manager. Args: registry: Hook registry to use. If None, uses global registry. N)r?registry)r2rxs rrEzHookManager.__init__s!2LN rc |jj|jtj}|D]}t j d|jd|j |j|}|durBtd|jjd|jd|jit j d|jd y#t$rt$r^}t jd|jd |d td |jdt||j||d}~wwxYw)a Execute all PRE hooks for the given operation. PRE hooks can reject the operation by: 1. Returning False 2. Raising HookRejectionError with error_code and message Args: context: Operation context Raises: HookRejectionError: If any hook rejects the operation HookExecutionError: If a hook fails unexpectedly zExecuting PRE hook '' for FHOOK_REJECTED_zOperation rejected by hook: r))r*r+r,z PRE hook '' completed successfully' failed with error: Texc_infoHook 'z' failed to execute: )r+r)original_exceptionN)rxrlr!rrrZdebugr8r:rupperr-errorrr )r2r3r]r^resultes rexecute_pre_hookszHookManager.execute_pre_hookss= ''(9(98<<HD LL/ {&ARAR@ST U w/U?,%3DIIOO4E3F#G">tyyk J!,dii 8  z$))4LMN &   z$))4I!MX\ ]($TYYK/DSVHM"ii'(  s*A:C''E9AEEc|jj|jtj}g}|D]f}t j d|jd|j |j|t j d|jdh|S#t$r}t jd|jd|jd|j|jt|j|j|j|j|Yd}~d}~wt $r}t j#d|jd |d |jt|jd d |jdt%|dt'|j(i|Yd}~d}~wwxYw)a Execute all POST hooks for the given operation. POST hooks cannot reject the operation. Errors are captured and returned so the operation remains successful but errors can be logged/displayed. Args: context: Operation context (typically with updated state after operation) Returns: List of errors that occurred in POST hooks (empty if all succeeded) zExecuting POST hook 'rzz POST hook 'r|z' tried to reject operation: z - )r)r*r+r,r.Nr}Tr~HOOK_EXECUTION_ERRORrz ' failed: exception_type)rxrlr!rrrZrr8r:rwarningr*r+rXr(r,r-rr typer)r2r3r]errorsr^rs rexecute_post_hookszHookManager.execute_post_hooksIs ''(9(98==I&(D LL0 6'BSBSATU V  g& {499+5MNO F 9& !$)),I!,,WZ[\[d[dZef !"&))#$<< ! ! "#   {499+5J1#NY] ^ !"&))#9"( :c!fX F!1473C3C D"#  s&,4B$$ G -BD55 G A>GG rH)rxOptional[HookRegistry])r3rr5rq)r3rr5zList[PostHookError])rrrrrErrrrrrvrvs.3,\3rrvr_global_registryc.t tatS)zd Get the global hook registry. Lazily initializes the global registry on first access. )rr?rrrget_global_registryrs'> rc>tj|||||y)aR Register a hook in the global registry. Args: name: Unique identifier for the hook hook_type: HookType.PRE or HookType.POST callback: Function to execute operation: Operation name or '*' for all operations priority: Execution priority (lower number = higher priority, default=100) Example: def check_quota(context: HookContext) -> bool: if context.metadata.get('count', 0) > 100: raise HookRejectionError( error_code="QUOTA_EXCEEDED", message="You have exceeded your quota limit" ) return True register_hook( name="quota_check", hook_type=HookType.PRE, callback=check_quota, operation="create", priority=10, ) N)rr_)r8r9r:r!r=s r register_hookrsD""4HiRrc4tj|S)z Unregister a hook from the global registry. Args: name: Hook name to remove Returns: True if hook was found and removed, False otherwise )rrdrIs runregister_hookrs  + +D 11rc4tjy)z>Clear all hooks from the global registry (useful for testing).N)rrnrrr clear_hooksrs!r)r5r?rorprrrt)#r __future__rlogging dataclassesrrenumrtypingrrr r r r exceptionsrr getLoggerrrZrrr(r0r7r?rvrr%rrrrrrrrs&"(@@>   8 $t $;;;6  . 8 *  &D)D)NBBL,0(/   "S "S"S"S "S  "S  "SJ 2"r