Markdown Linter - Pi Day Blues

Summary¶

In my last article, I talked about the reasoning and designs behind the Project Summarizer too that I use. In this article, I drift back to the PyMarkdown project for a while and talk about what is happening there.

Introduction¶

Things over here at my house have been a bit rocky professionally and personally. It is nothing serious and nothing that I cannot deal with given the proper time and mindset to deal with it. Just multiple things converging at the same time making life difficult for a while. As such, while I did want to make more progress with the Project Summarizer tool, the extra bandwidth in my personal life just was not there. Rather than try and force work on the tool and then not being happy with myself or my effort, I decided to bounce back to the PyMarkdown project and concentrate on familiar ground for a while.

What Is the Audience for This Article?¶

While detailed more eloquently in this article, my goal for this technical article is to focus on the reasoning behind my solutions, rather than the solutions themselves. For a full record of the solutions presented in this article, please consult the commits that occurred between 13 Feb 2022 and 13 Mar 2022.

State Of The Project¶

Wow… a whole month has passed and there have been a lot of minor changes here and there to the PyMarkdown project. While there are no new stellar features to report, I feel that the nested container testing is coming along. Granted, it is coming along slowly, but I can see that the progress in stability is worth the effort.

I guess that is why, during this weird time where multiple negative events seem to be hitting at the same, I find solace in this work. Do not get me wrong. The work itself is needed for the project. And it is creative, but it is also a very constrained problem space. Somewhat like a logical fuzzy blanket that I can use for a while.

For those that do not understand, let me try and explain it this way. Sometimes, when walking through our house, things can seem out of sort to me. When this happens, I look around for a handful of things that I can clean up in five or ten minutes that will have a decent impact on how I think the room looks. I might not clean everything up and I might just reorganize things to look cleaner, but that action helps me put my mind at ease. And for the record, the messiest room in our house is not my office, it is the kitchen followed closely by our dining room table.

In a similar fashion, I find that cleaning up code and making a project better helps me to clean up some of the “mess” in my mind. It is not the same thing, nor does it have the same level of impact. But still, it helps. Whether it is improving documentation, adding more specific scenarios tests, or cleaning up code that I was not happy with, it is all about leaving the project a bit better than when I found it. That is what helps me put my mind at ease.

Python, DataClasses, Typing, and Mypy¶

I have been learning and exploring in Python over the last five years. In that learning, I often find that the learning takes its own time and happens at the weirdest of times. And I just hit one of those learning “bumps”.

During the odd downtime in my professional job or in my personal projects, I browse various parts of the web. In some cases, it is to search for a better way to do something, and in other cases it is just about exploring. Either way, I often learn about interesting things that spark my creativity.

It was while I was working on research for another project that I came across a concept known as data classes. Covered more completely at the Python Docs Pages, the base concept behind dataclasses is a simple one. Instead of setting up a class like this:

class Point:
    def __init__(self, x, y):
        self.__x = x
        self.__y = y

    @property
    def x(self):
        return x

    @x_index.setter
    def x(self, value):
        self.__x = value

    @property
    def y(self):
        return y

    @y_index.setter
    def y(self, value):
        self.__y = value

you can set up a class like this:

from dataclasses import dataclass

@dataclass
class Point:
    x : int
    y : int

Even more interesting are the cases where you do not want those values to be changed. In that case, using @dataclass(frozen=True) will not generated any setters for the class.

To be clear, truly immutable objects in Python is not possible, but this language feature comes close to it. Knowing the design of the PyMarkdown project as I do, I thought dataclasses would be useful and started looking at them more in-depth.

Python Typing¶

My research flowed from dataclasses into one of the concepts that they introduced me to: Python Typing. In the dataclass example above, the variable is specified with a type that follows it. That type is what Python calls a “Type Hint” and simply supplies a hint as to what the developer thought that type should be. The Python interpreters do not do anything with that themselves, but tools such as Mypy use that information to check to see if each type usage lines up.

After reading the Mypy documentation, or at least a good handful of examples, I was hooked. There really is not a TL;DR on this, but here is my first take on it.

Type Hints are exactly as they sound, hints. In a normal Python interpreter, if the type hints do anything, they are essentially null operations. But with other tools, such as editors and Mypy, they provide extra type information that is used is various forms. For editors, this information is often used to show type information when the developer is changing a Python file. For Mypy, it evaluates assignments and parameters to ensure that the specified types suggested by the developer are being adhered to.

That is it. But in that lies its simplicity and usefulness. There is no switch in the Python interpreter that says “Thou shalt use type hints!” Instead, as things progress, I can add type hints to different classes as I have time. After I have added those type hints, Mypy will start checking assignments to and within those classes. And my VSCode editor will have extra type information to provide better information when I am editing the project files.

Where Does This Lead?¶

Over the course of the next few weeks, I am going to try and add in Type Hints where I can and see how that goes. I have already transformed a handful of data-only classes into dataclasses, and that went off without any fuss. I am plodding along with resolving the parsing issues, but I am “plodding” at a good pace.

One thing that I have noticed is that it has been over a month since the last incremental release. My current plan is that once I hit a solid wall with any remaining issues, I am going to make sure things are clean and get that next incremental release out. I know I still have more scenario tests to add and test, but the fixes from the last month are decent and need to be published so that users can receive fixes for those issues.

I wish that I had the extra bandwidth to be creative and work on the Project Summarizer tool, but I acknowledge that my head is just not currently in the right space for that. But that doesn’t mean I cannot still be productive!

What is Next?¶

I am hoping that things start settling down in my life in the next week or two. But a lot of that is currently out of my control. I am dealing with it at a good pace, just a decent number of things to figure out and deal with. So, to be honest, I am not sure what I am going to work on this week. Stay tuned!

Like this post? Share on: Twitter ❄ Facebook ❄ Email