[00:01]
editor that has paragraphs, images, sections, all the types of nodes, and you need operations like HTML rendering, accessibility checks, asset collection, all the things. Now, the obvious design puts those operations on every node. And
[00:19]
that's fine, but now every node needs to know about all the operations: HTML, Markdown, accessibility, exporting, indexing, etc. So, you think, "Hey, let's be smart about it and let's move the operations outside of the nodes."
[00:34]
render HTML, that's a match statement, and for every type of node, it's going to render it. Well, that's great, but now every operation needs to know every now every operation needs to know every type of node, which uh is basically the
[00:49]
opposite version of exactly the same problem. So, are we screwed? Well, almost everyone is now, except for you, because you are watching this video, and I'm going to show you another way to solve this. By the way, if you
[01:04]
want to learn more about how to design a piece of software from scratch, I have a arne.codes/designguide. Contains the seven steps that I take hopefully helps you avoid some of the mistakes that I made in the past.
[01:19]
The link is also in the video description. So, let's go over these existing solutions. Here's the first one, where we simply have some methods that we add on the nodes. So, I have a paragraph, for example, here. It has to
[01:32]
HTML, it has accessibility issues, and it has collect assets. And same for the image, and same for the section. And if I add more types of nodes here, here is just three, then each of them is going to need all of these methods. And as you
[01:47]
For example, a paragraph doesn't have any accessibility issues. An image may have them if there is no alt text. And in terms of assets, a paragraph also does not asset, but an image does. And a
[02:01]
section delegates each of these operations recursively to its children. So, this code at the moment, well, it's pretty direct and readable, and it's also the right choice when the behavior belongs to the model, or let's say new
[02:16]
node types are very common, but new operations aren't. But, of course, if there are sometimes new types of operations that you want to add, then Let's say you want to add markdown export. That means every node in your
[02:31]
system needs a new method for that. What happens is that these nodes tend to happens is that these nodes tend to become a catalog of unrelated things that can happen to a document. The alternative is to drastically simplify
[02:43]
the nodes, they're just plain frozen data classes right here, and each operation is its own function. So, now we have render HTML, which gets a node, and we have accessibility issues, same thing, we have assets. And then,
[02:58]
basically, each of these functions has a match statement where we check which kind of thing we have, and then depending on that, we do something. Now, of course, these are simple return statements. You could also call other
[03:10]
functions here if you would like to do that. The advantage of this approach is that things like HTML rendering, accessibility, asset collection are all grouped in one place. And if the types of document nodes that you have are
[03:23]
pretty static, then this can actually be a very good approach. Right? Because you don't have to edit these functions all that often, because, well, these data models that you have written don't change all that often. But now, of
[03:36]
course, the trade-off is that if you have some new thing here, a new type of document node, maybe a code block or whatever, it means that now for each of these functions you need to add another case. Every operation gets a new case.
[03:50]
So, both of these options have their pros and cons. And before I show you another approach, I want to also show you the visitor pattern. Because this is actually pretty close to the second version that I have here, but it uses a
[04:04]
slightly different pattern. And I think it's a nice way to introduce the pattern to you. So, maybe you can use it in some of your own projects. What it does, the visitor pattern, is that it gives each operation an object. So, here, each
[04:18]
operation is a function, which well, it's arguably more Pythonic, but in the visitor pattern, you don't do that. You actually have an object. And then, each operation is then an object, and the node to operation contract is then
[04:32]
explicit. So, what happens in the visitor pattern is that we have this interface. Let's call that a document visitor. In this case, that's a protocol class. That's how I got this video needs a protocol class. And there, for each
[04:44]
type of node, we have a method. Visit paragraph, visit image, visit section. And each node then gets an accept method that gets one of these visitors and then
[04:56]
calls that particular method. And by the way, a nice thing about Python is that we have this modern generic syntax. And that lets our document visitor return a particular type that we want. For example, if I scroll down, I have HTML
[05:12]
renderer, which is a document visitor of type string, that actually returns string values. Whereas, the accessibility checker returns a list of pattern matching version, where we had functions that had pattern matching like
[05:28]
so, is that in the visitor pattern, these things are objects. Now, I think in modern Python, honestly, I prefer this type of syntax. I think overall, this is a bit shorter than the
[05:41]
classic visitor pattern. But, I still wanted to present the pattern to you. So, you have a better understanding of where it belongs in the solutions that we're considering today. So, just like with the pattern matching solution, if
[05:54]
add a new type of operation. You can simply add a new class, and then you simply add the various visit methods, and you're all set. And by the way, this is how you use that version. So, we have the document, and then we can call
[06:08]
accept on the document to accept various types of visitors to do something. This of the script. But just like with the pattern matching solution, if you need to add another node type, this is expensive cuz every
[06:21]
visitor may need another method. Now, what's the actual design problem here? There's basically two axes. We have document node types, and we have operations. So, these are, you could say, in a matrix, right? Where each
[06:34]
combination of these things leads to some sort of operation. The methods on node solution organizes the matrix by row. Each node owns everything we can do with it. Operations outside of the node organize it by columns. HTML and
[06:49]
accessibility checker owns accessibility. Methods make adding new node types easy. Column-oriented designs make adding a new operation easy. And visitor, in particular, fits system where the model is fairly stable, but
[07:04]
new operations keep appearing. So, when we think about this design problem as a matrix, it actually leads us to another solution. What we're essentially doing is we're choosing a function from two pieces of information, the node type and
[07:18]
the operation. And what's interesting in Python is that we can actually model this explicitly. Here's a third option. I have simple node types. A paragraph, I have an image, decorative image, etc. Then I have operation types. So, that's
[07:35]
HTML, accessibility, assets. You can add any other type you want here. And then, I have a handler function, which is something that takes a node and returns something that takes a node and returns a result. For example, HTML paragraph or
[07:50]
HTML image, HTML section, image accessibility, section accessibility, etc., etc. I even have some no-op functions, so no accessibility issues or no assets, for example. And then, what I have here is handlers, and this is
[08:05]
exactly the structure that we actually have. So, there's a tuple of a node type and operation. These are the two things, and that determines the handler. So, for example, for paragraph in HTML, I'm going to need this operation. For image
[08:20]
HTML, this is the one. For image accessibility, I need this function. And then, I can define defaults if some of these handlers are missing. For example, for uh paragraphs, there is no accessibility issue, so it's not in the
[08:35]
list of handlers, but there is a default. And same for assets. If something doesn't have assets, we can have a simple default operation like so. that, given a node and operation, it's going to look up which thing you're
[08:49]
going to need by going through these dictionaries. And then, we have apply function that does that and then calls that particular operation. So, if we run this version, then this is what we get as a result.
[09:02]
What we've achieved here is we've flattened this matrix that we had into a sequence that takes a node type and an operation and gives us a handler. And by doing that, there's now also an easy way to define default operations by simply
[09:18]
omitting them from the list of handlers and putting them in the defaults dictionary. Now, you might say, "Well, nice, this is an alternative solution, but it is a bit messy with all of these different dictionaries, and it's not
[09:31]
really something that you want to do." Which I also totally understand. But there's one more variety that I want to show you that actually gives you even more flexibility, and that this kind of uses Python's syntax to maintain this
[09:45]
matrix for us. And that's by using single dispatch. So, here's the fifth the last one. I'm going to stop after this. But again, we have very simple
[09:57]
an image, we have a section, just like before. And then I have my operations. I have uh render HTML, for example, which gets a node and then uh raises a type
[10:09]
error in this case because it can't render it at the moment. But then I'm using single dispatch to register various types of render functions, like this one for example, for paragraphs, or this one for images. This one for
[10:23]
sections. In essence, it's almost the same idea as what we had with the dictionary, except that here we're using Python's single dispatch to register all of these various operations. As you can see, I'm doing the same here for
[10:37]
accessibility, and it also allows us to specify a default like this. And then what we can do is if we want to render HTML, simply call that function, and single dispatch is going to make sure that the right version of the operation
[10:50]
is called depending on the node type. And same for accessibility issues. So, if we run this, well, then this is what we get. Interestingly, this does dictionary version that I showed you before. It can even recursively call, in
[11:07]
this case, accessibility issues on the children, or rendering the children HTML for a particular node. There's nothing here about visitors, we don't need objects or dictionaries. It's all handled by Python's internal single
[11:21]
dispatch mechanism. But overall, I really like the single dispatch if you have different models, different operations, and these things vary independently, single dispatch might be a good solution
[11:35]
for you. By the way, if this kind of Python design deep dive is useful, like the video, subscribe to my channel, and then hopefully you will become a regular visitor. So, you've seen a few options to handle this: methods on nodes,
[11:49]
dictionary that maps node type and operation to handlers, and single What do you think? Which one do you prefer? Have you used any of these Let me know in the comments. YouTube thinks you might like this video next.
[12:05]
Thanks for watching, and see you next time.