11 Answers
11

Python defines two types of packages, regular packages and namespace packages. Regular packages are traditional packages as they existed in Python 3.2 and earlier. A regular package is typically implemented as a directory containing an __init__.py file. When a regular package is imported, this __init__.py file is implicitly executed, and the objects it defines are bound to names in the package’s namespace. The __init__.py file can contain the same Python code that any other module can contain, and Python will add some additional attributes to the module when it is imported.

But just click the link, it contains an example, more information, and an explanation of namespace packages, the kind of packages without __init__.py.

What does this mean: "this is done to prevent directories with a common name, such as string, from unintentionally hiding valid modules that occur later on the module search path"?
– Carl GJan 25 '14 at 4:43

91

@CarlG Python searches a list of directories to resolve names in, e.g., import statements. Because these can be any directory, and arbitrary ones can be added by the end user, the developers have to worry about directories that happen to share a name with a valid Python module, such as 'string' in the docs example. To alleviate this, it ignores directories which do not contain a file named _ _ init _ _.py (no spaces), even if it is blank.
– Two-Bit AlchemistMar 7 '14 at 20:56

159

@CarlG Try this. Make a directory called 'datetime' and in it make two blank files, the init.py file (with underscores) and datetime.py. Now open an interpreter, import sys, and issue sys.path.insert(0, '/path/to/datetime'), replacing that path with the path to whatever directory you just made. Now try something like from datetime import datetime;datetime.now(). You should get an AttributeError (because it is importing your blank file now). If you were to repeat these steps without creating the blank init file, this would not happen. That's what it's intended to prevent.
– Two-Bit AlchemistMar 7 '14 at 21:03

4

@DarekNędza You've got something set up incorrectly if you can't just open a Python interpreter and issue from datetime import datetime without error. That's good all the way back to version 2.3!
– Two-Bit AlchemistMay 5 '14 at 20:10

Files named __init__.py are used to mark directories on disk as Python package directories.
If you have the files

mydir/spam/__init__.py
mydir/spam/module.py

and mydir is on your path, you can import the code in module.py as

import spam.module

or

from spam import module

If you remove the __init__.py file, Python will no longer look for submodules inside that directory, so attempts to import the module will fail.

The __init__.py file is usually empty, but can be used to export selected portions of the package under more convenient name, hold convenience functions, etc.
Given the example above, the contents of the init module can be accessed as

Update: The file __init__.py was required under Python 2.X and is still required under Python 2.7.12 (I tested it) but it is no longer required from (allegedly) Python 3.3 onwards, and is not required under Python 3.4.3 (I tested it). See stackoverflow.com/questions/37139786 for more details.
– Rob_before_editsOct 30 '16 at 14:49

2

Don't use it. It is "namespace" package, not a regular package. namespace package is used for very rare use cases. You may not need to know when use it. Just use __init__.py.
– methaneApr 6 at 1:54

In addition to labeling a directory as a Python package and defining __all__, __init__.py allows you to define any variable at the package level. Doing so is often convenient if a package defines something that will be imported frequently, in an API-like fashion. This pattern promotes adherence to the Pythonic "flat is better than nested" philosophy.

An example

Here is an example from one of my projects, in which I frequently import a sessionmaker called Session to interact with my database. I wrote a "database" package with a few modules:

Native support for package directories that don’t require __init__.py marker files and can automatically span multiple path segments (inspired by various third party approaches to namespace packages, as described in PEP 420)

In Python the definition of package is very simple. Like Java the hierarchical structure and the directory structure are the same. But you have to have __init__.py in a package. I will explain the __init__.py file with the example below:

I have the same structure in my project(python 3.4) but i'm not able to make another.py see other.py. How should i make the import? from root.stuff import other? It works in VSCode debug mode but not in command line. Any ideas?
– rodrigorfOct 23 '18 at 16:55

Thank you for your interest in this question.
Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).