Why do python projects have the following structure?

Question

I am working on creating my own installable python package using setup.py. While going over different repositories, I find the following structure -

abc-def
|-abc_def
|-setup.py

Here, setup.py has the function setup with the following contents -

setup(
    name="abc_def",
)

My question is, does the parent directory need to share its name with the child directory, just swapping the - for a _. Especially since it seems that python doesn't accept the - symbol. For instance, if I use import abc-def anywhere in the code, I get the following error -

>>> import abc-def
  File "<stdin>", line 1
    import abc-def
              ^
SyntaxError: invalid syntax

Answer 1

The name of the root abc-def directory is the name of the project's source directory tree. This name does not matter at all for Python or packaging. This is a convention to keep the name of the project's source directory tree the same as the name of the distribution package.

The name abc-def written as name in setup.py is the name of the distribution package. And abc_def (directory abc-def/abc_def) is the name of the top-level import package. So you pip install abc-def, but you import abc_def. Both names can be completely different (for example "beautiful soup 4"), but the convention in the Python community is that both names should be the same name modulo the normalizations (dashes - for distribution package names vs. underscores _ for import package names).

The import package name has to be a valid Python identifier, so dashes - are not allowed.

The normalization rules for distribution package names are specified here in this document: Names and normalization. So a distribution package named abc-def, can also be installed like any of the following and still the same package would be installed:

• abc-def
• abc_def
• abc.def
• AbC_-._-dEf

The way you write the distribution package name in setup.py is the way it will appear on PyPI. See these examples:

• Sphinx has a capital S
• zope.interface has a dot .

Answer 2

1. python projects often have this structure, because this was what was recommended with setuptools

2. It is not compulsory to keep same names cf. here

Although setuptools allows developers to create a very complex mapping between directory names and package names, it is better to keep it simple and reflect the desired package hierarchy in the directory structure, preserving the same names.

3. new projects are advised to use pyproject.toml instead of setup.py