aa540581aa598fcb34d91aaff4234c2213e3413e
[mdis.git] / README.md
1 # About this project
2
3 The mdis module allows to quickly extend the classes with the required functionality without modifications inside these classes.
4 This is done via double dispatch pattern: the dispatcher describes the required action based on the the argument type.
5 Use cases mainly include visitors and iterators, but are not limited to them.
6
7 # Dispatchers
8
9 The key concept of this module is dispatcher. A dispatcher object is a callable object; the exact call logic depends on the type of the argument.
10 The main class, `mdis.dispatcher.Dispatcher`, can register per-type hooks, which modify the call logic depending on the argument.
11 The hook is registered on a dispatcher class level as a method; attempts to call a dispatcher determine the relevant hooks based on argument type.
12
13 # Walkers
14
15 Sometimes objects of different types need to be traversed, but either lack `__iter__` method, or its semantics differs from what the users want.
16 For example, let's consider a nested collection, consisting of tuples, dicts and other types.
17 `dict.__iter__` method yields just keys, and the values have to be got via `__getitem__` calls.
18 Also, in order to support nested collections, users will have to write some recursive code with `isinstance` checks.
19 With `mdis.Walker`, users can just install the handlers for the types of interest, and change the iteration logic.
20 A walker is just a particular example of dispatcher, where the call yields some objects in a class-dependent manner.
21 The default `mdis.Walker` already incorporates the logic to walk over some builtin Python objects.
22 The example below shows how to override the way the dicts are traversed so that keys and values are swapped.
23
24 import mdis.dispatcher
25 import mdis.walker
26
27 class CustomWalker(mdis.walker.Walker):
28 @mdis.dispatcher.hook(dict)
29 def dispatch_dict(self, instance):
30 for (key, value) in instance.items():
31 yield (value, key)
32 yield from self((value, key))
33
34 collection = {"a": 1, "b": 2}
35 walker = CustomWalker()
36 for item in walker(collection):
37 print(item)
38
39 The following output is expected:
40
41 (1, 'a')
42 1
43 a
44 (2, 'b')
45 2
46 b
47
48 # Visitors
49
50 In `mdis`, a visitor is just another particular example of dispatcher.
51 Whenever the visitor is called, the call is dispatched based on type, and some per-class action is performed.
52 The primary scenario is to combine the visitor calls with context managers.
53 The example below shows how to execute some arbitrary code upon visiting an object.
54
55 import contextlib
56
57 import mdis.dispatcher
58 import mdis.visitor
59
60 class CustomVisitor(mdis.visitor.ContextVisitor):
61 @mdis.dispatcher.hook(int)
62 @contextlib.contextmanager
63 def dispatch_int(self, instance):
64 print("entering int")
65 yield (instance + 42)
66 print("leaving int")
67
68 @mdis.dispatcher.hook(str)
69 @contextlib.contextmanager
70 def dispatch_str(self, instance):
71 print("entering str")
72 yield f"!!!{instance}!!!"
73 print("leaving str")
74
75 @mdis.dispatcher.hook(object)
76 @contextlib.contextmanager
77 def dispatch_object(self, instance):
78 print("entering object")
79 yield instance
80 print("leaving object")
81
82 visitor = CustomVisitor()
83 for item in (42, "cocojamboo", 1.5):
84 with visitor(item) as result:
85 print(result)
86
87 The following output is expected:
88
89 entering int
90 84
91 leaving int
92 entering str
93 !!!cocojamboo!!!
94 leaving str
95 entering object
96 1.5
97 leaving object