Have you used Sphinx for documenting your project? (You can also use RtD - for example, https://ensure.readthedocs.org/ https://ensure.readthedocs.org/ has the

Have you used Sphinx for documenting your project? (You can also use RtD - for example, https://ensure.readthedocs.org/ https://ensure.readthedocs.org/ has the docs for the project linked above). Sphinx makes it fairly straightforward to inline documentation and code while maintaining highly readable docs. Also, you can collapse and otherwise manage doctrings in IDEs like PyCharm. 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).