That would probably make it easier to decouple from "Normal" python code too.
I'm not a very senior software dev or anything, but I imagine myself liking having my well-written, compact .py file detailing logic, and a separate 'doc'(?) file containing long-winded explanations of what some key functions do, and listing all the type consistencies I absolutely wish to guarantee.
So, if I were to implement what you said, I'd go with a file containing interface classes, i.e. classes that have getters/setters and type checking built in and documented, and another file defining logic operating on them.
Another pattern is to use something like:
class Widget(object):
... define key constraints...
"""
Long-winded docstring about do_stuff
"""
from .impl import do_stuff
So all the implementation complexity of do_stuff is hidden in .impl (which also avoids stray exports).In fact, this is exactly what OCaml does (or can do)[0]. The interface file is not always required, but people usually include it for clarity, to make sure the compiler's type inference works according to their wishes, or to limit visibility of certain types and functions.