{"title":"PEP 8 Style Guide","description":"","content":"PEP 8 is the style guide for Python code. It's not a language rule, it's a social contract: a shared set of conventions that makes Python code from different authors look and feel the same. Following it is what turns a working script into code that other people can read, review, and maintain. This lesson covers what PEP 8 actually says, where its rules come from, and the handful of judgment calls every Python developer eventually has to make.\n\n---\n\n# Why PEP 8 Exists\n\nIn 2001, Guido van Rossum and Barry Warsaw wrote PEP 8 to document the conventions used in the standard library itself. The goal was simple: if every Python module looks roughly the same, a reader switching between files spends their attention on the logic, not on remembering whose brace style they're looking at. Python doesn't use braces, but the same idea applies to indentation, naming, spacing, and import order.\n\nThe guide opens with a line that gets quoted often: \"A Foolish Consistency is the Hobgoblin of Little Minds.\" PEP 8 is a guide, not a law. When the rule and the readable thing disagree, readability wins. That said, the rule wins 95% of the time, and the exceptions are rarer than beginners expect.\n\nThree things drive almost every PEP 8 decision:\n\n1. **Readability over cleverness.** Code is read more often than it's written.\n2. **Consistency within a file beats consistency with the world.** If a file already uses a particular style, match it.\n3. **Don't break the standard library's conventions without a reason.** Most Python developers learned them by osmosis.\n\nA quick mental model for where PEP 8 fits in the broader ecosystem:\n\n\n```mermaid\nflowchart LR\n PEP8[PEP 8
Style Guide]:::cyan\n PEP257[PEP 257
Docstrings]:::orange\n PEP20[PEP 20
The Zen]:::teal\n LINT[Linters
ruff / flake8]:::green\n FMT[Formatters
black / ruff format]:::green\n CODE[Your Python code]:::orange\n\n PEP8 --> LINT\n PEP8 --> FMT\n PEP257 --> LINT\n PEP20 --> CODE\n LINT --> CODE\n FMT --> CODE\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```\n\n\nPEP 8 sits at the top. PEP 257 is its companion guide for docstrings, and PEP 20 (The Zen of Python) is the philosophical backdrop. The tools at the bottom enforce or auto-apply most of the rules so you rarely have to think about them.\n\n---\n\n# Naming Conventions\n\nNames carry meaning. PEP 8 fixes the casing for each kind of name so that readers can tell what they're looking at from the shape alone.\n\n\n| Kind of name | Convention | Example |\n| --- | --- | --- |\n| Variable, function, method | `snake_case` | `cart_total`, `add_to_cart` |\n| Class | `PascalCase` (also called `CapWords`) | `ShoppingCart`, `OrderStatus` |\n| Constant | `UPPER_SNAKE_CASE` | `MAX_ITEMS_PER_CART`, `DEFAULT_TAX_RATE` |\n| Module, package | short `lowercase` | `cart`, `orders`, `email_utils` |\n| Type variable | short `PascalCase` | `T`, `KT`, `ProductT` |\n| Internal (private) name | leading underscore `_name` | `_normalize_email`, `_cache` |\n| Name-mangled (class-private) | double leading underscore `__name` | `__internal_id` (used rarely) |\n| Dunder (special) | double leading + trailing `__name__` | `__init__`, `__str__` |\n\n\nA small example that puts most of them together:\n\n\n```python\nMAX_ITEMS_PER_CART = 50\nDEFAULT_TAX_RATE = 0.08\n\nclass ShoppingCart:\n def __init__(self, customer_email: str) -> None:\n self.customer_email = customer_email\n self._items: list[dict] = []\n\n def add_item(self, product_name: str, price: float, quantity: int = 1) -> None:\n self._items.append({\"name\": product_name, \"price\": price, \"quantity\": quantity})\n\n def total(self) -> float:\n subtotal = sum(item[\"price\"] * item[\"quantity\"] for item in self._items)\n return subtotal * (1 + DEFAULT_TAX_RATE)\n\ncart = ShoppingCart(\"priya@example.com\")\ncart.add_item(\"headphones\", price=59.99)\nprint(f\"Total: ${cart.total():.2f}\")\n```\n\n\nThe naming alone tells you a lot before you read any logic. `ShoppingCart` is a class. `MAX_ITEMS_PER_CART` is a constant defined once at module load. `add_item` is a method you're meant to call. `_items` has a leading underscore, signaling \"this is an implementation detail, don't poke at it from outside the class.\"\n\n### The Underscore Rules\n\nThe underscore prefixes have specific meanings that beginners often blur together.\n\n- A single leading underscore (`_name`) is a convention: \"treat this as internal.\" Python doesn't enforce anything. You can still access `cart._items` from outside, you just signal that you're crossing a line.\n- A double leading underscore (`__name`) triggers name mangling inside a class body. `self.__internal_id` inside `class ShoppingCart` becomes `self._ShoppingCart__internal_id` after compilation. This was designed to avoid accidental clashes in subclasses, not to provide privacy. Most codebases reach for it rarely; a single underscore is enough for almost every case.\n- Double leading and trailing underscores (`__name__`) are reserved for Python itself. Don't invent your own dunder names; you'll collide with future language features.\n- A trailing single underscore (`class_`, `type_`) is the standard workaround when you want a name that's also a Python keyword. `class` is reserved, so `class_` is the conventional escape hatch.\n\n### Names to Avoid\n\nPEP 8 explicitly calls out a few characters that look like other characters in some fonts:\n\n- Single-character names `l` (lowercase L), `O` (uppercase o), and `I` (uppercase i) are easy to mistake for `1` and `0`. Don't use them as standalone variable names.\n- Avoid one-letter names in general except for short loop variables (`for i in range(10):`) and well-known math conventions.\n- Don't use Python builtins as names. Writing `list = [1, 2, 3]` shadows the built-in `list` type for the rest of the scope. Same for `type`, `id`, `dict`, `str`, `filter`, `map`, and so on. If you genuinely need a name like `type`, add a trailing underscore: `type_`.\n\n---\n\n# Indentation and Line Length\n\nPython uses indentation as syntax, so PEP 8's rules here are tighter than in languages where indentation is cosmetic.\n\n### Indentation\n\n- **4 spaces per indentation level.** Not tabs. Not 2 spaces.\n- Don't mix tabs and spaces. Python 3 rejects files that mix them ambiguously.\n- Continuation lines (when a single statement spans multiple lines) should align to the opening delimiter or use a hanging indent.\n\nAligned to the opening delimiter:\n\n\n```python\norder = create_order(customer_email=\"aanya@example.com\",\n items=cart.items,\n shipping_address=\"221B Baker Street\")\n```\n\n\nHanging indent (the more common modern style, especially with formatters):\n\n\n```python\norder = create_order(\n customer_email=\"aanya@example.com\",\n items=cart.items,\n shipping_address=\"221B Baker Street\",\n)\n```\n\n\nThe hanging-indent version is what `black` and `ruff format` produce, and it's what most modern Python code looks like. The trailing comma after the last argument is intentional: it makes diffs cleaner when you add another argument later, because the existing last line doesn't change.\n\n### Line Length\n\nThis is the most-debated rule in PEP 8. The original limit was **79 characters** for code and **72 for docstrings and comments**. The reasoning was practical: it fits in an 80-column terminal, two files fit side by side on most screens, and email clients wrap long lines.\n\nModern practice has drifted. The defaults you'll see in the wild:\n\n\n| Limit | Origin | Where you'll see it |\n| --- | --- | --- |\n| 79 | Original PEP 8 | Standard library, conservative codebases |\n| 88 | `black`'s default | Most modern open-source Python projects |\n| 100 | Google's Python style guide, internal use | Many companies, some popular libraries |\n| 120 | Some Java-influenced teams | Rare in Python |\n\n\nPEP 8 itself was updated to acknowledge that \"some teams strongly prefer a longer line length\" and explicitly permits up to 99 characters when the team agrees. Whatever you pick, pick one number and put it in `pyproject.toml` so the formatter enforces it.\n\n\n```shell\n[tool.ruff]\nline-length = 88\n```\n\n\nThe 88-character default that `black` introduced isn't arbitrary. The author's argument was that 10% more horizontal room lets nearly every reasonable function signature fit on one line, which kept code denser without sacrificing readability on a standard laptop screen.\n\n### Breaking Long Lines\n\nWhen a line genuinely has to wrap, prefer breaking inside parentheses, brackets, or braces over using a backslash continuation:\n\n\n```python\ntotal = (\n cart.subtotal()\n + cart.tax()\n + cart.shipping()\n - cart.discount()\n)\n```\n\n\nPEP 8 also recommends breaking **before** the operator, not after. The reasoning: when you read the wrapped lines, the operator at the start of each line tells you immediately what's happening.\n\n\n> **INFO**\n>\n> **Cost:** A backslash continuation (`\\` at end of line) is fragile. A single trailing space after the backslash silently breaks the continuation, and most editors don't show trailing whitespace by default. Use parentheses instead.\n\n\n---\n\n# Imports\n\nImports are the first non-trivial thing a reader sees in a file, so PEP 8 spends a fair amount of time on them.\n\n### Order and Grouping\n\nImports are grouped into three blocks, separated by a single blank line:\n\n1. **Standard library imports** (`os`, `sys`, `json`, `datetime`)\n2. **Third-party imports** (`requests`, `pydantic`, `pytest`)\n3. **Local application imports** (your own package's modules)\n\nInside each block, imports are sorted alphabetically. Putting it together:\n\n\n```python\nimport json\nimport os\nfrom datetime import datetime\n\nimport httpx\nfrom pydantic import BaseModel\n\nfrom algomart.carts import Cart\nfrom algomart.orders import Order, OrderStatus\n```\n\n\nThe visual separation makes the file's external surface obvious at a glance: you can see at the top exactly which third-party libraries this module pulls in.\n\n### One Import Per Line\n\nEach `import` statement should import one top-level name, with one exception.\n\nCorrect:\n\n\n```python\nimport os\nimport sys\n```\n\n\nWrong:\n\n\n```python\nimport os, sys\n```\n\n\nThe exception is `from module import a, b, c`, which is fine because it's still importing from a single module. If the list gets long, wrap it:\n\n\n```python\nfrom algomart.carts import (\n Cart,\n CartItem,\n CartValidationError,\n compute_discount,\n)\n```\n\n\n### Absolute vs Relative Imports\n\nPEP 8 recommends **absolute imports** in nearly all cases. They make the source of every name unambiguous and survive refactors well.\n\nAbsolute:\n\n\n```python\nfrom algomart.carts import Cart\nfrom algomart.orders.status import OrderStatus\n```\n\n\nRelative:\n\n\n```python\nfrom .carts import Cart\nfrom ..orders.status import OrderStatus\n```\n\n\nThe dot syntax in relative imports means \"the current package.\" A single dot is the current package, two dots is the parent, and so on. Relative imports work only inside a package and can be useful when a package is renamed (the imports keep working without changes). But they make a line harder to read in isolation, and they break when someone copies a file out to test it. The general advice: use absolute imports by default, and reach for relative imports only inside a tight package where the alternative is annoyingly long.\n\n\n```mermaid\nflowchart TD\n FILE[Python source file]:::cyan\n STD[Standard library
os, sys, json, datetime]:::orange\n BLANK1[blank line]:::teal\n TP[Third-party
httpx, pydantic, pytest]:::orange\n BLANK2[blank line]:::teal\n LOCAL[Local imports
your package]:::green\n CODE[Module code]:::green\n\n FILE --> STD\n STD --> BLANK1\n BLANK1 --> TP\n TP --> BLANK2\n BLANK2 --> LOCAL\n LOCAL --> CODE\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```\n\n\nThe diagram captures the layout most Python files share: three sorted blocks of imports separated by blank lines, with module code following after a final blank line. Tools like `isort` and `ruff` enforce this automatically.\n\n### Things to Avoid in Imports\n\nA few patterns PEP 8 calls out as bad form:\n\n- **Wildcard imports** (`from module import *`) pull every public name into your namespace and make it impossible to tell where a name came from. Avoid them except in carefully controlled cases (some `__init__.py` files use them with an `__all__` list).\n- **Imports inside functions** are sometimes necessary (to avoid circular imports or to defer expensive imports), but they should be the exception, not the rule. Top-of-file imports make the module's dependencies obvious.\n- **Conditional imports based on Python version or platform** are fine when needed, but keep them at the top of the file with a clear comment:\n\n\n```python\nimport sys\n\nif sys.version_info >= (3, 11):\n from datetime import UTC\nelse:\n from datetime import timezone\n UTC = timezone.utc\n```\n\n\n---\n\n# Whitespace\n\nPEP 8's whitespace rules are mechanical but they're what makes Python files feel \"right\" to a reader. Tools like `black` and `ruff format` handle every rule below for you, but you should still recognize them in code review.\n\n### Around Operators\n\nOne space on each side of a binary operator, none inside unary operators:\n\n\n```python\ntotal = price * quantity + shipping\ndiscount = -0.10\nis_valid = age >= 18 and balance > 0\n```\n\n\nWhen operators have different priorities, you may add spacing around the lower-priority operators to make the grouping visual:\n\n\n```python\nhypotenuse = x*x + y*y # multiplication tight, addition spaced\nfinal = (a + b) * (c - d) # uniform spacing also fine\n```\n\n\nThe exception that surprises beginners: **no spaces around `=` in keyword arguments or default values.**\n\n\n```python\ndef add_item(name: str, price: float, quantity: int = 1) -> None:\n ...\n\ncart.add_item(name=\"headphones\", price=59.99, quantity=2)\n```\n\n\nWhy? Because `quantity: int = 1` is a default value, not an assignment, and `quantity=2` in a function call is a keyword argument, not an assignment. PEP 8 wants you to spot that difference visually. Add spaces around `=` only when there's an annotation that doesn't have a default:\n\n\n```python\ndef add_item(name: str, price: float = 0.0) -> None: # annotation + default: spaces\n ...\n```\n\n\n### After Commas, Colons, Semicolons\n\nOne space after, no space before:\n\n\n```python\nitems = [\"headphones\", \"cable\", \"case\"]\nprices = {\"headphones\": 59.99, \"cable\": 9.99, \"case\": 19.99}\n\nfor index, item in enumerate(items):\n print(index, item)\n```\n\n\nSlice colons are special: PEP 8 treats `:` as a binary operator in slices, so you typically write `a[1:5]` with no spaces. When slice expressions get more complex, equal spacing on both sides is fine: `a[1 : 5 : 2]`. Either is acceptable, but pick one per file.\n\n### Blank Lines\n\nBlank lines separate things at the visual level the same way indentation separates them at the syntactic level:\n\n- **Two blank lines** between top-level function and class definitions.\n- **One blank line** between methods inside a class.\n- **One blank line** to logically separate sections inside a function, used sparingly.\n\n\n```python\nimport json\n\nMAX_ITEMS = 50\n\nclass ShoppingCart:\n def __init__(self) -> None:\n self.items: list[dict] = []\n\n def add(self, name: str, price: float) -> None:\n self.items.append({\"name\": name, \"price\": price})\n\n def total(self) -> float:\n return sum(item[\"price\"] for item in self.items)\n\ndef serialize_cart(cart: ShoppingCart) -> str:\n return json.dumps(cart.items)\n\ndef deserialize_cart(payload: str) -> list[dict]:\n return json.loads(payload)\n```\n\n\nThe two blank lines around `class ShoppingCart`, `def serialize_cart`, and `def deserialize_cart` give the file a clear top-level rhythm. Inside the class, single blank lines between methods keep them visually distinct without making the class sprawl.\n\n### Inside Brackets\n\nNo space immediately inside parentheses, brackets, or braces:\n\n\n```python\nitems = [\"headphones\", \"cable\"] # correct\nitems = [ \"headphones\", \"cable\" ] # wrong: spaces inside brackets\n\ncart.add(name=\"headphones\", price=59.99) # correct\ncart.add( name=\"headphones\", price=59.99 ) # wrong: spaces inside parens\n```\n\n\nThis rule has zero exceptions in normal code. If you see leading or trailing whitespace inside a bracket, it's almost always a typo.\n\n---\n\n# String Quotes, Comments, and Docstrings\n\nPEP 8 has surprisingly little to say about string quotes. Single quotes and double quotes are treated as equivalent; pick one and stay with it inside a file. The pragmatic argument for double quotes: they match what `black` produces by default and what most JSON and JavaScript code uses, which reduces context-switching cost. Triple-double-quotes (`\"\"\"...\"\"\"`) are the convention for docstrings, set by PEP 257.\n\n\n```python\ngreeting = \"Welcome to the store\"\nproduct = 'headphones' # fine too, just be consistent within the file\n```\n\n\nThe one case where the choice matters: when the string itself contains a quote, pick the other one to avoid escaping.\n\n\n```python\nquote = \"It's a great deal.\" # double quotes avoid escaping\nquote = 'She said \"hi\".' # single quotes avoid escaping\n```\n\n\n### Comments\n\nPEP 8 has more to say about how comments are written than where they go.\n\n- **Block comments** apply to the code that follows. Each line starts with `# ` (hash, then a single space), and the block sits at the same indentation as the code.\n- **Inline comments** sit on the same line as a statement. They're separated by at least two spaces from the code, then `# `, then the comment. Use them sparingly; if you need an inline comment, ask first if a clearer variable name would replace it.\n- **Comments should be complete sentences.** Capitalize the first word (unless it's a code identifier). Don't end with extraneous punctuation but do use proper sentence structure.\n- **Update comments when code changes.** A wrong comment is worse than no comment.\n\n\n```python\n# Apply the standard tax rate to the cart subtotal.\n# We round at the end to avoid intermediate floating-point drift.\ndef total_with_tax(subtotal: float, tax_rate: float = 0.08) -> float:\n total = subtotal * (1 + tax_rate)\n return round(total, 2) # round to cents for display\n\ndiscount = 0.10 # 10% off for first-time customers\n```\n\n\n### Docstrings (PEP 257 Briefly)\n\nPEP 257 is the companion guide for docstring conventions. The highlights you need here:\n\n- Every public module, function, class, and method gets a docstring.\n- Docstrings use triple double-quotes: `\"\"\"...\"\"\"`.\n- A one-line docstring fits on a single line: `\"\"\"Return the cart subtotal.\"\"\"`.\n- A multi-line docstring has a one-line summary on the first line, a blank line, then the rest.\n\n\n```python\ndef apply_discount(price: float, percent: float) -> float:\n \"\"\"Apply a percentage discount to a price.\n\n Args:\n price: The original price in dollars.\n percent: The discount as a decimal (0.10 for 10% off).\n\n Returns:\n The discounted price, rounded to two decimal places.\n \"\"\"\n return round(price * (1 - percent), 2)\n```\n\n\nThe exact format inside the docstring (Google style, NumPy style, reStructuredText) is a project choice, not a PEP 8 rule.\n\n---\n\n# When to Break PEP 8\n\nPEP 8 itself names the situations where you should break its rules:\n\n1. **When applying the rule would make the code less readable**, even to someone used to PEP 8.\n2. **For consistency with surrounding code** that already breaks a rule. If a file uses a particular style throughout, follow it.\n3. **For consistency with code that predates PEP 8.** Legacy stdlib modules and older third-party libraries have their own conventions.\n4. **When the code needs to support an old Python version** that doesn't have a feature PEP 8 assumes.\n5. **When you have a reason and you can defend it.** \"I prefer it\" isn't a reason; \"this matches the surrounding API for symmetry\" is.\n\nA concrete example: a class that mimics an external API often uses `camelCase` method names because that's what the wrapped API uses. Forcing `snake_case` would mean every caller has to mentally translate.\n\n\n```python\nclass StripeClient:\n def createPaymentIntent(self, amount: int, currency: str) -> dict:\n # Matches Stripe's documented API name exactly.\n ...\n```\n\n\nThat's a legitimate break. Adding `camelCase` because you came from a JavaScript background is not.\n\nThe summary rule from PEP 8 itself: \"Know when to be inconsistent. Sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best.\"","pageType":"python"}

PEP 8 Style Guide

Get Premium