{"title":"Packages","description":"","content":"A single `.py` file is a module. Once your project grows past a handful of modules, you'll want to group related ones together: cart code in one place, product code in another, customer code in a third. That's what a package is. This lesson covers what `__init__.py` actually does, how to structure subpackages, and when you'd skip `__init__.py` entirely and use a namespace package instead.\n\n---\n\n# Module vs Package\n\nA module is one file. A package is a directory of modules with an `__init__.py` file that marks the directory as importable. That's the entire distinction.\n\nIf you have a single file `cart.py`, that's a module. You import it with `import cart`. If you have a directory `ecommerce/` containing `cart.py`, `products.py`, and an `__init__.py`, that's a package. You import its pieces with `import ecommerce.cart` or `from ecommerce import products`.\n\nThe reason packages exist is scale. A 200-line `shop.py` is fine. A 2,000-line file with cart logic, product logic, customer logic, and order logic is painful to navigate. Splitting it into a package lets each concern live in its own file while still being addressable as one thing: `ecommerce`.\n\n\n```mermaid\nflowchart LR\n subgraph Module[\"Module (one file)\"]\n F[\"cart.py\"]:::cyan\n end\n\n subgraph Package[\"Package (directory)\"]\n D[\"ecommerce/\"]:::orange\n I[\"__init__.py\"]:::teal\n C[\"cart.py\"]:::cyan\n P[\"products.py\"]:::cyan\n D --> I\n D --> C\n D --> P\n end\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 structural difference. A module is one file at the top level. A package is a directory whose contents are addressable through the directory name, with `__init__.py` acting as the marker that says \"this directory is a package, not just a folder of loose scripts.\"\n\nThe import syntax mirrors the structure. Once `ecommerce/` is a package, `ecommerce.cart` refers to the `cart` module inside it. The dot is literally the path separator. A deeper structure like `ecommerce/customers/profile.py` is reached with `ecommerce.customers.profile`.\n\n---\n\n# What `__init__.py` Actually Does\n\n`__init__.py` is the file that runs the first time the package is imported. It has two jobs. First, its presence tells Python \"this directory is a regular package.\" Second, any code inside it executes once, sets up the package's namespace, and stays in memory.\n\nStart with the simplest case: an empty `__init__.py`. Empty file, zero bytes. That's enough.\n\nDirectory layout:\n\n\n```shell\necommerce/\n __init__.py (empty)\n cart.py\n products.py\n```\n\n\nContents of `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\ndef cart_total(cart, prices):\n return sum(prices[product] * qty for product, qty in cart.items())\n```\n\n\nContents of `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\nNow from a script next to the `ecommerce/` directory:\n\n\n```python\nfrom ecommerce.cart import add_item, cart_total\nfrom ecommerce.products import PRICES\n\ncart = {}\nadd_item(cart, \"Wireless Mouse\", 2)\nadd_item(cart, \"USB Cable\")\n\nprint(cart)\nprint(f\"Total: ${cart_total(cart, PRICES):.2f}\")\n```\n\n\nThe empty `__init__.py` did one thing: it let Python recognize `ecommerce` as a package so the dotted imports work. No setup code ran because there was none to run.\n\nA populated `__init__.py` is where the package gets interesting. It runs the first time `import ecommerce` (or any submodule import) happens, and never again in the same Python process.\n\nChange `ecommerce/__init__.py` to:\n\n\n```python\nprint(\"ecommerce package initializing\")\n\nPACKAGE_VERSION = \"1.0.0\"\n```\n\n\nNow run:\n\n\n```python\nfrom ecommerce.cart import add_item\nfrom ecommerce.products import PRICES\nimport ecommerce.cart\nimport ecommerce\nprint(ecommerce.PACKAGE_VERSION)\n```\n\n\nThe print statement fires once even though the script imports from the package four times. That's because Python caches imported modules in `sys.modules`. The second import returns the cached object instead of running `__init__.py` again. The `PACKAGE_VERSION` attribute lives on the package itself, accessible as `ecommerce.PACKAGE_VERSION`.\n\n\n> **INFO**\n>\n> **Cost:** Heavy work inside `__init__.py` slows down the first import of the package, even if the caller only needs one tiny function. If your `__init__.py` opens a database connection or loads a 50MB model, every script that touches anything in the package pays for it. Keep `__init__.py` light, and let submodules do their own heavy lifting only when they're imported directly.\n\n\n---\n\n# Re-exports and the Flat Public API\n\nOne of the most useful patterns for `__init__.py` is re-exporting. Submodules live in a tree, but you can present a flat surface to callers. Internally, `ecommerce/cart.py` defines `add_item`. Externally, callers can write `from ecommerce import add_item` if the package's `__init__.py` re-exports it.\n\nUpdate `ecommerce/__init__.py`:\n\n\n```python\nfrom ecommerce.cart import add_item, cart_total\nfrom ecommerce.products import PRICES, is_available\n\nPACKAGE_VERSION = \"1.0.0\"\n```\n\n\nNow both of these work:\n\n\n```python\n# Deep path (still works)\nfrom ecommerce.cart import add_item\n\n# Flat path (works because __init__.py re-exports it)\nfrom ecommerce import add_item, cart_total, PRICES\n```\n\n\nThe flat path is friendlier for users of the package. They don't have to know that `add_item` lives in `cart.py` versus `cart_utils.py` versus somewhere else. The package is the API; the file layout is an implementation detail.\n\nThis pattern shows up everywhere in the standard library. When you write `from collections import Counter`, you're not actually pulling `Counter` from a file called `collections.py`. The `collections` package re-exports `Counter` from one of its internal modules. Same idea: users see a flat API; internally, the code is organized however the maintainers prefer.\n\nThe trade-off is import cost. Every name re-exported in `__init__.py` causes its submodule to be loaded on the first package import. If `ecommerce/__init__.py` does `from ecommerce.cart import add_item`, then `import ecommerce` (even with no explicit cart use) loads `cart.py`. For small packages this is fine. For big packages with expensive submodules, you might choose to re-export only the most common names and leave heavier ones reachable only through their submodule path.\n\n\n```mermaid\nflowchart TD\n User[\"from ecommerce import add_item\"]:::cyan\n Init[\"ecommerce/__init__.py\"]:::orange\n Cart[\"ecommerce/cart.py
defines add_item\"]:::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. exposes add_item\"| 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 when a caller writes `from ecommerce import add_item`. Python loads `__init__.py`, which loads the submodules it re-exports, and the name `add_item` ends up bound on the package's namespace. The caller never has to know that `cart.py` exists.\n\n---\n\n# `__all__` and `from package import *`\n\nWhen a caller writes `from ecommerce import *`, Python has to decide which names to pull in. By default, it imports every name in the package's namespace that doesn't start with an underscore. That's usually too much and not what you want as a package author.\n\n`__all__` is a list of strings that overrides this default. If `__all__` is defined in `__init__.py`, `from package import *` imports exactly those names and nothing else.\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\n__all__ = [\"add_item\", \"cart_total\", \"PRICES\", \"is_available\"]\n```\n\n\nNow in a caller:\n\n\n```python\nfrom ecommerce import *\n\nprint(add_item({}, \"Wireless Mouse\"))\nprint(is_available(\"Wireless Mouse\"))\n\n# _internal_helper was imported into __init__.py but is NOT in __all__,\n# so the star import skips it.\nprint(_internal_helper)\n```\n\n\n`__all__` lets you separate \"names that exist inside the package\" from \"names that are part of the public API.\" Without it, star imports leak whatever happens to be lying around in `__init__.py`'s namespace, which often includes imports that were only meant for internal wiring.\n\nA few people will tell you that `from package import *` is bad practice and you should never write it. That's mostly true for application code, but the convention exists, and tools like linters use `__all__` to figure out what counts as the public API even when no one ever writes a star import. Defining `__all__` is good hygiene either way.\n\n\n> **INFO**\n>\n> **Cost:** `__all__` doesn't change how much code gets executed; it only filters which names are bound after a star import. The submodules still load. If you want to keep submodules unloaded until needed, you have to skip re-exporting them in `__init__.py` entirely, not just leave them out of `__all__`.\n\n\n---\n\n# Subpackages\n\nA package can contain other packages. Each subpackage is a directory with its own `__init__.py`, and the same rules apply at every level. The dotted import path mirrors the directory tree exactly.\n\nFor a real-sized e-commerce project, you'd group related modules into subpackages:\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 customers/\n __init__.py\n profiles.py\n addresses.py\n```\n\n\nEach subpackage is independent. `ecommerce/cart/__init__.py` is unrelated to `ecommerce/products/__init__.py`. They each get their own initialization, their own namespace, and their own `__all__` if you choose to define one.\n\nContents of `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\nContents of `ecommerce/cart/discounts.py`:\n\n\n```python\ndef apply_percentage(total, percent):\n return total * (1 - percent / 100)\n\ndef apply_flat(total, amount):\n return max(0, total - amount)\n```\n\n\nContents of `ecommerce/cart/__init__.py`:\n\n\n```python\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\nA caller can now use any of these import shapes:\n\n\n```python\n# Through the subpackage namespace\nfrom ecommerce.cart import add_item, apply_percentage\n\n# Or directly from a specific module inside the subpackage\nfrom ecommerce.cart.discounts import apply_flat\n\ncart = {}\nadd_item(cart, \"Wireless Mouse\", 2)\ntotal = 60.00\nprint(f\"After 10% off: ${apply_percentage(total, 10):.2f}\")\nprint(f\"After $5 off: ${apply_flat(total, 5):.2f}\")\n```\n\n\nThe top-level `ecommerce/__init__.py` can re-export from subpackages too. If you want users to call `from ecommerce import add_item` without thinking about the cart subpackage at all, write:\n\n\n```python\n# ecommerce/__init__.py\nfrom ecommerce.cart import add_item, remove_item, apply_percentage, apply_flat\nfrom ecommerce.products.catalog import is_available\nfrom ecommerce.customers.profiles import Customer\n\n__all__ = [\n \"add_item\",\n \"remove_item\",\n \"apply_percentage\",\n \"apply_flat\",\n \"is_available\",\n \"Customer\",\n]\n```\n\n\nHow aggressive to be with top-level re-exports is a style choice. A flat API is easier for users; a layered API is easier to evolve internally without breaking callers. Many libraries do both: a flat top-level for the 10 names most callers want, plus the full deep paths for everything else.\n\n\n```mermaid\nflowchart TD\n Root[\"ecommerce/\"]:::orange\n RootInit[\"__init__.py
(top-level re-exports)\"]:::cyan\n\n Cart[\"cart/\"]:::orange\n CartInit[\"__init__.py\"]:::cyan\n CartOps[\"operations.py\"]:::teal\n CartDisc[\"discounts.py\"]:::teal\n\n Products[\"products/\"]:::orange\n ProductsInit[\"__init__.py\"]:::cyan\n Catalog[\"catalog.py\"]:::teal\n Search[\"search.py\"]:::teal\n\n Customers[\"customers/\"]:::orange\n CustomersInit[\"__init__.py\"]:::cyan\n Profiles[\"profiles.py\"]:::teal\n Addresses[\"addresses.py\"]:::teal\n\n Root --> RootInit\n Root --> Cart\n Root --> Products\n Root --> Customers\n\n Cart --> CartInit\n Cart --> CartOps\n Cart --> CartDisc\n\n Products --> ProductsInit\n Products --> Catalog\n Products --> Search\n\n Customers --> CustomersInit\n Customers --> Profiles\n Customers --> Addresses\n\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nEach directory in the tree is a package with its own `__init__.py`. Each `.py` file inside is a module. The dotted import path follows the tree: `ecommerce.cart.discounts.apply_flat` is the file path with dots instead of slashes and no `.py` extension.\n\n---\n\n# Common Package Layouts\n\nFor a typical small-to-medium project, the layout looks like this:\n\n\n```shell\nmy_shop/\n pyproject.toml\n README.md\n src/\n ecommerce/\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 customers/\n __init__.py\n profiles.py\n addresses.py\n orders/\n __init__.py\n placement.py\n tracking.py\n tests/\n test_cart.py\n test_products.py\n```\n\n\nA few things worth noting:\n\n- The `src/` layout puts the package one level below the project root. It's a common convention (called the \"src layout\") that prevents accidental imports of the in-development version when running tests. The alternative \"flat layout\" puts `ecommerce/` directly at the project root.\n- Tests live in a separate top-level `tests/` directory, not inside the package. Mixing them inside makes shipping the package harder later.\n- Each subpackage corresponds to a domain concern: cart, products, customers, orders. Files inside each subpackage split that domain further: `cart/operations.py` for adding and removing items, `cart/discounts.py` for discount logic.\n\nThere's no rule that every subpackage needs more than one file. If `customers/` only has `profiles.py` today, that's fine. The subpackage exists so that when `customers/` grows to need `addresses.py` and `preferences.py` and `auth.py`, they have a natural home and you don't have to rename anything.\n\nFor very small projects (one or two files), don't bother with a package at all. A single `shop.py` is more readable than `shop/__init__.py` + `shop/main.py`. Packages start paying off when you have more than three or four related modules.\n\n---\n\n# Relative Imports Inside a Package\n\nInside a package, modules can refer to each other with relative imports. A dot means \"current package,\" two dots mean \"parent package.\" This is mostly a convenience: relative imports keep working when the package gets renamed.\n\nFor example, inside `ecommerce/cart/operations.py`, you might want to use a helper from `ecommerce/cart/discounts.py`. Two ways to write it:\n\n\n```python\n# Absolute import (always works)\nfrom ecommerce.cart.discounts import apply_percentage\n\n# Relative import (equivalent here, but breaks if used from a script)\nfrom .discounts import apply_percentage\n```\n\n\nThe single dot means \"look in the current package,\" which from `operations.py`'s perspective is `ecommerce.cart`. Two dots would walk up one level to `ecommerce` itself, so `from ..products.catalog import is_available` inside `cart/operations.py` would reach `ecommerce/products/catalog.py`.\n\nRelative imports only work inside actual packages, not in top-level scripts. If you try to run a file with relative imports directly (`python operations.py`), you'll get `ImportError: attempted relative import with no known parent package`. They only resolve when the module is loaded as part of a package, which is the normal case once everything is wired up correctly.\n\nMost teams pick one style and stick with it. Absolute imports are more explicit; relative imports survive renames better. Both are fine.\n\n---\n\n# Namespace Packages (No `__init__.py`)\n\nPython supports a second kind of package called a namespace package, introduced by PEP 420 in Python 3.3. A namespace package is a directory **without** an `__init__.py` that Python still treats as importable.\n\nThe motivation: large projects sometimes want to split a single logical package across multiple directories or even multiple installed distributions. With a regular package, you can't do that, because only one `__init__.py` can \"own\" the package name. Namespace packages let multiple directories contribute to the same dotted name, as long as none of them has an `__init__.py`.\n\nExample layout:\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 the Python 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 has an `__init__.py`.\n\nFor most projects, you don't want this. The pitfalls are real:\n\n- No initialization code, ever. You lose `__init__.py`'s ability to set up package state or re-export names.\n- Silent merging. If two directories on the path happen to share a top-level name, Python merges them. This can mask typos and cause weird \"where did this module come from?\" debugging sessions.\n- Tools like `setup.py` and `pyproject.toml` need extra configuration to handle namespace packages correctly when packaging for distribution.\n- Some editors and type checkers handle namespace packages less smoothly than regular packages.\n\nRule of thumb: use a regular package with an `__init__.py` for everything you build, even when it's empty. Reach for namespace packages only when you have a specific reason, like distributing plugins where third parties extend your package from their own installed wheels.\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\"]:::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 shows the trade-off side by side. Regular packages are simpler and more controllable. Namespace packages buy you a specific extensibility feature in exchange for losing initialization and re-export control.\n\n---\n\n# Putting It All Together\n\nA complete walkthrough using everything covered so far. Here's the final 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\nContents of `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\nContents of `ecommerce/cart/discounts.py`:\n\n\n```python\ndef apply_percentage(total, percent):\n return total * (1 - percent / 100)\n```\n\n\nContents of `ecommerce/cart/__init__.py`:\n\n\n```python\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\nContents of `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\nContents of `ecommerce/products/__init__.py`:\n\n\n```python\nfrom ecommerce.products.catalog import PRICES, is_available, price_of\n\n__all__ = [\"PRICES\", \"is_available\", \"price_of\"]\n```\n\n\nContents of `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\nContents of `ecommerce/customers/__init__.py`:\n\n\n```python\nfrom ecommerce.customers.profiles import make_customer, add_to_wishlist\n\n__all__ = [\"make_customer\", \"add_to_wishlist\"]\n```\n\n\nContents of `ecommerce/__init__.py`:\n\n\n```python\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\nPACKAGE_VERSION = \"1.0.0\"\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]\n```\n\n\nNow a 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\n# Build a customer and a cart.\nalice = make_customer(\"Alice\", \"alice@example.com\")\ncart = {}\n\n# Add items, skipping any that aren't available.\nfor product, qty in [(\"Wireless Mouse\", 2), (\"Coffee Mug\", 1), (\"Unknown Item\", 5)]:\n if is_available(product):\n add_item(cart, product, qty)\n\n# Compute the total.\nsubtotal = sum(price_of(product) * qty for product, qty 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\nEvery name the caller uses came from the flat `from ecommerce import ...` line. The actual code lives in five different files across three subpackages, but the caller doesn't have to know that. The package's `__init__.py` files do the work of presenting a clean surface.\n\nIf a maintainer later moves `apply_percentage` from `cart/discounts.py` to a new `cart/promotions.py`, they only have to update `ecommerce/cart/__init__.py` to re-export it from the new location. Every caller that did `from ecommerce import apply_percentage` keeps working with zero changes. That's the practical payoff of structuring a package well.","pageType":"python"}

Packages

Get Premium