{"title":"__init__.py File","description":"","content":"A package is a directory of modules grouped under a single name, and the file at its center is `__init__.py`. It marks a directory as a package, runs once when the package is first imported, and acts as the package's namespace. Every shaping decision about how a package looks to callers happens in `__init__.py`. This lesson covers what the file does, what to put inside it, the common patterns (thin re-exports, lazy imports, package-level constants), and the modern alternative (namespace packages) for the rare cases where skipping `__init__.py` makes sense.\n\n---\n\n# What `__init__.py` Does\n\n`__init__.py` is a file that lives at the root of a package directory. Its presence tells Python \"this directory is a regular package, not a folder of unrelated scripts.\" Without it (in older Python or in projects that don't opt into namespace packages), the directory is a folder and the dotted imports won't work.\n\nThe file itself is a regular Python module. Anything that goes in a normal `.py` file can go here. The difference is that this particular file represents the **package** itself. When code does `import ecommerce`, Python runs `ecommerce/__init__.py` and the resulting module object is the `ecommerce` package. The package's namespace is whatever names exist after `__init__.py` finishes running.\n\nThe simplest case is a directory:\n\n\n```shell\necommerce/\n __init__.py (empty file, zero bytes)\n cart.py\n products.py\n```\n\n\n`ecommerce/cart.py`:\n\n\n```python\ndef add_item(cart, product, quantity=1):\n cart[product] = cart.get(product, 0) + quantity\n return cart\n```\n\n\n`ecommerce/products.py`:\n\n\n```python\nPRICES = {\"Wireless Mouse\": 29.99, \"USB Cable\": 9.99, \"HDMI Cable\": 14.99}\n\ndef is_available(product):\n return product in PRICES\n```\n\n\n`ecommerce/__init__.py` is completely empty.\n\nFrom a script next to the `ecommerce/` directory:\n\n\n```python\nfrom ecommerce.cart import add_item\nfrom ecommerce.products import PRICES, is_available\n\ncart = {}\nadd_item(cart, \"Wireless Mouse\", 2)\nprint(cart)\nprint(f\"Price: ${PRICES['Wireless Mouse']:.2f}\")\nprint(f\"Available: {is_available('Wireless Mouse')}\")\n```\n\n\nThe empty `__init__.py` did one thing: it made Python treat `ecommerce/` as a regular package, which is what makes `from ecommerce.cart import ...` resolve. No code ran (there was none to run), no names got bound on the package, but the dotted imports work.\n\nThe next step up is a populated `__init__.py`. Change `ecommerce/__init__.py` to:\n\n\n```python\nprint(\"ecommerce package initializing\")\n\nPACKAGE_VERSION = \"1.0.0\"\n```\n\n\nNow from a caller:\n\n\n```python\nfrom ecommerce.cart import add_item\nfrom ecommerce.products import PRICES\nimport ecommerce\nprint(ecommerce.PACKAGE_VERSION)\n```\n\n\nThree imports of `ecommerce` (one direct, two indirect through submodule imports), but `__init__.py` runs once. That's the same caching behavior every Python module has: the first import runs the body, every later import returns the cached module object from `sys.modules`. Earlier chapters covered this; it applies to `__init__.py` the same way it applies to any other module.\n\nThe `PACKAGE_VERSION` constant became an attribute on the `ecommerce` package, reachable as `ecommerce.PACKAGE_VERSION`. Package-level names are exposed by being defined at the top level of `__init__.py`, or by being imported into it from a submodule.\n\n\n```mermaid\nflowchart LR\n Import[\"first import ecommerce
or any submodule\"]:::cyan\n Find[\"Python finds
ecommerce/__init__.py\"]:::orange\n Run[\"run __init__.py body
build package namespace\"]:::green\n Cache[\"store in sys.modules
under 'ecommerce'\"]:::teal\n Done[\"package available
via ecommerce.NAME\"]:::cyan\n Later[\"later imports\"]:::cyan\n Reuse[\"reuse cached
module object\"]:::green\n\n Import --> Find --> Run --> Cache --> Done\n Later --> Reuse\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows the lifecycle. The first import (whether `import ecommerce` directly or `from ecommerce.cart import add_item` indirectly) triggers running `__init__.py`. The body runs once, builds the package namespace, and the result lands in `sys.modules` under the key `'ecommerce'`. Every later import (no matter the form) reuses that cached object.\n\n---\n\n# Empty `__init__.py`\n\nThe first case to consider is the empty `__init__.py`. Zero bytes, no code, no docstring. That's a valid package, and for many simple cases it's enough.\n\nWhat it accomplishes:\n\n- The directory is recognized as a regular package.\n- Dotted imports into the package work: `from package.submodule import name`.\n- No code runs at import time; the package has no setup overhead.\n- The package's namespace is empty (apart from automatic dunder attributes like `__name__`, `__file__`, `__path__`).\n\nWhen this is the right choice:\n\n- The package's modules are independent and don't need to coordinate.\n- A flat API isn't needed; callers can use the deeper paths.\n- The submodules are cheap to load (no heavy initialization), so there's no concern about which ones run when.\n\nA small example. A project's `ecommerce/` package has three submodules and the caller always uses the deep paths:\n\n\n```shell\necommerce/\n __init__.py (empty)\n cart.py\n products.py\n customers.py\n```\n\n\n\n```python\nfrom ecommerce.cart import add_item, cart_total\nfrom ecommerce.products import is_available\nfrom ecommerce.customers import get_customer\n```\n\n\nEach submodule loads only when something asks for it. The empty `__init__.py` introduces zero overhead. There's no extra code to maintain. A small project can keep the file empty for its entire life.\n\nThe empty version is also a sensible **starting point** for any package. Begin with an empty file and add to it only with a concrete reason: a flattened API, a package-level constant, an `__all__` declaration for tooling. Premature `__init__.py` content tends to drift into noise; starting empty and adding deliberately keeps the file purposeful.\n\nOne thing to watch: in a Python 2 codebase or a very old Python 3 codebase, an empty `__init__.py` is the **only** way to mark a directory as a package. Namespace packages (no `__init__.py` at all) only became fully supported in Python 3.3 via PEP 420. For modern code on modern Python (3.3+), both options exist, and the empty-file approach is still preferred for self-contained projects.\n\n---\n\n# Re-exports: Flattening the API Surface\n\nThe most common reason to put code in `__init__.py` is to **re-export** names from submodules so callers can reach them through the package's top-level name. This is the pattern that makes deeply-nested code look flat from the outside.\n\nConsider this layout:\n\n\n```shell\necommerce/\n __init__.py\n cart.py\n products.py\n```\n\n\nWithout re-exports, callers have to know which submodule owns which name:\n\n\n```python\nfrom ecommerce.cart import add_item, cart_total\nfrom ecommerce.products import PRICES, is_available\n```\n\n\nTwo things wrong here. First, the caller has to remember that `add_item` lives in `cart.py` versus, say, `cart_utils.py` or `actions.py`. Second, if anything is renamed or moved internally (moving `add_item` from `cart.py` to a new `cart/actions.py`), every caller's import breaks.\n\nRe-exports fix both. Update `ecommerce/__init__.py` to:\n\n\n```python\nfrom ecommerce.cart import add_item, cart_total\nfrom ecommerce.products import PRICES, is_available\n```\n\n\nNow callers can write:\n\n\n```python\nfrom ecommerce import add_item, cart_total, PRICES, is_available\n```\n\n\nThe names are now attached to the `ecommerce` package itself. The caller doesn't need to know that `add_item` lives in `cart.py`; that's an implementation detail. Splitting `cart.py` later into `cart/actions.py` and `cart/totals.py` requires updating `ecommerce/__init__.py` once to re-export from the new locations, and every caller keeps working with zero changes.\n\nThis pattern is everywhere in the standard library. `from collections import Counter` doesn't pull `Counter` from a file called `collections.py`. The `collections` package re-exports `Counter` from one of its internal modules. Same idea: a flat public API, regardless of how the code is laid out internally.\n\n\n```mermaid\nflowchart TD\n User[\"Caller writes:
from ecommerce import add_item\"]:::cyan\n Init[\"ecommerce/__init__.py
(re-exports submodule names)\"]:::orange\n Cart[\"ecommerce/cart.py
defines add_item, cart_total\"]:::teal\n Products[\"ecommerce/products.py
defines PRICES, is_available\"]:::teal\n\n User -->|\"1. triggers\"| Init\n Init -->|\"2. imports from\"| Cart\n Init -->|\"3. imports from\"| Products\n Init -->|\"4. add_item visible
on ecommerce\"| User\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram traces what happens. The caller's import triggers loading `__init__.py`. Inside `__init__.py`, the submodule imports run, which loads `cart.py` and `products.py`. After `__init__.py` finishes, `add_item`, `cart_total`, `PRICES`, and `is_available` are all attributes of the `ecommerce` package. The caller's request for `from ecommerce import add_item` resolves through that namespace.\n\nThe trade-off is import cost. Every name re-exported in `__init__.py` causes its source submodule to load on the first package import. If `cart.py` does heavy work at import time (loads a big file, compiles regexes, opens a connection), `import ecommerce` pays for that work even if the caller never uses `add_item`. For small packages, this is fine. For large packages with expensive submodules, an alternative is to re-export only the most common names and leave heavier ones reachable only through their deep paths.\n\nEager re-exports trade startup time for caller convenience. A package with 30 submodules that all get loaded eagerly through `__init__.py` re-exports has a noticeable startup cost. Profile the package's import time if needed; tools like `python -X importtime your_script.py` show which modules are slow to load.\n\nA rule of thumb: re-export the names callers use frequently. Leave rarely-used or expensive submodules accessible only through their full path. This keeps the common case fast and the unusual case still possible.\n\n---\n\n# Package-Level Constants\n\nConstants that are part of the package's public API often belong directly in `__init__.py`. Version numbers, default settings, package-wide configuration: things that aren't specific to any one submodule.\n\n\n```python\n# ecommerce/__init__.py\n\"\"\"E-commerce helpers for the AlgoMaster store.\"\"\"\n\nfrom ecommerce.cart import add_item, cart_total\nfrom ecommerce.products import PRICES, is_available\n\nPACKAGE_VERSION = \"1.2.0\"\nDEFAULT_CURRENCY = \"USD\"\nSUPPORTED_LANGUAGES = [\"en\", \"es\", \"fr\"]\n```\n\n\nCallers reach these through the package:\n\n\n```python\nimport ecommerce\n\nprint(ecommerce.PACKAGE_VERSION)\nprint(ecommerce.DEFAULT_CURRENCY)\n```\n\n\nThe `PACKAGE_VERSION` convention is common; many Python projects expose it under that name (or `__version__`, which is the dunder variant). Both work; pick one per project. Tools that introspect a package's version number look at one or the other first:\n\n\n```python\n# ecommerce/__init__.py\n__version__ = \"1.2.0\"\n```\n\n\n\n```python\nimport ecommerce\nprint(ecommerce.__version__)\n```\n\n\nBeyond version numbers, the kinds of constants that fit at the package level are configuration that doesn't depend on any particular submodule. If a value is conceptually owned by `pricing.py`, it lives in `pricing.py`. If it's owned by the package as a whole, it lives in `__init__.py`. Mixing these wrong creates confusion: a `TAX_RATE` constant in `__init__.py` makes readers wonder whether it overrides something in `pricing.py`, and updates require touching both files.\n\nOne small note: don't import package-level constants into submodules through the package. Doing `from ecommerce import PACKAGE_VERSION` inside `ecommerce/cart.py` creates a circular import (cart needs ecommerce, ecommerce needs cart). Submodules that need a constant should either define their own or read it from a separate config module the package as a whole owns.\n\n---\n\n# `__all__` in `__init__.py`\n\n`__all__` plays the same role in a package's `__init__.py` as it does in a regular module: it controls which names `from package import *` exports.\n\nWithout `__all__`, `from ecommerce import *` pulls every name that doesn't start with an underscore from the package's namespace. That includes any submodules imported into `__init__.py`, which is often more than intended.\n\nWith `__all__`, the public API is explicit:\n\n\n```python\n# ecommerce/__init__.py\nfrom ecommerce.cart import add_item, cart_total, _internal_helper\nfrom ecommerce.products import PRICES, is_available\n\nPACKAGE_VERSION = \"1.2.0\"\n\n__all__ = [\n \"add_item\",\n \"cart_total\",\n \"PRICES\",\n \"is_available\",\n \"PACKAGE_VERSION\",\n]\n```\n\n\n\n```python\n# caller.py\nfrom ecommerce import *\n\nprint(add_item({}, \"Mouse\")) # works\nprint(is_available(\"Mouse\")) # works\nprint(PACKAGE_VERSION) # works\nprint(_internal_helper) # NameError\n```\n\n\n`_internal_helper` exists in `ecommerce`'s namespace (it was imported into `__init__.py`), but it isn't in `__all__`, so the star import skips it. Same goes for any other name not listed.\n\nEven when no one writes `from ecommerce import *`, defining `__all__` is good hygiene. Linters and type checkers use it to identify the public API. Documentation generators use it to decide which names show up in the rendered docs. IDEs use it for autocomplete prioritization. The file is more useful with `__all__` than without.\n\nA common style is to keep `__all__` at the end of `__init__.py`, after all the imports and constants. That way the file reads top-to-bottom: docstring, imports, constants, then `__all__` summarizing the public surface.\n\n\n```python\n# ecommerce/__init__.py\n\"\"\"E-commerce helpers.\"\"\"\n\nfrom ecommerce.cart import add_item, cart_total\nfrom ecommerce.products import PRICES, is_available\n\nPACKAGE_VERSION = \"1.2.0\"\nDEFAULT_CURRENCY = \"USD\"\n\n__all__ = [\n \"add_item\",\n \"cart_total\",\n \"PRICES\",\n \"is_available\",\n \"PACKAGE_VERSION\",\n \"DEFAULT_CURRENCY\",\n]\n```\n\n\nA reader's eye lands on `__all__` and immediately sees the public API.\n\n---\n\n# Lazy Imports for Heavy Submodules\n\nEager re-exports in `__init__.py` load every referenced submodule at package import time. For a small package this is fine. For a large package, especially one with expensive submodules (a machine learning model loader, a database connector, a heavy parser), eager loading bloats startup time even when the caller only needs a lightweight name.\n\nLazy imports are the standard solution. Instead of importing a submodule eagerly, import it the first time someone asks for one of its names. The mechanism uses the module-level `__getattr__` function, added in Python 3.7 by PEP 562.\n\n\n```python\n# ecommerce/__init__.py\n\"\"\"E-commerce helpers with lazy loading for the heavy bits.\"\"\"\n\n# Cheap things: load eagerly\nfrom ecommerce.cart import add_item, cart_total\n\nPACKAGE_VERSION = \"1.2.0\"\n\n# Heavy things: load lazily\ndef __getattr__(name):\n if name == \"load_full_catalog\":\n from ecommerce.catalog import load_full_catalog\n return load_full_catalog\n if name == \"build_recommendation_model\":\n from ecommerce.recommendations import build_recommendation_model\n return build_recommendation_model\n raise AttributeError(f\"module 'ecommerce' has no attribute {name!r}\")\n```\n\n\nWhat happens at runtime:\n\n\n```python\nimport ecommerce\n# Loads cart.py only. catalog.py and recommendations.py are not loaded yet.\n\necommerce.add_item(...)\n# Still no catalog.py or recommendations.py.\n\necommerce.load_full_catalog(...)\n# Now catalog.py loads, because Python called __getattr__(\"load_full_catalog\").\n```\n\n\nThe first two operations don't touch the heavy modules. The third triggers the lazy load, and from then on `ecommerce.load_full_catalog` is cached on the package object (Python caches attribute access by default), so the cost is paid only once.\n\nThis pattern is most useful for packages where many users only need a small subset of the functionality, and the heavy submodules would otherwise slow down everyone's imports. It's used by numpy, scipy, scikit-learn, and many other large libraries. For small packages, it's overkill: the complexity of `__getattr__` isn't worth the savings when the eager version takes 50 milliseconds.\n\nTo check whether a package would benefit, profile its import time first:\n\n\n```shell\n$ python -X importtime -c \"import ecommerce\" 2>&1 | tail -20\n```\n\n\nThis prints the cumulative import time for every module loaded during `import ecommerce`. The output shows which submodules are the slow ones, and lazy loading is worth considering for any that take more than a few tens of milliseconds.\n\nA simpler form of lazy loading: don't re-export the heavy modules in `__init__.py` at all. Callers who need them use the deep path:\n\n\n```python\n# ecommerce/__init__.py exports lightweight names only\nfrom ecommerce.cart import add_item, cart_total\n__all__ = [\"add_item\", \"cart_total\"]\n```\n\n\n\n```python\n# Callers who want the heavy stuff use the deep path\nfrom ecommerce.catalog import load_full_catalog\n```\n\n\nThis works without `__getattr__` and is easier to read. The cost is that the public API looks split: some names live at the package root, others live one level down. Both forms (`__getattr__` and \"don't re-export\") are common in larger codebases; pick whichever fits the project.\n\n---\n\n# Side Effects to Avoid in `__init__.py`\n\nA common source of pain in packages is `__init__.py` files that do too much. Some side effects to keep out:\n\n**File and network I/O at import time.** Reading a JSON config, opening a database connection, fetching a URL: all of these run the first time anything imports the package, which is rarely the intent. The cost is paid by every program that touches the package, even ones that don't need the data. Worse, if the file doesn't exist or the network is down, the import fails entirely, and the package becomes unusable. Push I/O into functions that the caller invokes deliberately.\n\n\n```python\n# Bad: every importer pays for the load\nPRODUCTS = json.loads(open(\"products.json\").read())\n```\n\n\n\n```python\n# Better: opt-in\ndef load_products():\n return json.loads(Path(__file__).parent.joinpath(\"products.json\").read_text())\n```\n\n\n**Logging configuration.** Configuring the logging system at package import time (calling `logging.basicConfig`, setting handlers, setting log levels) interferes with whatever the caller's application has already set up. Libraries should attach handlers only when explicitly asked, never automatically.\n\n**Mutating global state.** `__init__.py` runs before the user has any say in what their program looks like. Avoid touching global state inside `__init__.py` to inject into the caller's environment. A package that needs to register itself with something should expose a `register()` function and let the caller invoke it.\n\n**Heavy computation.** Building large lookup tables, training a model, sorting a big list of constants: any of this slows imports down. If the result is cheap to compute, do it lazily on first use. If it's expensive, ship pre-built data files and load them on demand.\n\n**Imports that fail.** A `__init__.py` that imports a third-party library that might not be installed makes the entire package unusable when that import fails. Either make the dependency required (and let `pip install your-package` ensure it's there) or wrap the import in a try/except that falls back to a clear error message when the feature is used:\n\n\n```python\n# ecommerce/__init__.py\ntry:\n from ecommerce.fancy_feature import fancy_function\nexcept ImportError:\n def fancy_function(*args, **kwargs):\n raise RuntimeError(\n \"fancy_function requires the 'numpy' package. \"\n \"Install it with: pip install numpy\"\n )\n```\n\n\nThis makes the failure deferred and explicit instead of breaking every import of `ecommerce`.\n\nThe simplest rule: `__init__.py` should be predictable. A reader of the file should be able to glance at it and see what runs at import time. Big side effects, conditional logic, and external dependencies are red flags.\n\nSide effects at import time are some of the hardest bugs to debug because they happen before any calling code starts running. Symptoms include slow startup, failures during simple imports, and `ImportError` traces that point to lines deep inside someone else's package. The fix is usually to move the side effect out of `__init__.py` and into a function the caller invokes explicitly.\n\n---\n\n# Thin Init vs Fat Init\n\nThere are two broad styles for `__init__.py`, and most packages use one or the other depending on size and intent.\n\n**Thin init (re-exports only).** The file is a curated list of `from ... import ...` statements plus an `__all__`. All the logic lives in submodules; the init file shapes what callers see. This is the dominant style for small-to-medium packages.\n\n\n```python\n# ecommerce/__init__.py\n\"\"\"E-commerce helpers.\"\"\"\n\nfrom ecommerce.cart import add_item, cart_total\nfrom ecommerce.products import PRICES, is_available\nfrom ecommerce.customers import get_customer\n\n__all__ = [\n \"add_item\",\n \"cart_total\",\n \"PRICES\",\n \"is_available\",\n \"get_customer\",\n]\n```\n\n\nPros: easy to read, easy to maintain, clear separation between API shape (init) and implementation (submodules). Cons: every re-export forces its submodule to load eagerly.\n\n**Fat init (logic lives here).** Functions, classes, and constants are defined directly inside `__init__.py`, sometimes alongside imports from submodules. This appears in small one-file-grew-into-a-package projects.\n\n\n```python\n# ecommerce/__init__.py\n\"\"\"E-commerce helpers.\"\"\"\n\nTAX_RATE = 0.08\n\ndef cart_total(prices):\n return sum(prices) * (1 + TAX_RATE)\n\ndef apply_discount(price, percent):\n return price * (1 - percent / 100)\n\nfrom ecommerce.products import PRICES, is_available\n```\n\n\nPros: short package, fewer files, easy to read at a glance. Cons: doesn't scale; once `__init__.py` is more than a couple hundred lines, the rationale for being a package (organization) starts working against the layout.\n\nThe practical guidance: **start fat, refactor to thin as the package grows.** A brand-new package with three functions and a constant doesn't need a separate `core.py`; put everything in `__init__.py`. As the package accumulates dozens of names, gradually move logic into named submodules and turn `__init__.py` into a thin re-export layer.\n\nThe wrong move is the opposite: a 2,000-line `__init__.py` that defines everything itself. That's a giant `pricing.py` wearing a package's clothing. An `__init__.py` doing real work should split the work into submodules and turn the init file into a curated API.\n\nA useful smell test: can the `__init__.py` be read top to bottom in 30 seconds? If yes, the file is healthy. If no, it's grown beyond what a package's init file should hold.\n\n---\n\n# Subpackage `__init__.py`\n\nEvery directory in a package tree gets its own `__init__.py`. The rules are the same at every level: an empty file is enough to mark the directory as a regular package; a populated file can re-export, define constants, and set `__all__` for that subpackage.\n\n\n```shell\necommerce/\n __init__.py\n cart/\n __init__.py\n operations.py\n discounts.py\n products/\n __init__.py\n catalog.py\n search.py\n```\n\n\n`ecommerce/cart/__init__.py`:\n\n\n```python\n\"\"\"Cart operations and discount logic.\"\"\"\n\nfrom ecommerce.cart.operations import add_item, remove_item\nfrom ecommerce.cart.discounts import apply_percentage, apply_flat\n\n__all__ = [\"add_item\", \"remove_item\", \"apply_percentage\", \"apply_flat\"]\n```\n\n\n`ecommerce/products/__init__.py`:\n\n\n```python\n\"\"\"Product catalog and search.\"\"\"\n\nfrom ecommerce.products.catalog import PRICES, is_available, price_of\n\n__all__ = [\"PRICES\", \"is_available\", \"price_of\"]\n```\n\n\nThe top-level `ecommerce/__init__.py` can then re-export from the subpackages:\n\n\n```python\n\"\"\"E-commerce helpers.\"\"\"\n\nfrom ecommerce.cart import add_item, remove_item, apply_percentage, apply_flat\nfrom ecommerce.products import PRICES, is_available, price_of\n\nPACKAGE_VERSION = \"1.2.0\"\n\n__all__ = [\n \"add_item\",\n \"remove_item\",\n \"apply_percentage\",\n \"apply_flat\",\n \"PRICES\",\n \"is_available\",\n \"price_of\",\n \"PACKAGE_VERSION\",\n]\n```\n\n\nA caller now has multiple ways to import any given name:\n\n\n```python\n# Through the top-level package\nfrom ecommerce import add_item\n\n# Through the subpackage\nfrom ecommerce.cart import add_item\n\n# Through the deep path\nfrom ecommerce.cart.operations import add_item\n```\n\n\nAll three resolve to the same function. The maintainer chooses which path is the \"official\" one (usually the shallowest); the deeper paths remain available as fallbacks and for advanced users.\n\nA note on import order: when Python loads `ecommerce/__init__.py` and that init does `from ecommerce.cart import add_item`, Python triggers loading `ecommerce/cart/__init__.py`, which triggers loading `ecommerce/cart/operations.py`. The chain runs top-down through the tree. If any of those steps has slow code, the cost rolls up to the top-level import.\n\n\n```mermaid\nflowchart TD\n Caller[\"import ecommerce\"]:::cyan\n EcInit[\"ecommerce/__init__.py
runs\"]:::orange\n CartInit[\"ecommerce/cart/__init__.py
runs (triggered by re-export)\"]:::orange\n Operations[\"ecommerce/cart/operations.py
runs (triggered by re-export)\"]:::teal\n Discounts[\"ecommerce/cart/discounts.py
runs (triggered by re-export)\"]:::teal\n ProductsInit[\"ecommerce/products/__init__.py
runs\"]:::orange\n Catalog[\"ecommerce/products/catalog.py
runs\"]:::teal\n\n Caller --> EcInit\n EcInit --> CartInit\n CartInit --> Operations\n CartInit --> Discounts\n EcInit --> ProductsInit\n ProductsInit --> Catalog\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows the load order for `import ecommerce` when every `__init__.py` re-exports eagerly. The top-level init triggers the subpackage inits, which trigger the submodules. By the time `ecommerce` is fully loaded, the whole tree is in memory.\n\nThis is fine for small to medium packages. For larger ones, an alternative is to skip re-exporting heavy subpackages and let callers reach them through the deep path, saving the cost for those who need it.\n\n---\n\n# Namespace Packages: When You Skip `__init__.py`\n\nPEP 420 (Python 3.3+) added a second kind of package called a **namespace package**: a directory **without** `__init__.py` that Python still treats as importable. The motivation was distributed development: large projects sometimes want to split a single logical package across multiple physical directories or installed distributions, and a regular package can't do that because only one `__init__.py` can own the package name.\n\nA minimal example:\n\n\n```shell\nplugins-core/\n ecommerce/\n cart.py\nplugins-extras/\n ecommerce/\n wishlist.py\n```\n\n\nIf both `plugins-core/` and `plugins-extras/` are on `sys.path`, then `import ecommerce.cart` and `import ecommerce.wishlist` both work, even though the two `ecommerce/` directories are physically separate. Python merges them into a single namespace because neither contains an `__init__.py`.\n\nThis is useful for plugin systems. Consider a base package `myapp` where third parties publish their own plugins as separate distributions on PyPI. With a namespace package layout, each plugin can drop its module into `myapp.plugins.` from its own installed distribution, and Python merges them at runtime. Users install the base package and any combination of plugins, and they all show up under the same dotted name.\n\nFor ordinary self-contained projects, namespace packages are usually the wrong choice. The pitfalls:\n\n- **No initialization code possible.** The package loses `__init__.py`'s ability to set up state or re-export names. There's no place to put a docstring, a version constant, or an `__all__` declaration. Tools that look for `package.__version__` find nothing.\n- **Directory merging without warning.** If two directories on `sys.path` share a top-level name, Python merges them. This can mask typos and produce hard-to-debug \"where did this module come from\" sessions.\n- **Tool support is uneven.** Some packaging tools, type checkers, and IDEs handle namespace packages less smoothly than regular packages. Setting up a `pyproject.toml` for a namespace-package distribution requires extra configuration.\n- **No `__all__` control.** Without `__init__.py`, the package can't define `__all__`, so `from package import *` falls back to defaults that may not match the intent.\n\nThe rule of thumb: **include `__init__.py` for everything**, even when it's empty. Use namespace packages only with a specific reason, almost always involving plugin extensibility from third parties.\n\n\n```mermaid\nflowchart LR\n Regular[\"Regular Package
has __init__.py\"]:::cyan\n Namespace[\"Namespace Package
no __init__.py\"]:::orange\n\n Regular --> R1[\"Single directory
owns the name\"]:::teal\n Regular --> R2[\"Can run init code\"]:::teal\n Regular --> R3[\"Can re-export names
and define __all__\"]:::teal\n\n Namespace --> N1[\"Multiple directories
can contribute\"]:::green\n Namespace --> N2[\"No init code possible\"]:::red\n Namespace --> N3[\"No __all__ control\"]:::red\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe diagram lays out the trade-off. Regular packages are simpler, more controllable, and the right choice for self-contained projects. Namespace packages provide cross-distribution extensibility at the cost of every package-level feature `__init__.py` provides.\n\nThe two styles can also be mixed within one project: a regular `myapp/` (with `__init__.py`) and a namespace `myapp/plugins/` (without one) that third parties extend. That's a common architecture for plugin-aware applications.\n\n---\n\n# A Full Walkthrough\n\nA complete example that combines everything in the lesson. The layout:\n\n\n```shell\necommerce/\n __init__.py\n cart/\n __init__.py\n operations.py\n discounts.py\n products/\n __init__.py\n catalog.py\n customers/\n __init__.py\n profiles.py\n```\n\n\n`ecommerce/cart/operations.py`:\n\n\n```python\ndef add_item(cart, product, quantity=1):\n cart[product] = cart.get(product, 0) + quantity\n return cart\n\ndef remove_item(cart, product):\n cart.pop(product, None)\n return cart\n```\n\n\n`ecommerce/cart/discounts.py`:\n\n\n```python\ndef apply_percentage(total, percent):\n return total * (1 - percent / 100)\n```\n\n\n`ecommerce/cart/__init__.py`:\n\n\n```python\n\"\"\"Cart operations and discount logic.\"\"\"\n\nfrom ecommerce.cart.operations import add_item, remove_item\nfrom ecommerce.cart.discounts import apply_percentage\n\n__all__ = [\"add_item\", \"remove_item\", \"apply_percentage\"]\n```\n\n\n`ecommerce/products/catalog.py`:\n\n\n```python\nPRICES = {\n \"Wireless Mouse\": 29.99,\n \"USB Cable\": 9.99,\n \"HDMI Cable\": 14.99,\n \"Coffee Mug\": 12.50,\n}\n\ndef is_available(product):\n return product in PRICES\n\ndef price_of(product):\n return PRICES.get(product, 0.0)\n```\n\n\n`ecommerce/products/__init__.py`:\n\n\n```python\n\"\"\"Product catalog and lookups.\"\"\"\n\nfrom ecommerce.products.catalog import PRICES, is_available, price_of\n\n__all__ = [\"PRICES\", \"is_available\", \"price_of\"]\n```\n\n\n`ecommerce/customers/profiles.py`:\n\n\n```python\ndef make_customer(name, email):\n return {\"name\": name, \"email\": email, \"wishlist\": []}\n\ndef add_to_wishlist(customer, product):\n customer[\"wishlist\"].append(product)\n return customer\n```\n\n\n`ecommerce/customers/__init__.py`:\n\n\n```python\n\"\"\"Customer profile helpers.\"\"\"\n\nfrom ecommerce.customers.profiles import make_customer, add_to_wishlist\n\n__all__ = [\"make_customer\", \"add_to_wishlist\"]\n```\n\n\n`ecommerce/__init__.py`:\n\n\n```python\n\"\"\"E-commerce helpers for the AlgoMaster store.\"\"\"\n\nfrom ecommerce.cart import add_item, remove_item, apply_percentage\nfrom ecommerce.products import is_available, price_of\nfrom ecommerce.customers import make_customer, add_to_wishlist\n\n__version__ = \"1.0.0\"\nDEFAULT_CURRENCY = \"USD\"\n\n__all__ = [\n \"add_item\",\n \"remove_item\",\n \"apply_percentage\",\n \"is_available\",\n \"price_of\",\n \"make_customer\",\n \"add_to_wishlist\",\n \"DEFAULT_CURRENCY\",\n]\n```\n\n\nA caller script next to the `ecommerce/` directory:\n\n\n```python\nfrom ecommerce import (\n add_item,\n apply_percentage,\n is_available,\n price_of,\n make_customer,\n)\n\nalice = make_customer(\"Alice\", \"alice@example.com\")\ncart = {}\n\nfor product, qty in [(\"Wireless Mouse\", 2), (\"Coffee Mug\", 1), (\"Unknown\", 5)]:\n if is_available(product):\n add_item(cart, product, qty)\n\nsubtotal = sum(price_of(p) * q for p, q in cart.items())\ntotal = apply_percentage(subtotal, 10)\n\nprint(f\"Customer: {alice['name']}\")\nprint(f\"Cart: {cart}\")\nprint(f\"Subtotal: ${subtotal:.2f}\")\nprint(f\"After 10% discount: ${total:.2f}\")\n```\n\n\nThe caller never had to know which submodule any name lived in. The top-level `ecommerce/__init__.py` re-exports from the subpackage inits, which re-export from their own submodules. Three layers of init files form a clean public API over a deeper internal layout.\n\nIf a maintainer later moves `apply_percentage` from `cart/discounts.py` to a new `cart/promotions.py`, only `ecommerce/cart/__init__.py` needs an update to re-export from the new location. The top-level `__init__.py` doesn't change because it already imports from `ecommerce.cart`, not from the deeper file. The caller doesn't change at all because it imports from `ecommerce`, which still exposes `apply_percentage`. That's the practical payoff of curating a package API through `__init__.py`.","pageType":"python"}

__init__.py File

Get Premium

init.py File