Adding type hints to the codebase

[Ryex]

Every time I go to work on ideas I have I get really itchy to add type hinting to novelWriter's code. They are really easy to use now days and can prevent a lot of silly mistakes and identify potential bugs.

even better, Since the project dropped py3.6 that means
from __future__ import annotations
can be placed at the top of all files for force hints to act as strings (3.11+ behavior) and we can use all the latest QOL type hint features without dropping parsing support for the previous versions. ie

a: list[int] = []

instead of

from typing import List
a: List[int] = []

I've stared some work in a private fork
Ryex#1

Thing are going smoothish but I've only worked on 3 files so far.

The type hinting has identified some dubious code paths in config.py because I'm being forced to use a lot asserts to get types to resolve. This is actually fairly normal when dealing with Optionals like str | None but it does indicate that at least some of these should be defaulting to empty strings instead of None. Some functions are, perhaps wrongly, assuming that the config fields can't be None by the time they are called and there is no failure code in place.

Is this kind of work something your interested in?
(no wories if not, I mostly was just interested in how much overall work it would be. Turns out a moderate amount of work to add all the hints and them some extra to get the errors to resolve.)

[vkbo]

Yes, I have thought about this too. I've considered starting to add it whenever code is updated. The project was originally written to support Python 3.4 and 3.5 due to support for Ubuntu LTS releases that no longer are relevant (there is still code left related to unordered dictionaries for instance).

I'm not entirely happy with the way strings and None are implemented in my code, especially in the config. It is handled OK in the XML parsing I think. I've mostly handled these cases by passing them through the checker functions. The entire Config class is inherited from an older project, so it is really old code at the core. I am considering rewriting it entirely. I've made a number of fixes to it, but it is still not ideal. I would rather implement it as a class similar to the OptionState class, with a JSON file as storage format.

But I digress ...

I'm absolutely interested in this. I think the best place to start adding type hinting is in the core subpackage. This is where it matters the most since that's where all data classes live. It is also where I've made the most effort to restructure the code and improve encapsulation.

Edit: Also, I've been very absent from the project over the summer. I've moved to another city and a new apartment, so I've been very busy. I want to speed up the work on 1.7 though, so I can get it out. I think there are a lot of good improvements there, and some people have been waiting a long time for them!

[Ryex]

I've placed a draft PR with my work starting on type hinting for the core package so far things have been very strait forward.
I had to get a little creative with some @overload hints and I made some strategic use of TypedDict. when adding type hinting it is always a good idea to solidify any complex data structures (read: dicts or lists with more than one type stored within) in use as much a possible because it allows you to spot mistakes when you access them elsewhere.

project.py has a significant number of places where str | None types and the like are assumed to no longer be None during normal program flow and thus asserts have been placed to make the checker happy. These places are good candidates for review at a later date to ensure that those asserts would truly be a bug and non recoverable.

I'll continue work on this over the next month or so as I have time.

[vkbo]

Thanks, I'll have a look. There are functions that ensure that these variables are not None as soon as a project is successfully loaded. Most default values are set by clearProject(), and the remaining variables can either be None, or in case of the paths, are set by the ensureFolderStructure() function.

Perhaps the flow is too complex for the tools to determine whether these None values can reach code that assumes they are strings. There may of course be some cases where this could potentially fail.

Personally, I don't like having asserts in the main code, so they need to be cleared up.