pythonpython-packaging

Why do python projects have the following structure?

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
Solution

  • 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:

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