I’m not really sure if this is the correct category, correct venue, or even correct approach to raising this question, but it felt at least not obviously in-appropriate to go this route.
Is there any… formal/official “guidance” available anywhere (perhaps in a FAQ / documentation, a mailing-list thread, a ranting screed someone crayoned to the door of a bathroom stall at a conference somewhere… whatever) as to how “importability” should be handled in Python modules? (Ones installed into the interpreter’s site-packages, particularly.)
I discovered to my dismay, recently, that the sphinx_theme_builder package contains modules (well, at least one module) that take an unusual approach to implementing dependency management. On import, the module
sphinx_theme_builder._internal.cli.__init__.py will do a check for the (external, third-party) dependencies of its CLI mode, and if any are missing, it will display a very snazzily formatted, colorized error message…and then call
I discovered this in the course of doing a
pydoc -k search for some keyword I don’t recall, when I noticed that my search was abruptly terminating with a non-zero exit code. But the same thing happens if you just run
import sphinx_theme_builder._internal.cli in an interactive Python session — instant termination.
That just doesn’t sit well with me. At least as a matter of opinion (something that, I stipulate, carries less that no weight), I feel that any and all modules installed into a Python distribution should be at least importable… importable, that is, without taking down the Python interpreter as a side-effect.
We certainly tolerate plenty of other, often ugly, side-effects from module imports, but I feel (again: meaningless) that a line worth drawing in the sand is: At no point should importing a module cause the interpreter to exit. Any module, under any circumstance.
So, I attempted to raise that concern with the
sphinx_theme_builder developers, demonstrating with this REPL listing, verbatim:
$ python3 Python 3.11.2 (main, Feb 8 2023, 00:00:00) [GCC 12.2.1 20221121 (Red Hat 12.2.1-4)] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import sphinx_theme_builder._internal.cli error: missing-command-line-dependencies × Could not import a package that is required for the `stb` command line. ╰─> No module named 'sphinx_autobuild' note: The optional cli dependencies of this package are missing. hint: During installation, make sure to include the `[cli]`. For example: pip install "sphinx-theme-builder[cli]" link: https://sphinx-theme-builder.rtfd.io/errors/#missing-command-line-dependencies $
In reply, a project maintainer posted a single, pointed question: “Why are you importing an _internal submodule directly?”
Not an unfair question, perhaps, but also sort of missing the point, since I’d mentioned previously (there as well as here) that, for one thing, this was affecting the ability of
pydoc -k to fully scan the collection of installed modules.
Which is kind of where things are at. IMHO the fact that the module is internal is immaterial — it’s installed into Python as part of the package, and if nothing else there are tools in the broader ecosystem that rely on being able to import every installed module as part of their basic function.
And that’s before you factor in the best interests of curious users, inquisitive language-learners, and even potential
sphinx_theme_builder contributors, all of whom might have valid reasons for experimentally importing a module, despite it being internal, despite it not being intended to be imported that way. “Simply because it’s there.”
…But other than my (stipulated: meaningless) arguments about what I believe, are there any resources I can point to that help make the case for “don’t exit on import”?