What does an empty string key for package_dir do in setup.py?

Question

I have a setup.py file that looks like this:

import setuptools

from distgradle import GradleDistribution

setuptools.setup(
  distclass=GradleDistribution,
  package_dir={'': 'src'},
  packages=setuptools.find_packages('src'),
  include_package_data=True,
  namespace_packages=['foo'],
  entry_points={
    'console_scripts': [
      'first = foo.something.first:main',
      'second = foo.somethingelse.second:main',
    ],
  },
)

What is the significance of package_dir={'': 'src'}? Why do we have an empty string as the key?

Answer 1

When you have multiple directories at the root level and under one directory the modules reside, then you can define that directory as root package and then all packages provided to packages named argument would be looked up inside that dir. Python's official documentation describes this very well:

https://docs.python.org/3/distutils/setupscript.html#listing-whole-packages

Here, if code resides under lib directory then defining package_dir = {'': 'lib'} & packages = ['foo'] would mean that you are telling that system to look for foo module under lib i.e. lib/foo/__init__.py exists.