bug: Unconditional import of _internal.tests in __init__.py breaks downstream packaging/compilation (e.g., Nuitka, PyInstaller)

[zengzhengrong]

Describe the bug

In griffe/__init__.py, the test-related helpers from griffe._internal.tests (such as temporary_pypackage, temporary_pyfile, etc.) are imported unconditionally at the top level:

https://github.com/mkdocstrings/griffe/blob/main/src/griffe/__init__.py (around line 361)

from griffe._internal.tests import (
    TmpPackage,
    htree,
    module_vtree,
    temporary_inspected_module,
    temporary_inspected_package,
    temporary_pyfile,
    temporary_pypackage,
    temporary_visited_module,
    temporary_visited_package,
    vtree,
)

While these helpers are useful for users writing test suites for their extensions, unconditionally importing them in the package's top-level entrypoint creates a hard runtime dependency on griffe._internal.tests.

When downstream developers compile or package their applications using tools like Nuitka, PyInstaller, or PyStand, they typically configure these tools to exclude test suites (e.g., using --nofollow-import-to=*.tests or excluding subpackages matching tests) to keep the bundle size small.

Because of this unconditional import, any attempt to load griffe (or frameworks that depend on it, like pydantic_ai) in the compiled environment fails immediately with:

ModuleNotFoundError: No module named 'griffe._internal.tests'

To Reproduce

Create a script app.py that imports griffe:

import griffe
print("Loaded!")

Compile it using Nuitka with tests excluded:

nuitka --standalone --nofollow-import-to=*.tests app.py

Run the compiled executable, and it crashes with ModuleNotFoundError: No module named 'griffe._internal.tests'.
Expected behavior
griffe should be importable without requiring the test utilities package to be present. The core library should not have a hard runtime import dependency on its own test helpers in init.py.

[pawamoy]

Thanks for the report @zengzhengrong.

they typically configure these tools to exclude test suites

I know sometimes people put their test suite in the package sources (which is a wrong thing to do IMO), but is it really that common?

In any case, can't Nuitka/Pyinstaller users make their regular expression to exclude tests more specific? My tests module is under _internal, surely there are very very few packages that have test suites in sources AND split across sub packages as well?

The test helpers are an integral part of the API, so I will not make their import conditional. I can consider renaming the tests module though, to something like test_helpers, but I'd like to know first if that can be fixed on the user side.

[zengzhengrong]

Thanks for the reply!

1. Nuitka uses standard glob matching (fnmatch) for --nofollow-import-to, so we can't write negative patterns (like "exclude all *.tests except Griffe's").We tried forcing it with --include-module=griffe._internal.tests, but Nuitka's --nofollow-import-to=*.tests blacklist has higher priority and still blocks it. Packaging tools strip folders named tests by default to reduce binary size, which breaks here.
2. It's a very common practice for packaging tools (PyInstaller/Nuitka) and Linux distros (Debian/Fedora) to automatically strip tests folders to save space. An unconditional import of a module named tests breaks these setups.
3. This is why major libraries with public test utilities (like NumPy and Pandas) name their modules testing or test_helpers instead of tests to avoid conflict.
   If you could rename griffe._internal.tests to testing or test_helpers, it would cleanly solve this issue for all downstream packagers and OS package maintainers.

[pawamoy]

Thanks 🙂

Packaging tools strip folders named tests by default to reduce binary size, which breaks here.

Well that's not a folder here, it's a tests.py file. But I understand the tools don't care about that difference, and work with modules (whether folders or files).

to automatically strip tests folders to save space

Again, not a folder here.

---

Anyway, the module name is internal so I can change it without breaking anything, so I'll just do that 🙂