@@ -42,6 +42,103 @@ The architecture supports multiple usage strategies:
4242* It's possible to register callback to `.ANY` event from particular source, or particular
4343 event from `.ANY` source, or even to `.ANY` event from `.ANY` source.
4444
45+ Example
46+ =======
47+
48+ .. code-block:: python
49+
50+ from __future__ import annotations
51+ from enum import Enum, auto
52+ from firebird.base.types import *
53+ from firebird.base.hooks import hook_manager
54+
55+ class MyEvents(Enum):
56+ "Sample definition of events"
57+ CREATE = auto()
58+ ACTION = auto()
59+
60+ class MyHookable:
61+ "Example of hookable class, i.e. a class that calls hooks registered for events."
62+ def __init__(self, name: str):
63+ self.name: str = name
64+ for hook in hook_manager.get_callbacks(MyEvents.CREATE, self):
65+ try:
66+ hook(self, MyEvents.CREATE)
67+ except Exception as e:
68+ print(f"{self.name}.CREATE hook call outcome: ERROR ({e.args[0]})")
69+ else:
70+ print(f"{self.name}.CREATE hook call outcome: OK")
71+ def action(self):
72+ print(f"{self.name}.ACTION!")
73+ for hook in hook_manager.get_callbacks(MyEvents.ACTION, self):
74+ try:
75+ hook(self, MyEvents.ACTION)
76+ except Exception as e:
77+ print(f"{self.name}.ACTION hook call outcome: ERROR ({e.args[0]})")
78+ else:
79+ print(f"{self.name}.ACTION hook call outcome: OK")
80+
81+ class MyHook:
82+ "Example of hook implementation"
83+ def __init__(self, name: str):
84+ self.name: str = name
85+ def callback(self, subject: MyHookable, event: MyEvents):
86+ print(f"Hook {self.name} event {event.name} called by {subject.name}")
87+ def err_callback(self, subject: MyHookable, event: MyEvents):
88+ self.callback(subject, event)
89+ raise Exception("Error in hook")
90+
91+
92+ # Example code that installs and uses hooks
93+
94+ hook_manager.register_class(MyHookable, MyEvents)
95+ hook_A: MyHook = MyHook('Hook-A')
96+ hook_B: MyHook = MyHook('Hook-B')
97+ hook_C: MyHook = MyHook('Hook-C')
98+
99+ print("Install hooks")
100+ hook_manager.add_hook(MyEvents.CREATE, MyHookable, hook_A.callback)
101+ hook_manager.add_hook(MyEvents.CREATE, MyHookable, hook_B.err_callback)
102+ hook_manager.add_hook(MyEvents.ACTION, MyHookable, hook_C.callback)
103+
104+ print("Create event sources, emits CREATE")
105+ src_A: MyHookable = MyHookable('Source-A')
106+ src_B: MyHookable = MyHookable('Source-B')
107+
108+ print("Install instance hooks")
109+ hook_manager.add_hook(MyEvents.ACTION, src_A, hook_A.callback)
110+ hook_manager.add_hook(MyEvents.ACTION, src_B, hook_B.callback)
111+
112+ print("And action!")
113+ src_A.action()
114+ src_B.action()
115+
116+
117+ Output from sample code::
118+
119+ Install hooks
120+ Create event sources, emits CREATE
121+ Hook Hook-A event CREATE called by Source-A
122+ Source-A.CREATE hook call outcome: OK
123+ Hook Hook-B event CREATE called by Source-A
124+ Source-A.CREATE hook call outcome: ERROR (Error in hook)
125+ Hook Hook-A event CREATE called by Source-B
126+ Source-B.CREATE hook call outcome: OK
127+ Hook Hook-B event CREATE called by Source-B
128+ Source-B.CREATE hook call outcome: ERROR (Error in hook)
129+ Install instance hooks
130+ And action!
131+ Source-A.ACTION!
132+ Hook Hook-A event ACTION called by Source-A
133+ Source-A.ACTION hook call outcome: OK
134+ Hook Hook-C event ACTION called by Source-A
135+ Source-A.ACTION hook call outcome: OK
136+ Source-B.ACTION!
137+ Hook Hook-B event ACTION called by Source-B
138+ Source-B.ACTION hook call outcome: OK
139+ Hook Hook-C event ACTION called by Source-B
140+ Source-B.ACTION hook call outcome: OK
141+
45142
46143Functions
47144=========
0 commit comments