Python 3.8.0 has been released

So there's a few things going on here. If we look at a bit more of the directory structure it might look like:

project/
    README.md
    setup.py
    project/
        module/
             __init__.py
             __main.py__
        __init__.py
        __main__.py

So, the top-level project folder can actually be named anything. The reason I typically name it identically to the inner-level project folder it is so that I can install the project in editable mode (pip install -e .) while the project is still being heavily developed. This installs the project as (essentially) a symlink to the source directory has a number of nice features, including:

1. you don't need to worry about the setup.py, which can be complicated and will change a lot as you develop.
2. any updates to your project are automatically reloaded the next time you import it into a python shell; no need to reinstall.

I've found that if the top-level and inner-level project folders aren't named identically, this trick breaks (appears to be a pip issue, the last I checked). None of this is required at all (see way more about packaging here), but I find it pretty useful.

The real key here is that the inner-level project folder is the name that your package will have when you use the package externally. E.g., if you had:

Naaaayme/
    README.md
    setup.py
    coolio/
        __init__.py

you would use it externally as:

>>>from coolio import ... # whatever is in your package

Then subfolders (e.g., the module) above would be available via from coolio.module import ...

To reframe the question, I have to use the directory name as the module name? I can't do "foo directory is the bar module"?

You can do this as the following (assuming you stick with the ~/project/project/module/ format:

#file: ~/project/project/foo/more_files.py
class SomeCoolClass(object):
    pass

#file: ~/project/project/bar/__init__.py
from project.foo.more_files import SomeCoolClass

__all__ = ['SomeCoolClass']

Then when you use your package you can do:

>>>from package.bar import SomeCoolClass

You can physically rename modules such that they don't correspond to the folder name, but that involves mucking about with the sys.modules which is typically a bad idea (and not very portable).