`NamespacePackageEncountered` exception docstring needs revisiting?

[nathanjmcdougall]

This error doesn't seem to be raised anymore in the codebase itself, since namespace packages are now supported at the top level, I think the docstring should probably be updated.

grimp/src/grimp/exceptions.py

Lines 19 to 25 in 82ebd22

	class NamespacePackageEncountered(GrimpException):
	"""
	Indicates that there was no __init__.py at the top level.
	This indicates a namespace package (see PEP 420), which is not currently supported. More
	typically this is just an oversight which can be fixed by adding the __init__.py file.
	"""

Perhaps something like

class NamespacePackageEncountered(GrimpException):
    """
    Indicates that there was unexpectedly no __init__.py at the top level.

    This indicates a namespace package (see PEP 420). Previously, Grimp did not support this situation.
    This error is kept for backward-compatibility reasons and is not raised by Grimp itself anymore.
    """

[seddonym]

Thanks for spotting this.

Ideally we wouldn't have this exception knocking around forever - arguably, if someone is handling it in library code it's better that we error so they know that code path can no longer happen. Not a great user experience for the exception just to disappear with no deprecation warning.

Thinking aloud, perhaps we could implement a module-level __getattr__ so if someone accesses that exception class, we log a warning.

Out of interest how do you notice this issue?

[nathanjmcdougall]

Ideally we wouldn't have this exception knocking around forever - arguably, if someone is handling it in library code it's better that we error so they know that code path can no longer happen. Not a great user experience for the exception just to disappear with no deprecation warning.

Thinking aloud, perhaps we could implement a module-level getattr so if someone accesses that exception class, we log a warning.

Yeah I think that would be the standard way to approach this - a deprecation cycle. But there's a built-in for doing this with a decorator: @warnings.deprecated. Perhaps better to remove the docstring at the same time. And then let it sit there for a while :)

Out of interest how do you notice this issue?

I'm working on a CLI tool which automates the management of Python tooling on a project, and one of the commands is usethis tool import-linter. I had a unit test for the case of a root-level namespace package, and was catching NamespacePackageEncountered.

The command uses Grimp to automatically infer a plausible layered architecture based on the existing import structure to give some sensible out-of-the-box config. I mentioned it a while back on the Import Linter repo. For what it's worth, along a similar vein to your comment here regarding adding new convenience commands to Import Linter, I think something like il infer and il init would be useful, which would basically do the same sort of thing.

The new behaviour in Grimp 3.14 update was caught by my CI runner which tests bleeding edge versions of dependencies using uv sync --resolution=highest to try and catch these sorts of things, and address them quickly.

I've bumped the usethis requirements to grimp>=3.14 now, so I won't be using NamespacePackageEncountered anymore:
https://github.com/usethis-python/usethis-python/pull/1182/files

[seddonym]

Yeah I think that would be the standard way to approach this - a deprecation cycle. But there's a built-in for doing this with a decorator: @warnings.deprecated. Perhaps better to remove the docstring at the same time. And then let it sit there for a while :)

Agreed. I'll get to it (unless you feel like contributing? 😄 )

The command uses Grimp to automatically infer a plausible layered architecture based on the existing import structure

Wow that's cool, wasn't aware of your tool. Are you aware of the recently-added nominate_cycle_breakers method in Grimp? This provides an algorithm for optimally organizing the code into an acyclic graph (the cycles could be put into ignore_imports). Might be interesting for your library.

Thanks for the context!

[nathanjmcdougall]

I'll get to it (unless you feel like contributing? 😄 )

I feel like contributing :)

there's a built-in for doing this with a decorator

Ah, it's Python 3.13 only.

Are you aware of the recently-added nominate_cycle_breakers method in Grimp? This provides an algorithm for optimally organizing the code into an acyclic graph (the cycles could be put into ignore_imports). Might be interesting for your library.

No - I didn't know about that, I'll take a look. The logic I currently use to handle cycles is basically just to put them into exhaustive_ignores for the layer contract.

[seddonym]

I feel like contributing :)

Great! Let me know if you need any pointers. Otherwise https://grimp.readthedocs.io/en/stable/contributing.html should sort you out.