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