pytest-dev
Class diagram
All of the Hook* classes are somewhat confusing to me, and I always have to rediscover how they relate. So I created an ASCII diagram of it. I think it's worth shoving in a comment somewhere, or in some "architecture" document. I'll use this issue as a placeholder for that.
┌──────────┐
│ HookSpec │
└──────────┘
▲ plugin1 ┌────────┐
│ ┌──────────────►│HookImpl│
│ │ └────────┘
foo_hook1 ┌─────┴──┴─┐
┌──────────┤HookCaller├───►...
│ └────────┬─┘
│ │ ┌────────┐
│ └──────────────►│HookImpl│
│ plugin2 └────────┘
┌─────────────┐ pm.hook ┌───────┴─┐
│PluginManager├──────────►│HookRelay├───►...
└─────────────┘ └───────┬─┘
│ plugin2 ┌────────┐
│ ┌───────────────►│HookImpl│
│ │ └────────┘
│ ┌───────┴──┐
└─────────►│HookCaller├───►...
foo_hook2 └─────┬─┬──┘
│ │ ┌────────┐
│ └───────────────►│HookImpl│
▼ plugin3 └────────┘
┌──────────┐
│ HookSpec │
└──────────┘
Just saw this https://github.com/github/roadmap/issues/372 which is similar to planetuml, I might try it.
Leaving their example here to see when it actually works :)
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
All of the Hook* classes are somewhat confusing to me, and I always have to rediscover how they relate. So I created an ASCII diagram of it. I think it's worth shoving in a comment somewhere, or in some "architecture" document. I'll use this issue as a placeholder for that.
┌──────────┐ │ HookSpec │ └──────────┘ ▲ plugin1 ┌────────┐ │ ┌──────────────►│HookImpl│ │ │ └────────┘ foo_hook1 ┌─────┴──┴─┐ ┌──────────┤HookCaller├───►... │ └────────┬─┘ │ │ ┌────────┐ │ └──────────────►│HookImpl│ │ plugin2 └────────┘ ┌─────────────┐ pm.hook ┌───────┴─┐ │PluginManager├──────────►│HookRelay├───►... └─────────────┘ └───────┬─┘ │ plugin2 ┌────────┐ │ ┌───────────────►│HookImpl│ │ │ └────────┘ │ ┌───────┴──┐ └─────────►│HookCaller├───►... foo_hook2 └─────┬─┬──┘ │ │ ┌────────┐ │ └───────────────►│HookImpl│ ▼ plugin3 └────────┘ ┌──────────┐ │ HookSpec │ └──────────┘
I was lucky to see this flowchart, which can be said to be a simple illustration of the core calling logic of pluggy. If you need to continue improving, or have something to help with, I'd be happy to do some！
Gave it a quick go, just to see if it has potential:
flowchart LR
PluginManager -.- pm.hook --> HookRelay
HookRelay -- foo_hook --> HookCaller --> HookSpec
HookRelay -- foo_hook2 --> HookCaller -- plugin1 --> HookImpl1
HookCaller -- plugin2 --> HookImpl2
Looks nice! https://mermaid-js.github.io/mermaid
Thanks for converting @nicoddemus!
It does lose some details - namely it merges the nodes when it's better not, the placing of the HookSpec and the .... Maybe this can be added in though. I'll need to learn the mermaid syntax.
[off topic] Is it possible that we use a class structure like this? Or are there specialised intentions? I mean, the HookRelay class seemed meaningless to me...
┌──────────┐
│ HookSpec │
└──────────┘
▲ plugin1 ┌────────┐
│ ┌──────────────►│HookImpl│
│ │ └────────┘
pm.hook1 ┌─────┴──┴─┐
┌──────────┤HookCaller├───►...
│ └────────┬─┘
│ │ ┌────────┐
│ └──────────────►│HookImpl│
│ plugin2 └────────┘
┌─────────────┐ |
│PluginManager|-----|
└─────────────┘ |
│ plugin2 ┌────────┐
│ ┌───────────────►│HookImpl│
│ │ └────────┘
│ ┌───────┴──┐
└─────────►│HookCaller├───►...
pm.hook2 └─────┬─┬──┘
│ │ ┌────────┐
│ └───────────────►│HookImpl│
▼ plugin3 └────────┘
┌──────────┐
│ HookSpec │
└──────────┘
@CofinCup HookRelay does seem redundant but I think the main problem it solves is that hook names don't conflict with PluginManager method/attribute names.