{"title":"Modules Basics","description":"","content":"A module is the unit Python uses to organize code across files. Once a program grows past a few dozen lines, putting everything in one file stops being practical, and splitting work into modules is how Python keeps it tidy. This lesson covers what a module actually is, why you'd split code into modules, the metadata Python attaches to every module, and how to peek at a module's contents.\n\n---\n\n# What a Module Actually Is\n\nA module is any Python file. That's it. The file `pricing.py` is a module called `pricing`. The file `customer.py` is a module called `customer`. The file you're running right now is also a module. Python doesn't draw a hard line between \"the script I'm running\" and \"a library I imported\"; both are modules, and the rules that govern them are the same.\n\nThe point of a module is to bundle related code (functions, variables, classes) under one name so the rest of the program can use it without copying anything. When you have a function that calculates a cart total, you don't want to retype it in every file that needs it. You write it once in `pricing.py` and let any other file pull it in.\n\nStart with a tiny module. Create a file called `pricing.py` next to your main script:\n\n\n```python\n# pricing.py\n\nTAX_RATE = 0.08\n\ndef cart_total(prices):\n subtotal = sum(prices)\n tax = subtotal * TAX_RATE\n return subtotal + tax\n```\n\n\nThen, in another file in the same folder, called `shop.py`, use it:\n\n\n```python\n# shop.py\n\nimport pricing\n\ncart = [29.99, 14.99, 9.99]\ntotal = pricing.cart_total(cart)\nprint(f\"Cart total: ${total:.2f}\")\nprint(f\"Tax rate in use: {pricing.TAX_RATE * 100}%\")\n```\n\n\nThe `import pricing` line tells Python \"go find a module named `pricing` and load it\". After that, every name defined inside `pricing.py` becomes available as an attribute of `pricing`. The function `cart_total` becomes `pricing.cart_total`, and the constant `TAX_RATE` becomes `pricing.TAX_RATE`. The dot is the access operator, the same way it works for any other Python object.\n\nThis is the smallest useful picture of a module: one file defines names, another file imports those names through the file's name. For now, plain `import modulename` is enough to make every example below work.\n\n---\n\n# Why Split Code Into Modules\n\nA single-file program works until it doesn't. The first time you need to find a function you wrote three weeks ago and have to scroll through 800 lines to find it, the pain is obvious. Splitting code into modules solves three real problems at once: reuse, organization, and namespacing.\n\n### Reuse\n\nIf two scripts both need to calculate a cart total, they have two options: each copies the function, or both import it from a shared module. Copying means two places to fix when the tax rules change, and two places to drift out of sync. Importing means one place to fix, one place to update.\n\n\n```python\n# pricing.py\nTAX_RATE = 0.08\n\ndef cart_total(prices):\n return sum(prices) * (1 + TAX_RATE)\n```\n\n\n\n```python\n# checkout.py\nimport pricing\n\ncart = [19.99, 4.99, 39.99]\nprint(f\"Checkout total: ${pricing.cart_total(cart):.2f}\")\n```\n\n\n\n```python\n# email_receipts.py\nimport pricing\n\ncustomer_cart = [9.99, 9.99]\nprint(f\"Receipt total: ${pricing.cart_total(customer_cart):.2f}\")\n```\n\n\nBoth `checkout.py` and `email_receipts.py` lean on the same `cart_total`. When the tax rate changes, you edit `pricing.py` and both files immediately see the new behavior. No copy-paste bugs, no forgotten files.\n\n### Organization\n\nA 50-line file is easy to scan. A 500-line file is a chore. A 5,000-line file is where bugs live. Splitting by purpose makes each file small enough to read in one sitting:\n\n\n| File | What lives there |\n| --- | --- |\n| `pricing.py` | Tax, discounts, totals |\n| `customer.py` | Customer records, addresses |\n| `cart.py` | Cart structure, add and remove operations |\n| `orders.py` | Order placement, status updates |\n| `shop.py` | The entry point that ties it together |\n\n\nEach file is small. Each file has a clear job. When you need to fix a discount bug, you open `pricing.py` and don't have to wade through 4,000 lines of unrelated order-status code on the way.\n\n### Namespacing\n\nModules give names a place to live. Without modules, every function and variable in your program shares a single global pool, and collisions become inevitable. With modules, two files can both have a function called `total` without stepping on each other, because one is `pricing.total` and the other is `shipping.total`.\n\n\n```python\n# pricing.py\ndef total(prices):\n return sum(prices) * 1.08\n\n# shipping.py\ndef total(weights):\n return sum(weights) * 0.50\n\n# shop.py\nimport pricing\nimport shipping\n\nprint(pricing.total([10.00, 5.00]))\nprint(shipping.total([2.5, 1.0]))\n```\n\n\nBoth files define a function named `total`. They don't clash because each lives behind the module's name. The module acts like a folder for names, and the dot acts like the slash in a file path.\n\n\n```mermaid\nflowchart LR\n Shop[\"shop.py
imports modules\"]:::cyan\n Pricing[\"pricing.py
cart_total, TAX_RATE\"]:::orange\n Customer[\"customer.py
load_customer\"]:::orange\n Shipping[\"shipping.py
total, ZONES\"]:::orange\n\n Shop --> Pricing\n Shop --> Customer\n Shop --> Shipping\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n```\n\n\nThe diagram shows the typical shape: one entry-point file (cyan) leans on several smaller files (orange), each holding one slice of the program. Every arrow is an `import`. The entry-point file doesn't define much itself; it stitches together work that lives elsewhere.\n\n\n> **INFO**\n>\n> **Cost:** Importing a module the first time runs its top-level code. If a module has heavy work at the top level (loading a big file, opening a connection), the first `import` pays that cost. Later imports of the same module are cheap because Python caches the result.\n\n\n---\n\n# Importing a Module (The Basics)\n\nTo use names from another module, you import it. The most direct form is the bare `import` statement:\n\n\n```python\nimport pricing\n```\n\n\nThis does three things, in order:\n\n1. Python finds a file called `pricing.py`.\n2. Python runs the file from top to bottom, just like running it as a script, except the names defined inside stick around in a module object.\n3. Python binds the name `pricing` in the current file to that module object.\n\nAfter the import, you reach names inside the module with the dot:\n\n\n```python\nimport pricing\n\nprint(pricing.TAX_RATE)\nprint(pricing.cart_total([29.99, 14.99]))\n```\n\n\nThe dot tells Python \"look inside `pricing` for an attribute called `TAX_RATE`\". A module is just an object, and the names defined inside it are its attributes. That's the same mechanism Python uses for any other dotted name (`some_list.append`, `some_string.upper`), so the syntax feels consistent once you've seen it for modules.\n\nThere are other shapes of import (`from pricing import cart_total`, `import pricing as p`, and so on). They're useful, but they're variations on the same idea and they get their own lesson. For everything in this chapter, plain `import modulename` does the job.\n\nOne quick rule: an `import` statement at the top of a file makes the module available for the rest of that file. By convention, imports go at the very top, above any other code. Putting them anywhere else is legal Python, but it makes the file harder to read because someone scanning the top can't see what the file depends on.\n\n---\n\n# Module vs Script: The Same File, Two Roles\n\nA `.py` file can do double duty. The same file can be run directly as a script (`python pricing.py`) or imported by another file (`import pricing`). Python doesn't force you to pick one or the other; the file is just a module, and you can use it either way.\n\nWhen you run a file directly, Python loads it and executes every top-level statement. When you import the same file, Python also loads it and executes every top-level statement, the difference is what happens afterward. A script runs and exits. An imported module sticks around as an object that the importing file can poke at.\n\n\n```python\n# pricing.py\n\nTAX_RATE = 0.08\nprint(\"pricing.py is being loaded\")\n\ndef cart_total(prices):\n return sum(prices) * (1 + TAX_RATE)\n```\n\n\nIf you run `python pricing.py` directly:\n\nIf you run `python shop.py` where `shop.py` contains `import pricing`:\n\nThe `print` runs in both cases, because both cases execute the top-level code. The difference is harder to see: in the first case, the module ends and Python exits. In the second case, the module ends and Python keeps going, with `pricing` now sitting in memory ready for `shop.py` to use.\n\nThis dual nature is why most non-trivial modules guard their \"if I'm being run as a script\" code with the line `if __name__ == \"__main__\":`. That idiom lets a file both define reusable helpers and offer a runnable entry point, without one stepping on the other. For this lesson, the takeaway is just that a `.py` file is a module either way, and merely importing it runs its top-level code.\n\n\n```mermaid\nflowchart LR\n File[\"pricing.py
same file\"]:::cyan\n Run[\"python pricing.py
run as script\"]:::orange\n Import[\"import pricing
imported by another file\"]:::green\n BothLoad[\"Python executes
top-level statements\"]:::teal\n ScriptEnd[\"script exits
names discarded\"]:::orange\n ModObj[\"module object stays
names accessible via
pricing.NAME\"]:::green\n\n File --> Run --> BothLoad\n File --> Import --> BothLoad\n BothLoad --> ScriptEnd\n BothLoad --> ModObj\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 two paths the same file can take. Both paths run the top-level code (teal). The script path (orange) ends after that. The import path (green) keeps the module object around so the importer can use its names.\n\n---\n\n# Module Attributes: The Metadata Python Attaches\n\nEvery module Python loads gets a small bundle of metadata attached to it. These attributes are named with double underscores on each side, which Python calls **dunder** names (short for \"double underscore\"). They describe the module to anyone who asks: what it's called, where it lives, what it's about.\n\nThe four worth knowing on day one are `__name__`, `__doc__`, `__file__`, and `__loader__`.\n\n### `__name__`\n\n`__name__` is the module's name as Python sees it. For an imported module, it's the import name. For the file you ran directly with `python somefile.py`, it's the special string `\"__main__\"`.\n\n\n```python\n# pricing.py\nprint(f\"This file's __name__ is: {__name__}\")\n\ndef cart_total(prices):\n return sum(prices) * 1.08\n```\n\n\nIf you run `python pricing.py` directly:\n\nIf you import it from another file (`import pricing`):\n\nThe same line prints two different values depending on how the file got loaded. That's the hook the `if __name__ == \"__main__\":` idiom hangs on. For now, just know that `__name__` is the attribute that lets a file tell whether it's the script being run or a module being imported.\n\nYou can also read `__name__` from an already-imported module by going through the module object:\n\n\n```python\n# shop.py\nimport pricing\n\nprint(pricing.__name__)\n```\n\n\n(The first line comes from the `print` at the top of `pricing.py`, which runs when the import loads the file. The second line is `shop.py` asking for `pricing.__name__` directly.)\n\n### `__doc__`\n\n`__doc__` holds the module's docstring: a string literal placed at the very top of the file. If the file doesn't have one, `__doc__` is `None`.\n\n\n```python\n# pricing.py\n\"\"\"Pricing helpers for the AlgoMaster store.\n\nProvides cart totals, tax calculation, and the standard tax rate constant.\n\"\"\"\n\nTAX_RATE = 0.08\n\ndef cart_total(prices):\n return sum(prices) * (1 + TAX_RATE)\n```\n\n\n\n```python\n# shop.py\nimport pricing\n\nprint(pricing.__doc__)\n```\n\n\nThe docstring is just a regular triple-quoted string at the top of the file, but Python treats it specially and binds it to `__doc__`. That's also what the `help()` builtin reads when you ask it for help on the module. Documenting your own modules with a one-line summary at the top costs almost nothing and pays off the next time someone (including future you) runs `help(pricing)`.\n\n### `__file__`\n\n`__file__` is the absolute path to the source file that backed the module. It's a string and it usually ends in `.py`.\n\n\n```python\n# shop.py\nimport pricing\n\nprint(pricing.__file__)\n```\n\n\n`__file__` is useful for modules that need to find files next to themselves: a config file in the same directory, a data file shipped alongside the code. You can extract the folder with the `pathlib` or `os.path` modules and build paths relative to it. The point is that `__file__` exists and tells you where the module came from.\n\nA handful of special modules (mostly built-in ones written in C, like `sys`) don't have a `__file__` attribute because they're not loaded from a `.py` file at all. Reaching for `__file__` on those raises `AttributeError`. For ordinary Python modules you write, it's always there.\n\n### `__loader__`\n\n`__loader__` is the object Python used to load the module. Most of the time it's an internal Python detail you don't touch, but it's worth a glance so the name isn't a mystery when you see it.\n\n\n```python\n# shop.py\nimport pricing\n\nprint(pricing.__loader__)\n```\n\n\nFor a regular `.py` file, the loader is a `SourceFileLoader`. For built-in modules, it's a different class. For modules inside a `.zip` file or a custom import location, it's something else again. The `importlib` machinery lives behind this attribute. You rarely interact with it directly, but library authors who need to load modules from unusual places do.\n\n### All Together\n\nHere's a small inspection script that prints all four for a module of your own:\n\n\n```python\n# inspect_module.py\nimport pricing\n\nprint(f\"name: {pricing.__name__}\")\nprint(f\"doc: {pricing.__doc__!r}\")\nprint(f\"file: {pricing.__file__}\")\nprint(f\"loader: {pricing.__loader__}\")\n```\n\n\nThe `!r` in the f-string shows `__doc__` with its quotes and newlines intact, which makes the structure of the string easier to see.\n\nModules carry other dunder attributes too (`__package__`, `__spec__`, `__builtins__`, `__cached__`), but those four are the ones to know first. The rest become relevant when you start building packages or doing import-system tricks, and we'll meet them then.\n\n---\n\n# Inspecting a Module With `dir()`\n\nThe builtin `dir()` returns a sorted list of the names defined on an object. When you point it at a module, you get a list of every name the module exposes: the functions, classes, variables, and the dunder attributes.\n\n\n```python\n# pricing.py\n\"\"\"Pricing 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```\n\n\n\n```python\n# shop.py\nimport pricing\n\nprint(dir(pricing))\n```\n\n\nThe dunder names at the start are the metadata Python attaches to every module. The names without underscores (`TAX_RATE`, `apply_discount`, `cart_total`) are the ones the module's author defined. Those are the names the rest of your program would use.\n\n`dir()` is the fastest way to answer \"what's in this module?\" without opening the file. It's especially handy in the REPL when you've imported something new and want to see what's available before reading the docs:\n\n\n```python\n>>> import pricing\n>>> dir(pricing)\n['TAX_RATE', '__builtins__', ..., 'apply_discount', 'cart_total']\n>>> pricing.cart_total\n\n>>> pricing.cart_total([10.00, 5.00])\n16.200000000000003\n```\n\n\nThe REPL flow is: import the module, run `dir()` on it to see the names, pick a name to investigate, and either inspect it or call it. This loop is one of the small everyday joys of Python; you can poke at a new library without reading a single line of its docs and get a decent feel for what's there.\n\nTo strip the dunder noise, filter the list with a comprehension:\n\n\n```python\nimport pricing\n\npublic_names = [name for name in dir(pricing) if not name.startswith(\"_\")]\nprint(public_names)\n```\n\n\nThat's a cleaner view of what the module actually offers, minus Python's bookkeeping. Names that start with an underscore are conventionally \"internal\" anyway, so dropping them gives you the public surface of the module.\n\n`dir()` works on more than modules. Pass it any object and it returns the names defined on that object: a list's methods, a string's methods, a class's attributes. The same one builtin answers \"what can I do with this thing?\" for almost anything.\n\n\n> **INFO**\n>\n> **Cost:** `dir()` allocates and sorts a new list every call. It's fine for interactive exploration and for tools that need to introspect a module, but don't call it in a hot loop, allocating a sorted list of every name in a module just to check membership is wasteful when `hasattr(module, name)` does the same job in O(1).\n\n\n---\n\n# Modules Are Cached: Imported Once, Reused Forever\n\nPython imports a module exactly once per process, no matter how many times you write `import` for it. The first import runs the file from top to bottom and stores the resulting module object. Every later `import` of the same name just hands back the same object.\n\nThat behavior matters because it means a module's top-level code only runs once. Heavy setup, file reads, or configuration loading at the top of a module pays its cost on the first import and is free afterwards.\n\n\n```python\n# pricing.py\nprint(\"pricing.py top-level code is running\")\n\nTAX_RATE = 0.08\n\ndef cart_total(prices):\n return sum(prices) * (1 + TAX_RATE)\n```\n\n\n\n```python\n# shop.py\nimport pricing\nimport pricing\nimport pricing\n\nprint(\"done\")\n```\n\n\nThree `import pricing` lines, one print. The first import loaded the file and ran the top-level code. The second and third imports saw that `pricing` was already loaded and reused the cached object. You can prove they all point to the same thing:\n\n\n```python\nimport pricing\nfirst = pricing\n\nimport pricing\nsecond = pricing\n\nprint(first is second)\n```\n\n\nThe `is` operator checks object identity. Both names refer to the same module object in memory. There's no second copy.\n\nThis caching has a real consequence for how modules are designed. A module's top-level code is effectively a one-time setup block: register configuration, build lookup tables, create constants. Anything you put there happens once for the life of the program. If a module's top-level code accidentally has a side effect (writing a file, sending a request, mutating shared state), that side effect happens once on first import and never again, which is usually a surprise.\n\n\n```mermaid\nflowchart LR\n First[\"first import pricing\"]:::cyan\n Find[\"find pricing.py\"]:::orange\n Run[\"run top-level code
build module object\"]:::green\n Cache[\"store in cache\"]:::teal\n Done[\"return module object\"]:::cyan\n Later[\"later import pricing\"]:::cyan\n HitCache{\"in cache?\"}:::orange\n Reuse[\"return cached object
no re-run\"]:::green\n\n First --> Find --> Run --> Cache --> Done\n Later --> HitCache\n HitCache -->|yes| 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 two paths: the first import does real work (orange and green), saves the result in the cache (teal), and returns it. Every later import skips straight to the cache. The cache itself lives in `sys.modules`, which is a dictionary that maps module names to module objects.\n\nFor now, three things to remember about the cache:\n\n1. The first `import` of a module runs its top-level code; later imports do not.\n2. All imports of the same module name in the same process get the same module object.\n3. Mutating a module's attributes through one importer is visible to every other importer, because they're all pointing at the same object.\n\nThe third point is subtle and powerful. If `pricing.TAX_RATE` is `0.08` and one part of your program changes it to `0.10`, every other part that uses `pricing.TAX_RATE` sees `0.10` from then on. This is how Python's \"modules as singletons\" model lets configuration spread across files without any special framework. It's also how it sometimes bites you, because surprise shared state is still surprise shared state. Use it deliberately, not by accident.\n\n\n> **INFO**\n>\n> **Cost:** First-import cost is one-time but real. If a module reads a 100 MB file at the top level, every program that imports it pays that 100 MB upfront. Push heavy work into a function the importer calls when it wants it, instead of running it at import time.\n\n\n---\n\n# A Slightly Bigger Example: A Two-Module Store\n\nPutting the ideas together, here's a small two-module e-commerce setup. One module owns pricing rules; another module owns customer lookups; a third file is the entry point that uses both.\n\n\n```python\n# pricing.py\n\"\"\"Pricing helpers for the AlgoMaster store.\"\"\"\n\nTAX_RATE = 0.08\n\ndef cart_total(prices):\n \"\"\"Return the total of a cart, including tax.\"\"\"\n return sum(prices) * (1 + TAX_RATE)\n\ndef apply_discount(price, percent):\n \"\"\"Return a price after a percentage discount.\"\"\"\n return price * (1 - percent / 100)\n```\n\n\n\n```python\n# customer.py\n\"\"\"Customer records for the AlgoMaster store.\"\"\"\n\nCUSTOMERS = {\n 1: {\"name\": \"Alice\", \"email\": \"alice@example.com\"},\n 2: {\"name\": \"Bob\", \"email\": \"bob@example.com\"},\n}\n\ndef get_customer(customer_id):\n \"\"\"Return a customer record by ID, or None if not found.\"\"\"\n return CUSTOMERS.get(customer_id)\n```\n\n\n\n```python\n# shop.py\nimport pricing\nimport customer\n\ncart_prices = [29.99, 14.99, 9.99]\ntotal = pricing.cart_total(cart_prices)\nsale_price = pricing.apply_discount(49.99, 10)\n\nbuyer = customer.get_customer(1)\n\nprint(f\"Customer: {buyer['name']} <{buyer['email']}>\")\nprint(f\"Cart total (with tax): ${total:.2f}\")\nprint(f\"Sale price after 10% off: ${sale_price:.2f}\")\n```\n\n\nEach module has one job. `pricing.py` knows about money. `customer.py` knows about customers. `shop.py` doesn't define any business logic; it just stitches the pieces together. If the tax rate changes, only `pricing.py` changes. If customer storage moves from a hard-coded dictionary to a database lookup, only `customer.py` changes. The entry point stays put.\n\nIf you want a quick look at what each module exposes, you don't need to open the files:\n\n\n```python\nimport pricing\nimport customer\n\nprint(\"pricing exposes:\", [n for n in dir(pricing) if not n.startswith(\"_\")])\nprint(\"customer exposes:\", [n for n in dir(customer) if not n.startswith(\"_\")])\nprint(\"pricing docstring:\", pricing.__doc__)\n```\n\n\nThat's the loop again: import, list, look. Three lines of code give you a map of what each module is for. With a docstring at the top of each file, even the why is there.","pageType":"python"}

Modules Basics

Get Premium