Is setuptools.find_namespace_packages() consistent with PEP420?

[kandersolar]

I'm trying to understand the new best practice for package maintainers around PEP 420 and found something that seems inconsistent between how setuptools defines namespace packages and how PEP 420 defines them.

Under https://peps.python.org/pep-0420/#specification it says:

Namespace packages cannot contain an __init__.py.

And under Differences between namespace packages and regular packages, PEP 420 says:

Namespace packages have no __init__.py module.

From this I'd have thought that a namespace package MUST NOT (in the convention of RFC 2119) contain an __init__.py module. However, the code underlying find_namespace_packages does not reflect that requirement and considers any directory a namespace package, regardless of the presence or absence of an __init__.py module:

setuptools/setuptools/discovery.py

Lines 163 to 166 in 641cb89

	class PEP420PackageFinder(PackageFinder):
	@staticmethod
	def _looks_like_package(_path: _Path, _package_name: str) -> bool:
	return True

I've found very helpful explanations from @abravalheri (#3340 (comment) and elsewhere) about the definition of packages, but I've not seen this particular aspect of namespace packages discussed. Any clarification here would be appreciated :)

[abravalheri]

Hi @kanderso-nrel ,maybe the naming we use right now is a bit mixed up, but the idea with find_namespace_packages is that it would also include namespaces in addition to regular packages. The same thing with PEP420PackageFinder, it find the packages including the ones described in PEP 420.

[kandersolar]

Thanks for the explanation @abravalheri! From their names alone I might have assumed that find_packages and find_namespace_packages would have no overlap in what they return, i.e. find_packages returns only directories with an __init__ file and find_namespace_packages returns only directories without one. Thanks for clarifying.

[abravalheri]

Yeah, the choice of names might have been a bit misleading, but since these functions/classes are part of setuptools for a long time now, I don't think it would be wise to rename them. What we can do is improve documentation. Please let us know if they appear in a part of the docs that is confusing.