{"title":"import Statement","description":"","content":"Every non-trivial Python program splits its code across multiple files and pulls those files back together with `import`. The statement looks small, but it carries a lot of behavior: locating the file, executing it once, caching the result, and binding names into the current scope. This lesson walks through every form of import you'll see in real code, where Python looks for the file, what happens when the import succeeds (or fails), and the conventions PEP 8 expects you to follow.\n\n---\n\n# `import module` and Qualified Access\n\nThe simplest form of import is `import` followed by a module name. The module gets loaded, and a name pointing to the module object is bound in the current scope. You then reach into the module using dot notation.\n\n\n```python\nimport math\n\nprint(math.sqrt(16))\nprint(math.pi)\n```\n\n\n`import math` doesn't pull `sqrt` or `pi` into your file's namespace. It pulls the `math` module itself in, under the name `math`, and you reach the contents through `math.something`. That qualified access is the point: when you read `math.sqrt(16)`, you know exactly where `sqrt` came from. No guessing.\n\nThe same pattern works for modules you write yourself. Suppose you have an e-commerce app with a file named `pricing.py` sitting next to your main script.\n\n\n```python\n# pricing.py\ndef apply_discount(price, percent):\n return price * (1 - percent / 100)\n\nTAX_RATE = 0.08\n```\n\n\n\n```python\n# main.py\nimport pricing\n\ndiscounted = pricing.apply_discount(99.99, 10)\nprint(f\"After discount: ${discounted:.2f}\")\nprint(f\"Tax rate: {pricing.TAX_RATE}\")\n```\n\n\n`import pricing` runs `pricing.py` once and binds the resulting module to the name `pricing` in `main.py`. Functions, classes, and module-level variables are all reached the same way: `pricing.apply_discount`, `pricing.TAX_RATE`, and so on.\n\nThere's a small detail worth being explicit about: the name you bind is the module's name, not the file path. `import pricing` works because `pricing.py` is on Python's search path. You never write `import pricing.py` and you never write `import \"./pricing.py\"`. Python takes a bare identifier and figures out which file (or package) that maps to.\n\n---\n\n# `from module import name`\n\nThe second form pulls specific names out of a module and binds them directly into your current scope. You don't need the qualifier anymore.\n\n\n```python\nfrom math import sqrt, pi\n\nprint(sqrt(16))\nprint(pi)\n```\n\n\n`from math import sqrt, pi` runs `math` (just like `import math` would), then takes only `sqrt` and `pi` out of it and binds those two names directly. The module itself is not bound, so `math.sqrt` would now fail with `NameError`.\n\nThis form is convenient when you use a few names from a module repeatedly. Calling `apply_discount` ten times reads better than `pricing.apply_discount` ten times.\n\n\n```python\n# main.py\nfrom pricing import apply_discount, TAX_RATE\n\nfor price in [99.99, 49.99, 19.99]:\n final = apply_discount(price, 10) * (1 + TAX_RATE)\n print(f\"${price:.2f} -> ${final:.2f}\")\n```\n\n\nThe trade-off is information loss. When you read `apply_discount(99.99, 10)` halfway through a file, you can't tell at a glance whether that function came from `pricing`, from some other local module, or from a third-party library. With `import pricing` and `pricing.apply_discount(...)`, the source is right there in the call. The right choice depends on how often you use the names and how readable the qualified form is in context.\n\nYou can import any number of names in one `from` statement, separated by commas. For long lists, wrap them in parentheses across multiple lines.\n\n\n```python\nfrom pricing import (\n apply_discount,\n apply_tax,\n apply_shipping,\n round_to_cents,\n)\n```\n\n\nThis isn't a tuple. The parentheses are purely syntactic; they let the statement span multiple lines without backslash continuation. Most linters and formatters prefer this layout once a single line gets long.\n\n\n> **INFO**\n>\n> **Cost:** Both `import math` and `from math import sqrt` execute the module body once. Picking one form over the other doesn't change loading cost. The difference is only in what names get bound in your scope.\n\n\n---\n\n# Aliasing with `as`\n\nSometimes the name you'd be bound to isn't what you want. Maybe it's too long. Maybe it conflicts with another name you're already using. The `as` keyword renames the binding at import time.\n\n\n```python\nimport numpy as np\n\nprices = np.array([29.99, 14.99, 9.99, 49.99])\nprint(np.mean(prices))\n```\n\n\n`import numpy as np` loads the `numpy` module and binds it under the name `np` in the current scope. The name `numpy` is not bound. This pattern is so ingrained in the data ecosystem that you'll see `import pandas as pd` and `import matplotlib.pyplot as plt` in nearly every example online. The aliases are conventions, not rules, but following them makes your code instantly familiar to other readers.\n\nYou can also alias individual imports inside a `from` statement.\n\n\n```python\nfrom pricing import apply_discount as discount, TAX_RATE as tax\nprint(discount(100, 25))\nprint(tax)\n```\n\n\n`apply_discount` is now reachable as `discount`, and `TAX_RATE` as `tax`. The original names aren't bound. The most common practical use is conflict resolution: if your file already has a function called `apply_discount` and you also want one from `pricing`, you alias the imported one to avoid shadowing your local definition.\n\n\n```python\nfrom pricing import apply_discount as apply_pricing_discount\n\ndef apply_discount(price, code):\n if code == \"WELCOME10\":\n return apply_pricing_discount(price, 10)\n return price\n\nprint(apply_discount(99.99, \"WELCOME10\"))\n```\n\n\nWithout the alias, the `from pricing import apply_discount` would clobber the local `apply_discount` (or vice versa, depending on order), and the result would be a silent bug. The alias makes the two functions distinct names.\n\n---\n\n# `from module import *` and `__all__`\n\nThere's a fourth form: `from module import *`. It pulls every public name out of the module and binds each of them directly into your scope.\n\n\n```python\nfrom math import *\n\nprint(sqrt(16))\nprint(pi)\nprint(cos(0))\n```\n\n\nThis looks convenient at first glance. You skip writing out names; everything is just there. But the cost is real. You don't know what names got bound, you don't know whether any of them conflict with names you already had, and a reader of your code has no way to tell where `sqrt` or `cos` came from.\n\nHere's the classic problem.\n\n\n```python\nfrom math import *\nfrom cmath import *\n\nprint(sqrt(-1))\n```\n\n\nBoth `math` and `cmath` define `sqrt`. The second import silently shadowed the first. If you'd expected `math.sqrt(-1)` to raise (which it does for negative input), you wouldn't get that behavior, because `sqrt` now refers to the complex-number version. The bug is invisible at the call site.\n\nFor these reasons, **PEP 8 discourages `from module import *` in production code**. It's tolerable in interactive sessions or quick scripts where you're exploring, but in any file you'll read again, name your imports.\n\nThe `__all__` attribute controls what `import *` exports. If a module defines a list named `__all__`, only those names are pulled in by `import *`. Without `__all__`, every name not starting with an underscore is exported.\n\n\n```python\n# pricing.py\n__all__ = [\"apply_discount\", \"TAX_RATE\"]\n\ndef apply_discount(price, percent):\n return price * (1 - percent / 100)\n\ndef _internal_helper(x):\n return x * 2\n\nTAX_RATE = 0.08\nINTERNAL_CONSTANT = 42\n```\n\n\n\n```python\n# main.py\nfrom pricing import *\n\nprint(apply_discount(100, 10))\nprint(TAX_RATE)\nprint(INTERNAL_CONSTANT)\n```\n\n\nEven though `INTERNAL_CONSTANT` doesn't start with an underscore, it isn't in `__all__`, so `import *` doesn't bring it in. `__all__` is also the closest thing Python has to a \"public API\" declaration. Tools, IDEs, and documentation generators read it to know which names a module officially exposes.\n\n\n> **INFO**\n>\n> **Cost:** `from module import *` doesn't just pollute the namespace, it makes static analysis harder. Linters and type checkers can't always tell which names are defined, so warnings about \"undefined name\" become unreliable.\n\n\n---\n\n# Where Python Looks for Modules: `sys.path`\n\nWhen you write `import pricing`, Python doesn't search your whole disk. It walks through a specific, ordered list of directories called `sys.path`. The first directory containing a `pricing.py` (or a `pricing/` package) wins.\n\n\n```python\nimport sys\nfor path in sys.path:\n print(path)\n```\n\n\nThe exact contents vary by system and Python install. What matters is the order. `sys.path` is built from three sources, roughly in this order:\n\n1. The directory of the script you're running (or an empty string `\"\"` meaning current working directory, when you're in the REPL).\n2. The directories listed in the `PYTHONPATH` environment variable, if set.\n3. The standard library directories that ship with Python.\n4. The `site-packages` directory where `pip` installs third-party packages.\n\n\n```mermaid\nflowchart TD\n START[\"import pricing\"]:::cyan\n P1[\"Check script's directory
(or CWD)\"]:::orange\n P2[\"Check PYTHONPATH
directories\"]:::orange\n P3[\"Check standard library
directories\"]:::orange\n P4[\"Check site-packages
(pip-installed)\"]:::orange\n FOUND[\"Run pricing.py once
Cache in sys.modules\"]:::green\n FAIL[\"ModuleNotFoundError\"]:::red\n\n START --> P1\n P1 -->|found| FOUND\n P1 -->|not found| P2\n P2 -->|found| FOUND\n P2 -->|not found| P3\n P3 -->|found| FOUND\n P3 -->|not found| P4\n P4 -->|found| FOUND\n P4 -->|not found| FAIL\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 red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nPython takes the first match it finds. If `pricing.py` exists in both your project directory and somewhere on `PYTHONPATH`, the project directory wins because it comes first. This is mostly invisible, but it occasionally bites: if you name a local file `math.py`, you've shadowed the standard library `math`, and `import math` will load your file instead.\n\nThe standard library lives in directories that came with Python. `site-packages` is where `pip install requests` puts the `requests` package. You don't normally interact with these paths directly; the import system does it for you. But knowing the order helps when an import behaves unexpectedly: print `sys.path` and trace where Python would have looked.\n\nYou can modify `sys.path` at runtime, though it's a code smell in most situations. The cleaner ways to make your code importable are: organize files into packages, install with `pip`, or set `PYTHONPATH` outside Python. `sys.path` modification is mentioned here mainly so the mechanism isn't a mystery.\n\n\n```python\nimport sys\nsys.path.append(\"/some/other/directory\")\nimport pricing # now Python can find pricing.py there\n```\n\n\nThis works, but if you find yourself reaching for it often, the project layout is probably the real problem.\n\n---\n\n# Import Caching: `sys.modules`\n\nPython only runs a module's body **once per process**, no matter how many times it's imported. The first import does the work; every later import just returns the already-loaded module.\n\nThe cache lives in `sys.modules`, a dictionary mapping module names to module objects.\n\n\n```python\n# pricing.py\nprint(\"Running pricing.py top-level code\")\nTAX_RATE = 0.08\n```\n\n\n\n```python\n# main.py\nimport pricing\nimport pricing\nimport pricing\n\nprint(\"Done importing\")\n```\n\n\nThe `print` inside `pricing.py` runs exactly once. The second and third `import pricing` statements find `pricing` already in `sys.modules` and bind the cached module object without re-executing the file.\n\nThis caching is what makes import statements cheap. Once a module is loaded, importing it again costs about as much as a dictionary lookup. It also means top-level code in a module behaves like initialization: it runs once and sets up state, and every other file in the program sees the same state.\n\nYou can inspect the cache directly.\n\n\n```python\nimport sys\nimport pricing\n\nprint(\"pricing\" in sys.modules)\nprint(sys.modules[\"pricing\"] is pricing)\n```\n\n\nThe module object stored in `sys.modules[\"pricing\"]` is the exact same object bound to the name `pricing` in your scope. Every other file that imports `pricing` gets that same object too. There's only one `pricing` module per process.\n\nThis has a practical consequence. If you edit `pricing.py` while a Python session is running, just re-running `import pricing` won't pick up your changes. The cache says \"already loaded\", so the new file content is ignored. For long-running sessions (notebooks, REPLs), use `importlib.reload`.\n\n\n```python\nimport importlib\nimport pricing\n\nimportlib.reload(pricing)\n```\n\n\n`importlib.reload` re-executes the module body and updates the cached object in place. Other modules that already imported names from `pricing` may still hold references to the old definitions, though, which makes `reload` unreliable for anything beyond simple cases. In production code you usually restart the process instead.\n\n---\n\n# Absolute vs Relative Imports\n\nSo far every import has used an **absolute** name: the full path to the module from the top of the package structure. Absolute imports are the default and the recommended style for almost all cases.\n\n\n```python\n# anywhere in the project\nfrom shop.pricing import apply_discount\nfrom shop.cart.checkout import finalize_order\n```\n\n\nThese work no matter where the importing file lives, because the path is fully qualified. `shop.pricing` always means the `pricing` module inside the top-level `shop` package.\n\nInside a package, you can also use **relative** imports, which reference modules by their position relative to the current file. A relative import starts with one or more dots: `.` means \"the current package\", `..` means \"the parent package\", and so on.\n\n\n```python\n# shop/cart/checkout.py\nfrom .items import CartItem # current package: shop.cart\nfrom ..pricing import apply_discount # parent package: shop\n```\n\n\nThe single dot in `from .items import CartItem` says \"look in the same package as this file\". Since `checkout.py` lives in `shop/cart/`, the import resolves to `shop.cart.items`.\n\nThe double dots in `from ..pricing import apply_discount` say \"look one package up\". That resolves to `shop.pricing`.\n\n\n```mermaid\nflowchart TD\n SHOP[\"shop/\"]:::cyan\n PRICING[\"pricing.py\"]:::orange\n CART[\"cart/\"]:::cyan\n CHECKOUT[\"checkout.py\"]:::orange\n ITEMS[\"items.py\"]:::orange\n\n SHOP --> PRICING\n SHOP --> CART\n CART --> CHECKOUT\n CART --> ITEMS\n\n CHECKOUT -.->|\"from .items\"| ITEMS\n CHECKOUT -.->|\"from ..pricing\"| PRICING\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 red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe dashed arrows show what each relative import resolves to. `.items` stays in `cart/`. `..pricing` walks up to `shop/` and finds `pricing.py` there.\n\nRelative imports only work inside packages. If you try a relative import in a top-level script (one you run directly as `python checkout.py`), you'll see this:\n\n\n```shell\nImportError: attempted relative import with no known parent package\n```\n\n\nThe error means Python can't figure out what \"the current package\" is, because the file is being run as the main script, not imported as part of a package. The fix is either to switch to absolute imports or to run the file as a module: `python -m shop.cart.checkout`.\n\n**When to use which:**\n\n\n| Style | Example | Best for |\n|---|---|---|\n| Absolute | `from shop.pricing import apply_discount` | Almost everything. Clear, unambiguous, works from anywhere. |\n| Relative | `from .items import CartItem` | Sibling imports inside a package, especially when the package might be renamed. |\n\n\nPEP 8 recommends absolute imports as the default. Relative imports are acceptable inside a package when they keep things short and the file is firmly part of a package structure. Avoid going more than one level up (`...` or `....`) because it gets hard to follow and often signals a layout problem.\n\nHere we're only looking at the import syntax.\n\n---\n\n# Common Import Errors\n\nImports fail in a handful of recognizable ways. Recognizing the error type is half the fix.\n\n### `ModuleNotFoundError`\n\nThe module you asked for doesn't exist anywhere on `sys.path`.\n\n\n```python\nimport shipping_calculator\n```\n\n\nCommon causes:\n\n- Typo in the module name (`shiping_calculator` vs `shipping_calculator`).\n- The file isn't in any directory on `sys.path` (run `import sys; print(sys.path)` to see).\n- For third-party packages, you haven't installed it (`pip install package-name`).\n- You're running from the wrong working directory, so the project root isn't first on `sys.path`.\n\n`ModuleNotFoundError` is a subclass of `ImportError`, so catching `ImportError` catches both.\n\n### `ImportError`\n\nThe module exists, but the specific name you tried to import from it doesn't.\n\n\n```python\nfrom math import square_root\n```\n\n\n`math` loaded fine, but it has no name called `square_root`. The fix is either to use the correct name (`sqrt`) or to check what the module actually exports.\n\n### Circular Imports\n\nA circular import happens when two modules import from each other, directly or through a chain. Module `A` imports `B`, and `B` (during its own loading) tries to import `A`. At that moment, `A` is only partially loaded, so some of its names don't exist yet.\n\n\n```python\n# cart.py\nfrom pricing import apply_discount\n\ndef calculate_total(items):\n return sum(apply_discount(item.price, 10) for item in items)\n```\n\n\n\n```python\n# pricing.py\nfrom cart import calculate_total\n\ndef apply_discount(price, percent):\n return price * (1 - percent / 100)\n```\n\n\nRunning `python cart.py` produces:\n\n\n```shell\nTraceback (most recent call last):\n File \"cart.py\", line 1, in \n from pricing import apply_discount\n File \"pricing.py\", line 1, in \n from cart import calculate_total\nImportError: cannot import name 'calculate_total' from partially initialized module 'cart' (most likely due to a circular import)\n```\n\n\nThe trace shows the problem clearly: `cart` started loading, hit `from pricing import apply_discount`, which started loading `pricing`, which then tried to import `calculate_total` from `cart`, which hadn't finished defining `calculate_total` yet.\n\n\n```mermaid\nflowchart LR\n CART[\"cart.py
(loading)\"]:::orange\n PRICING[\"pricing.py
(loading)\"]:::orange\n FAIL[\"ImportError:
partially initialized
module\"]:::red\n\n CART -->|\"from pricing import...\"| PRICING\n PRICING -.->|\"from cart import calculate_total
(not defined yet)\"| FAIL\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 red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThree common fixes, in order of preference:\n\n1. **Restructure.** If `cart` needs `pricing` and `pricing` needs `cart`, one of them probably belongs in a third module both can import. Pull the shared logic out.\n2. **Import the module, not a name.** `import pricing` inside `cart.py` (and use `pricing.apply_discount`) often works where `from pricing import apply_discount` fails, because the module object exists in `sys.modules` even when it's partially loaded.\n3. **Import inside the function.** Move the import from the top of the file to inside the function that needs it. By the time the function runs, both modules are fully loaded.\n\n\n```python\n# cart.py - fix 3 example\ndef calculate_total(items):\n from pricing import apply_discount # imported lazily\n return sum(apply_discount(item.price, 10) for item in items)\n```\n\n\nThe lazy import works because the `from pricing import apply_discount` line doesn't run at module load time. It runs the first time `calculate_total` is called, by which point both modules have finished initializing.\n\n\n> **INFO**\n>\n> **Cost:** Circular imports usually point to a design issue. Lazy imports inside functions hide the problem but add a tiny per-call cost (a dict lookup in `sys.modules`). For hot code paths, prefer fixing the structure.\n\n\n---\n\n# Convention: Top-of-File Imports and PEP 8 Ordering\n\nTwo style rules show up in nearly every Python codebase, and PEP 8 codifies both.\n\n**Rule 1: Put imports at the top of the file.** After the module docstring and any future imports, before any module-level code. Imports are statements, and you can technically write them anywhere, but putting them all at the top means a reader can see every external dependency in one glance.\n\n\n```python\n\"\"\"Pricing utilities for the shop application.\"\"\"\n\nfrom __future__ import annotations # future imports first\n\nimport os\nimport sys\n\nimport requests\n\nfrom shop.pricing import apply_discount\n\n# module code starts here\nTAX_RATE = 0.08\n\ndef calculate_total(items):\n ...\n```\n\n\n**Rule 2: Group imports into three sections, in this order, separated by blank lines.**\n\n1. Standard library imports (`os`, `sys`, `math`, ...)\n2. Third-party imports (`requests`, `numpy`, `pandas`, ...)\n3. Local application imports (your own modules)\n\nWithin each group, sort the imports alphabetically. This isn't strictly required by Python; it just makes diffs cleaner and conflicts rarer. Tools like `isort` and `ruff` will sort imports for you automatically.\n\n\n```python\n# Standard library\nimport json\nimport os\nfrom datetime import datetime\n\n# Third-party\nimport requests\nfrom sqlalchemy import create_engine\n\n# Local\nfrom shop.cart import Cart\nfrom shop.pricing import apply_discount\n```\n\n\nThe three groups make the import dependency graph readable at a glance: what does this file need from Python itself, what does it need from packages we installed, and what does it need from inside our own project.\n\nThere are two situations where imports legitimately appear lower in the file:\n\n- **Inside a function** to break a circular import, as shown earlier.\n- **Conditional imports** that depend on platform or optional dependencies.\n\n\n```python\nimport sys\n\nif sys.platform == \"win32\":\n import winreg\nelse:\n import os\n```\n\n\nFor everything else, keep imports at the top.\n\n---\n\n# A Quick Tour of All the Forms\n\nBefore the exercises, here's a compact table of every import form covered in this lesson and what each one binds in your scope.\n\n\n| Statement | Names bound in your scope | Typical use |\n|---|---|---|\n| `import math` | `math` | Default form; clearest source attribution. |\n| `import math as m` | `m` | Aliasing a module (e.g., `np`, `pd`). |\n| `from math import sqrt` | `sqrt` | Pulling a few specific names you'll use a lot. |\n| `from math import sqrt, pi` | `sqrt`, `pi` | Same, multiple names at once. |\n| `from math import sqrt as s` | `s` | Renaming an imported name to avoid conflict. |\n| `from math import *` | Everything in `math.__all__` or all public names | Avoid in production code. |\n| `from .sibling import x` | `x` | Relative import: same package as current file. |\n| `from ..parent import x` | `x` | Relative import: parent package of current file. |\n\n\nEvery form runs the target module's body once (the first time), caches it in `sys.modules`, and then binds whichever names the syntax says to bind. The differences are entirely about what ends up named in your scope and how readable the result is.","pageType":"python"}

import Statement

Get Premium