How is a Python package laid out on disk, and what does the __init__.py file do?
A package is a directory that contains an __init__.py file and one or more modules inside it. A minimal package looks like this on disk:
shapes/
__init__.py
circle.pyThe __init__.py file is what makes the directory a regular package. It runs the first time the package is imported, so it is the natural place for package-level setup and for re-exporting the names that you want to be visible at the top level. Writing from .circle import area inside __init__.py means that users can write from shapes import area instead of reaching into the submodule themselves.
The submodules are then reached with a dotted import. Importing shapes gives you the package, and from shapes.circle import area reaches into the submodule for a single name. Importing shapes.circle binds the submodule as an attribute of the package, which is why the name of the submodule is also reachable as shapes.circle afterwards.
Two details are worth knowing. Since Python 3.3 the __init__.py file is optional, because a directory without it becomes an implicit namespace package. That works, but it cannot run any code at import time, so most projects still include the file. A package is also only importable when the directory that holds it is on sys.path, which is why an installed package works while a folder that you just created inside your project does not, until you fix the path.