merlin
merlin copied to clipboard
LLNL
[Q/A] Discussion to include new tools (annotations and PyLint)
So I want to start a discussion about some features and tools which can improve maintainability. We're looking to grow Merlin and the spellbook soon, potentially (ideally) a lot, now could be a great time to incorporate tools that promote lean and maintainable growth.
Python now supports type hints via annotation to indicate intended data types of variables/classes/function signatures/etc, basically because the community had been doing it informally for years with non-standardized tools and it seemed like, if the community's already doing it en masse, there should be a standard builtin. If anyone's unfamiliar with this newer-ish (~2014) Python feature, annotations enable inline markup, and type hints are a codified annotation to indicate an intended "static" data type. When you hear "static type" you might think "that's not Pythonic", but this doesn't change Python's quintessential dynamic duck typing, it's line-by-line optional, and even if you have annotation or type hints somewhere in your code, the interpreter does not enforce it, it reads through annotations like comments, so devs can use (or misuse) things the way they always have, e.g. I can type hint some variable as an int, initialize it to 3.14, then reassign its value as "foo", and the interpreter says 'ok boss' as usual.
The value of annotations is not to system behavior like in a statically typed language but for developers, who might notice an op assigning floats and strings to what someone declared should be an int and decide "let's not". It's useful for quickly reading unfamiliar, fast-evolving, or complicated code. I couldn't count how many times I spotted a problem in my last project just examining the annotations. Guido himself pushed for this through his Dropox position and Dropbox actually maintains a great linter called MyPy which, unlike the interpreter, actually enforces type hints (both internally for your project and externally if another project incorporates your code as a library and they also use mypy).
I'll just let Guido explain. The official docs are also really good.
As another possibility, we're running style checks with flake8 and black, which are both great, another linter to consider is PyLint, maybe not initially but soon-ish. It examines source not just for style but certain kinds of bugs and unsafe behavior, and esp. redundancy: it can recognize similar code and suggest simplifications; it can warn if you are breaking your declared interfaces because duck typing allows that; a myriad of other more advanced issues in addition to "is this PEP compliant". I'll admit to a love-hate relationship with PyLint, it can catch some really impressive things, but it's also examining a harder problem space than a style linter so it can miss some things and sometimes complains about fine code, but fixing that isn't too bad.
I think this seems like a good idea, for both merlin and the merlin-spellbook. I think we should welcome pull requests that add type annotations to our functions.
