It used to be a required part of a package (old, pre-3.3 "regular package", not newer 3.3+ "namespace package").

Here's the documentation.

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.

In Python, a module is recognised if the folder has an init.py so it’s essentially saying “look at me, this folder has code inside”. If there’s no init.py, then Python doesn’t know there’s code inside, so won’t recognise the folder as something to import. It can be used completely blank (no import / code of any kind) for this purpose on its own. What init actually is, is a reserved method for initialising. This means that when you import this module, this code is automatically run. As such, if you have an init.py which has the line start = ‘Hello World’ … then the start variable will be accessible to you from the very first import. Otherwise you might have to explicitly write import module.start

The __init__.py file is a fundamental component in Python's package structure. It plays a crucial role in defining Python packages, initializing package modules, and controlling package behavior. Understanding __init__.py is essential for organizing your Python projects, managing namespaces, and facilitating modular programming. This comprehensive guide will delve into the purpose, functionality, and best practices related to __init__.py. What is __init__.py? __init__.py is a special Python file that serves multiple purposes within Python packages: Package Identification: It signals to Python that the directory should be treated as a package. Initialization Code: It can execute initialization code for the package. Namespace Control: It can control which modules and attributes are exposed when the package is imported. The double underscores (__) denote that __init__.py is a "dunder" (double underscore) or special method in Python. Historical Context In versions of Python prior to 3.3, the presence of an __init__.py file was mandatory for a directory to be recognized as a Python package. Without it, attempting to import modules from the directory would result in an ImportError. Starting with Python 3.3, PEP 420 introduced implicit namespace packages, allowing directories without an __init__.py to be recognized as packages. This change provided more flexibility in organizing large projects and distributing packages across multiple directories or distributions. However, even with implicit namespace packages, including an __init__.py file is still common practice for several reasons, such as initializing package-level variables or controlling the package's public interface. Primary Purposes of __init__.py 1. Defining a Python Package A Python package is a directory containing Python modules (i.e., .py files). To explicitly declare a directory as a package, an __init__.py file is placed inside it. Without __init__.py: project/ utils/ helper.py Attempting to import: import utils.helper # Raises ImportError in Python < 3.3 With __init__.py: project/ utils/ __init__.py helper.py Now, the import works as expected: import utils.helper # Successfully imports helper.py 2. Package Initialization Code __init__.py can contain Python code that initializes the package. This code is executed the first time the package or any of its submodules is imported. Example: # project/utils/__init__.py print("Initializing the utils package") # Initialize package-level variables package_version = "1.0.0" # Setup logging for the package import logging logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) logger.info("Utils package loaded") Usage: import utils # Output: # Initializing the utils package # INFO:utils:Utils package loaded 3. Controlling Imports By defining the __all__ list in __init__.py, you can control which modules and attributes are exported when from package import * is used. Example: # project/utils/__init__.py __all__ = ['helper', 'calculator'] from .helper import HelperClass from .calculator import CalculatorClass Usage: from utils import * # Only helper and calculator are imported helper_instance = HelperClass() calculator_instance = CalculatorClass() 4. Namespace Packages While implicit namespace packages (PEP 420) allow packages without __init__.py, explicit namespace packages can still be created by including an __init__.py that declares a namespace. Example: # project/src/utils/__init__.py __path__ = __import__('pkgutil').extend_path(__path__, __name__) This allows multiple directories to contribute to the same namespace package. Creating and Using __init__.py Basic __init__.py A basic __init__.py can be empty or contain simple initialization code. Example: project/ utils/ __init__.py # Empty file helper.py Usage: import utils.helper # Imports helper.py Executing Initialization Code You can include code in __init__.py that needs to run when the package is imported. Example: # project/utils/__init__.py import sys print("Utils package is being imported") # Modify the system path sys.path.append('/additional/path') Usage: import utils # Output: # Utils package is being imported Exposing Submodules and Attributes By importing submodules or specific attributes in __init__.py, you can simplify the import statements for users of your package. Example: # project/utils/__init__.py from .helper import HelperClass from .calculator import CalculatorClass __all__ = ['HelperClass', 'CalculatorClass'] Usage: from utils import HelperClass, CalculatorClass helper = HelperClass() calculator = CalculatorClass() This approach allows users to access HelperClass and CalculatorClass directly from the utils package without specifying submodules.

__init__.py is a requirement for a directory to be registered as a module. Usually, I don't put any content in it. Well no, not anymore. Since 3.3, python has had namespace packages which actually can't have an __init__.py file in it. For most purposes, you can have the file or not and it should work as expected, but they are not required anymore. Sometimes, I write imports clauses of classes and functions that are meant to be used in the code importing this module. This makes them clearly visible among other, implementation-details parts of the code. This is pretty good practice for anything that you want to be available as a top level object when people import your package. If you declare it, or import it, in __init__.py, then its available as a top level object of your package, otherwise, people would have to know which submodule to import in order to use those objects It's good to keep classes in a separate files. I'm not sure about that one, maybe it's a good convention for other languages that I started treating as a good habit in general, but I think it improves the readability and simplifies the structure of the package. Generally, yes. Sometimes its more convenient to put a class in the init.py, but you can always define it in another file and import it if you want to It's a short class extending an abstract class and it's not meant to be changed by anyone. I don't really know what does it have to do with anything. If people using this package are not supposed to, or not expected to, access this abstract class directly, then it should not be in the init.py file. This specific case should be placed in a utils file or one reserved for abstract base classes that your project uses __init__.py is executed immediately after the import, it can have initialization code. Registering a class structure is sort of initialization meant for that package. Yes but also no. Yes, the code in that file is ran when you import the package, or any part of it, and it can have initialization code. No, registering a class structure, especially if it is an internal structure, is not the correct type of initialization code to put in here. However, when I consider reasons for and against mentioned above, I'm coming to the conclusion it's better not to do anything besides top-level imports in __init__.py It depends. Check out requests . In their init.py they are running some basic checks to make sure that requests can work as expected, and throws some warnings if it can't. This is more than just doing top level imports, but at the same time it needs to go in init.py because it affects how the entire package can run. But really it all comes down to personal opinion. You can include more in init.py if you want, you can have nothing there. Some situations have stronger arguments in favor of each position, but you never have to put anything there if you don't want to

Lets say you have the following structure: - main.py - module.py With code in each file. This works fine. At some point you need to break up module.py into smaller chunks, like: - main.py - module/ - __init__.py - gui.py - encoding.py or something similar. However, because "module" is now a directory instead of a file, you can't "put code in it". The contents of __init__.py "belong" to the same namespace as module, so if module/__init__.py contains the following code: SOME_VAR = 5 then in main.py you can do: from module import SOME_VAR print(SOME_VAR + 37) Adding due to popularity: Because of the above, it's common to see __init__.py used for package-related variables (all the dunders like __author__, __version__, etc.) as well as "up-importing". "Up-importing" is a way to balance a simple user interface with a practical development layout. For example, it's not uncommon to put classes in their own module, so you might ahve: package/ models/ api.py db.py user.py and so on. However, if you do this, then the user needs to: from package.models.api import MyAPI from package.models.db import UserTable ... So instead, you make a package/__init__.py that contains the above (what you don't want to force the user to type): from package.models.api import MyAPI from package.models.db import UserTable ... and then the user can now do: from package import MyAPI, UserTable, ... Because all those objects have been "up-imported" into the top-level package namespace. For similar reasons, this is a good place to define __all__ = [], if you need it.