[options.packages.find_namespace] should be [options.packages.find] in package discovery guide

In https://setuptools.readthedocs.io/en/latest/userguide/package_discovery.html#using-find-namespace-or-find-namespace-packages, the docs say

[options.packages.find_namespace]
where = src

That fails with

distutils.errors.DistutilsOptionError: Unsupported distribution option section: [options.packages.find_namespace]

[options.packages.find]
where = src

actually works.

Filing this as a doc issue, but maybe that option should work the way it’s documented?

[jaraco]

I’m now using find_namespace in most of my packages (those not supporting Python 2) based on jaraco/skeleton.

[trharoldsen]

The description of options.packages.find_namespace is also found in https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html so at least two locations in documentation are expecting it to work.

Note packages - The find: and find_namespace: directive can be further configured in a dedicated subsection
options.packages.find. This subsection accepts the same keys as the setuptools.find_packages and the
setuptools.find_namespace_packages function: where, include, and exclude.

I did a little searching of the code and found a few things. options.packages.find will work correctly according the the code. Both options.packages.find and options.packages.find_namespace sections are parsed in ConfigOptionsHandler._parse_packages in config.py when the corresponding package value (package = 'find[_namespace]') is parsed.

find_directives = ['find:', 'find_namespace:']
trimmed_value = value.strip()

if trimmed_value not in find_directives:
    return self._parse_list(value)

findns = trimmed_value == find_directives[1]

# Read function arguments from a dedicated section.
find_kwargs = self.parse_section_packages__find(
    self.sections.get('packages.find', {}))

if findns:
    from setuptools import find_namespace_packages as find_packages
else:
    from setuptools import find_packages

return find_packages(**find_kwargs)

So it’s actually expected that the [options.packages.find] form will be used.

The actual error occurs because the options.packages sections are parsed twice; once in the previously mentioned area and again when the the parser reaches the section. At this point the parser does a lookup of the method based on the option name. It finds the corresponding options.packages.find method, _parse_section_find, ignoring the result. However, there is no corresponding _parse_section_find_namespace method for the options.packages.find_namespace section which leads to the error.

I suppose the real question at this time is cosmetic. Should the code be updated to match the documentation or the other way around?

– Update – Updating to use options.packages.find_namespace could lead to a breaking change depending on how it’s implemented.