{"title":"from...import","description":"","content":"The plain `import module` form is the safest shape of import, but it isn't always the most convenient. When you call `pricing.cart_total` ten times in a function, the prefix adds noise. `from...import` pulls specific names out of a module and binds them straight into your scope, so the prefix is no longer needed. This lesson covers the full mechanics of `from...import`, including renames with `as`, the `import *` form, what `__all__` does, relative imports inside packages, and circular-import problems.\n\n---\n\n# `from module import name`: What Actually Changes\n\n`from module import name` does two things. It loads the module the same way `import module` would, and then it binds **only** the named attribute (not the module itself) into your scope. The second half is what makes the rest of the lesson clear.\n\nA small example using the standard library:\n\n\n```python\nfrom math import sqrt\n\nprint(sqrt(16))\n```\n\n\nTwo things happened during that import. Python ran the `math` module's body and cached the module object in `sys.modules`. Then Python looked up the attribute `sqrt` on that module object and bound the name `sqrt` in the current file's scope.\n\nThe name `math` did **not** get bound. Calling `math.pi` right after that import raises `NameError: name 'math' is not defined`. The module is loaded and cached, but the only name your scope has is the one requested:\n\n\n```python\nfrom math import sqrt\n\nprint(sqrt(16))\nprint(math.pi)\n```\n\n\nThat's the core distinction from `import math`, which binds `math` (the whole module) and contents are reached through `math.sqrt`. Both forms run the module body. The difference is what ends up named in your scope.\n\nThe same rule holds for your own modules. Consider a `pricing.py` next to your main script:\n\n\n```python\n# pricing.py\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```\n\n\nImporting only `cart_total`:\n\n\n```python\n# shop.py\nfrom pricing import cart_total\n\nprint(cart_total([29.99, 14.99, 9.99]))\n```\n\n\nIn `shop.py`, the names `pricing`, `TAX_RATE`, and `apply_discount` are not bound. Only `cart_total` is. The module is fully loaded and visible in `sys.modules`, but the file only has the single name requested.\n\n\n```mermaid\nflowchart LR\n Stmt[\"from pricing import cart_total\"]:::cyan\n Load[\"load pricing.py
once, cache it\"]:::orange\n Look[\"look up
pricing.cart_total\"]:::teal\n Bind[\"bind name
cart_total in scope\"]:::green\n Note[\"pricing and TAX_RATE
are NOT bound\"]:::red\n\n Stmt --> Load --> Look --> Bind\n Bind --> Note\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 four steps. The load and cache happen regardless of which import form is used. The difference comes in the binding step: a plain `import` binds the module name; `from...import` binds the requested attribute and leaves everything else in the module unreachable from your scope.\n\nThis matters when reading someone else's code. A `cart_total(...)` call deep in a function doesn't reveal where `cart_total` came from. With `import pricing` and `pricing.cart_total(...)`, the source is in the call. Both styles are valid; the trade-off is between brevity and traceability.\n\n---\n\n# Importing Multiple Names at Once\n\nA single `from` statement can import multiple names, separated by commas:\n\n\n```python\nfrom pricing import cart_total, apply_discount, TAX_RATE\n\nprint(cart_total([29.99, 14.99]))\nprint(apply_discount(99.99, 10))\nprint(TAX_RATE)\n```\n\n\nAll three names are bound in one statement. Python loads `pricing` once (or reuses the cache if it's already loaded) and looks up each attribute in turn.\n\nWhen the list gets long, wrap it in parentheses so it can span multiple lines:\n\n\n```python\nfrom pricing import (\n cart_total,\n apply_discount,\n apply_tax,\n round_to_cents,\n TAX_RATE,\n SHIPPING_THRESHOLD,\n)\n```\n\n\nThe parentheses are pure syntax. They aren't a tuple, and they don't change behavior. They let the statement break across lines without a backslash continuation. This style is common once the import list gets past about three names, because it's easier to read and produces cleaner diffs when imports get added or removed.\n\nFormatters like `black` and `ruff format` reflow imports into this style automatically. `isort` and `ruff`'s import sorter sort the names alphabetically inside the parentheses. None of this is required by Python, but it appears in most maintained projects.\n\nImporting five names from one module is no more expensive than importing one. The module body runs once on first import; the rest is attribute lookups, which are cheap. Trim imports for clarity, not performance.\n\n---\n\n# Renaming on Import with `as`\n\nThe `as` keyword renames the binding at import time. The original name isn't bound; only the alias is.\n\nA common convention is in data libraries:\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 `numpy` and binds it under the name `np`. The name `numpy` itself isn't bound, so calling `numpy.mean` raises `NameError`. This alias is a widely followed convention; matching it makes the code familiar to other readers.\n\n`as` works the same way inside `from...import`. Each name in the list can have its own alias:\n\n\n```python\nfrom pricing import apply_discount as discount, TAX_RATE as tax\n\nprint(discount(100, 25))\nprint(tax)\n```\n\n\nTwo reasons to do this in code: the original name is awkwardly long, or it clashes with something else in your scope. The clash case is the more common one. Consider a file that already defines a function called `apply_discount` with its own coupon-code logic, and also wants the simpler percentage version from `pricing.py`:\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\"))\nprint(apply_discount(99.99, \"NO_CODE\"))\n```\n\n\nWithout the alias, the import would clobber the local `apply_discount` (or the other way around, depending on order). The alias keeps both names alive: the local `apply_discount` and the imported `apply_pricing_discount` it delegates to.\n\nAliasing also helps when importing the same name from two different modules and keeping them distinct:\n\n\n```python\nfrom shop.cart import total as cart_total\nfrom shop.shipping import total as shipping_total\n\ncart = [29.99, 14.99]\nweights = [2.5, 1.0]\n\nprint(cart_total(cart))\nprint(shipping_total(weights))\n```\n\n\nBoth modules call their function `total`, a reasonable name inside each module. The aliases let the importer keep both around without conflict.\n\n---\n\n# `from module import *`: The Star Import\n\nA fourth form, `from module import *`, pulls every public name from the module into your scope at once.\n\n\n```python\nfrom math import *\n\nprint(sqrt(16))\nprint(pi)\nprint(cos(0))\n```\n\n\nAt first glance, this looks like a shortcut. Listing names is skipped; everything is available. In practice, star imports cause problems in larger codebases, and PEP 8 discourages them.\n\nThree things go wrong with star imports.\n\n**Problem 1: The source of names is hidden.** A reader who sees `cos(0)` halfway through a 300-line file can't tell whether `cos` came from `math`, from a third-party library, or from a local function. With `import math` and `math.cos(0)`, the source is in the call.\n\n**Problem 2: Shadowing without warning.** Two `import *` statements can clobber each other without any warning:\n\n\n```python\nfrom math import * # math.sqrt: returns float, raises on negative\nfrom cmath import * # cmath.sqrt: returns complex, handles negative\n\nprint(sqrt(-1))\n```\n\n\nBoth `math` and `cmath` define `sqrt`. The second star import replaced `math.sqrt` with `cmath.sqrt`. Code that wrote `sqrt(-1)` expecting the math version to raise (which it does for negative input) now gets the complex-number version instead. The bug is invisible because there's no error and no warning.\n\n**Problem 3: Tools struggle.** Linters, type checkers, and IDEs have a harder time analyzing files that use `import *`. They can't always tell which names are defined, which makes \"undefined name\" warnings unreliable and code completion noisier than it should be.\n\nFor these reasons, treat `from module import *` as a smell. It's tolerable in interactive REPL sessions and throwaway scripts. Any file that will be read again should use named imports.\n\nOne place star imports are common: at the top of a package's `__init__.py`, where the author has deliberately curated what to re-export. For application code, prefer explicit names.\n\nBeyond style, `import *` can introduce bugs as a codebase grows. A new module added later might export a name that shadows something the code depended on. Explicit imports make that impossible.\n\n---\n\n# Controlling `import *` with `__all__`\n\nA module author can influence what a star import pulls in even if star imports are discouraged. The hook is `__all__`: a list of strings defined at module level that controls which names `import *` exports.\n\nWithout `__all__`, `import *` pulls every name in the module that doesn't start with an underscore. With `__all__`, it pulls only the names listed there, regardless of underscores.\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# shop.py\nfrom pricing import *\n\nprint(apply_discount(100, 10))\nprint(TAX_RATE)\nprint(INTERNAL_CONSTANT)\n```\n\n\n`INTERNAL_CONSTANT` doesn't start with an underscore (so the default rule would normally export it), but it's not in `__all__`, so the star import skips it. `_internal_helper` would be excluded either way: it starts with an underscore.\n\n`__all__` is the closest Python comes to a \"this is the public API\" declaration. Even when no one uses `import *` against the module, defining `__all__` documents intent. Linters and type checkers read it to know which names are public. Documentation generators use it to decide what shows up in the rendered API reference.\n\nA rule of thumb: a module that will be imported by other code should define `__all__`. List the names that are part of the public API. Anything not in the list is \"internal\" by convention, and callers that use it have no guarantee across refactors.\n\n`__all__` is a regular list. Python doesn't enforce anything about its contents at import time; misspelling a name inside `__all__` doesn't raise an error until something tries `import *`. Some linters catch the typo, which is one more reason to run a linter.\n\n---\n\n# Relative Imports: `from . import x` and `from .. import y`\n\nEverything above used **absolute** imports, which spell out the full module name from the top of the package tree (`from shop.pricing import apply_discount`). Inside a package, there's a second option: **relative** imports, which reference modules by their position relative to the current file.\n\nA relative import starts with one or more dots. A single dot means \"the current package.\" Two dots mean \"the parent package.\" Three dots mean \"grandparent,\" and so on.\n\nConsider this package layout:\n\n\n```shell\nshop/\n __init__.py\n pricing.py\n cart/\n __init__.py\n items.py\n checkout.py\n```\n\n\nInside `shop/cart/checkout.py`, the current package is `shop.cart`. So:\n\n\n```python\n# shop/cart/checkout.py\nfrom . import items # imports shop.cart.items\nfrom .items import CartItem # imports CartItem from shop.cart.items\nfrom .. import pricing # imports shop.pricing\nfrom ..pricing import apply_discount # imports apply_discount from shop.pricing\n```\n\n\nThe single dot in `from .items import CartItem` resolves to `shop.cart.items` because that's \"items inside the current package, which is `shop.cart`.\" The two dots in `from ..pricing import apply_discount` walk up one level to `shop` and look at `pricing` there.\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 teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe dashed arrows show what each relative import resolves to. `.items` stays inside `cart/`. `..pricing` walks up to `shop/` and finds `pricing.py` there.\n\nThe appeal of relative imports is rename-resilience. Renaming the top-level `shop` package to `ecommerce` means every absolute import `from shop.something import x` has to change. The relative imports inside the package keep working, because they reference structure, not names.\n\nOne limitation: relative imports only work inside packages. Running a file directly as a script (`python checkout.py`) leaves Python without a \"current package,\" so the relative import fails:\n\n\n```shell\nImportError: attempted relative import with no known parent package\n```\n\n\nThe fix is either to use absolute imports or to run the file as a module from the project root: `python -m shop.cart.checkout`. The `-m` flag tells Python to treat this as a module being imported from the top of the package tree, which is the context relative imports need.\n\nPEP 8 recommends absolute imports as the default, with relative imports acceptable for sibling imports inside a package when they shorten the line meaningfully. Avoid going more than one level up (`...` or `....`) because the result becomes hard to read and usually signals a layout problem.\n\n\n| Style | Example | When to use |\n|---|---|---|\n| Absolute | `from shop.cart.items import CartItem` | Clearest for one-off imports, always unambiguous, works in scripts |\n| Relative | `from .items import CartItem` | Sibling imports inside a package, especially when the top-level name might change |\n\n\nPick one style per project and stick with it. Mixing the two heavily in one file is harder to read than either alone.\n\n---\n\n# Circular Imports\n\nTwo modules importing from each other is a common import problem in larger codebases. Module `A` imports from `B`, and `B` (during its own loading) imports from `A`. At the moment `B` runs, `A` is only partially loaded, so some of `A`'s names don't exist yet, and the import fails.\n\nA minimal reproduction:\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`:\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\nRead the traceback in order: `cart.py` started loading, hit `from pricing import apply_discount` on line 1, which triggered `pricing.py` to start loading, which hit `from cart import calculate_total` on its own line 1. At that moment, `cart` was registered in `sys.modules` but only partially executed. The `calculate_total` function hadn't been defined yet. The `from cart import calculate_total` line found the half-loaded module and couldn't find the name.\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 orange fill:#ffa94d,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe diagram shows the loop. `cart` is mid-load when `pricing` starts loading; `pricing` then tries to reach into `cart` for a name that hasn't been defined yet.\n\nThere are three ways out, in order of preference.\n\n**Fix 1: Restructure.** Circular imports usually point to a design issue. If `cart` and `pricing` depend on each other, there's a third concept hiding in there that should live in its own module. Pull the shared piece out:\n\n\n```python\n# discounts.py\ndef apply_discount(price, percent):\n return price * (1 - percent / 100)\n```\n\n\n\n```python\n# cart.py\nfrom discounts 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\nfrom discounts import apply_discount\n```\n\n\nNow `cart` depends on `discounts`, and `pricing` depends on both. Neither cart nor pricing depends on the other. The cycle is gone.\n\n**Fix 2: Use `import module` instead of `from module import name`.** A plain `import` works even when the target module is partially loaded, because the module object is already in `sys.modules` and no names on it are accessed at import time. Access happens later, after both modules have finished loading.\n\n\n```python\n# cart.py\nimport pricing\n\ndef calculate_total(items):\n return sum(pricing.apply_discount(item[\"price\"], 10) for item in items)\n```\n\n\n\n```python\n# pricing.py\nimport cart\n\ndef apply_discount(price, percent):\n return price * (1 - percent / 100)\n\ndef report():\n print(cart.calculate_total([{\"price\": 100}]))\n```\n\n\nAt import time, neither file tries to read attributes from the other. The lookups happen inside function bodies, which run after both modules are fully loaded. The cycle still exists in the dependency graph, but Python tolerates it now because it doesn't require partially loaded names.\n\n**Fix 3: Move the import inside the function.** When restructuring isn't quick and the module-form fix doesn't fit, the last resort is to move the import line inside the function that needs it.\n\n\n```python\n# cart.py\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\nBy the time `calculate_total` is called, both modules have finished initializing, so the import succeeds. The trade-off is a small per-call cost (a dict lookup in `sys.modules`) and a less obvious dependency graph. For occasional use, it's fine. For a hot path, prefer fix 1 or 2.\n\nLazy imports inside functions hide circular-import problems instead of solving them. They run a `sys.modules` lookup on every call, which is cheap but not free. They also obscure the file's real dependencies, which makes the code harder to reason about. Frequent use of this fix usually means the layout is the real problem.\n\n---\n\n# Best Practices\n\nA short list of habits that prevent most import-related pain.\n\n**Put imports at the top of the file.** After the module docstring and `from __future__` imports, before any module-level code. A reader scanning the top of a file should see every external dependency in one glance. The exceptions (lazy imports inside functions, conditional imports for platform-specific code) are rare enough to call out with a comment.\n\n**Group imports into three sections, in order:** standard library, third-party, local. Separate each group with a blank line. Within each group, sort alphabetically. Tools like `isort` and `ruff` do this 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\n**Prefer `import module` over `from module import name` when readability tips that way.** The qualified form (`module.name`) makes the source obvious at the call site. The `from` form makes the call site shorter. Pick the form that reads better in context. Most projects mix the two: `import` for things used once or twice (`import math`, then `math.sqrt` in one place), `from` for things used many times (`from typing import List, Optional, Dict`).\n\n**Avoid `from module import *` outside of `__init__.py`.** PEP 8 discourages it, linters complain about it, and it makes code harder to read and refactor. The one exception is package `__init__.py` files where the package author has deliberately curated re-exports.\n\n**Use `as` aliases sparingly.** Two situations call for them: community conventions (`import numpy as np`, `import pandas as pd`) and resolving conflicts. Don't alias to make names shorter; the cost is paid by future readers who have to figure out what `pd` is.\n\n**Define `__all__` in modules that will be imported by other code.** `__all__` documents intent and helps tools distinguish public from internal names.\n\n**Prefer absolute imports.** Use relative imports only for sibling imports inside the same package, and never go more than one level up. An import like `from ...subpackage.module import x` usually means the project layout is wrong.\n\n**Treat circular imports as a design signal, not a bug to patch.** Lazy imports and `import module` tricks can paper over a cycle, but the cycle itself usually means two modules are entangled in ways they shouldn't be. Refactoring is the real fix; the patches are stopgaps.","pageType":"python"}

from...import

Get Premium