{"title":"Class Attributes","description":"","content":"A class attribute is a value defined at class scope, outside any method. It's stored on the class itself, not on any individual instance, so every instance of the class sees the same value through the same name. This lesson covers what class attributes are, how Python finds them during attribute reads through an instance, the rules for when an instance \"sees\" a class attribute versus its own, the shared-mutable-attribute pitfall, and how to decide between a class attribute and an instance attribute when modeling a new class.\n\n---\n\n# Defining a Class Attribute\n\nA class attribute is any name assigned inside the class body, outside a method. The assignment runs once, when the class is being defined, and the result lives on the class object.\n\n\n```python\nclass Product:\n tax_rate = 0.08\n currency = \"USD\"\n\n def __init__(self, name, price):\n self.name = name\n self.price = price\n```\n\n\n`tax_rate` and `currency` are class attributes. They aren't set per instance; they belong to `Product` itself. Every `Product` instance reads them through the dot, and the value comes from the class:\n\n\n```python\nmouse = Product(\"Wireless Mouse\", 29.99)\nkeyboard = Product(\"Mechanical Keyboard\", 89.99)\n\nprint(mouse.tax_rate, mouse.currency)\nprint(keyboard.tax_rate, keyboard.currency)\nprint(Product.tax_rate, Product.currency)\n```\n\n\nAll three reads return the same value because the value lives in one place: on the `Product` class. The two instances aren't carrying their own copies; they fall back to the class when they don't have a matching instance attribute. The same fact shows up directly when inspecting the class's `__dict__`:\n\n\n```python\nprint({k: v for k, v in Product.__dict__.items() if not k.startswith(\"_\")})\n```\n\n\nThe class has its own dict, separate from any instance's `__dict__`. Class-level assignments (like `tax_rate = 0.08`) write to the class's dict. Method definitions inside the class body also live there, which is why methods can be called through instances even though they're defined once on the class.\n\nClass attributes that act as constants (values that should never change at runtime) are usually written in `UPPER_SNAKE_CASE`, like `MAX_RETRIES` or `DEFAULT_TAX_RATE`. Class attributes that act as mutable defaults or counters are written in `snake_case` like instance attributes. Python doesn't enforce either, but the casing signals intent to readers.\n\n---\n\n# The Attribute Lookup Order\n\nAttribute reads check the instance first and fall back to the class. The full lookup spelled out below is the rule that explains every interesting behavior involving class attributes.\n\nWhen `obj.name` is read, Python runs through these steps:\n\n1. Check `obj.__dict__` for the name. If found, return it.\n2. Check `type(obj).__dict__` for the name. If found, return it.\n3. Walk up the **method resolution order** (MRO) of the class, checking each base class's `__dict__`. If found, return it.\n4. If nothing found, raise `AttributeError`.\n\nFor ordinary classes with one parent (`object`), step 3 is `object.__dict__`, which carries the built-in dunders. The MRO becomes more interesting with multiple inheritance. For class attributes vs instance attributes, the important steps are 1 and 2: instance first, class second.\n\n\n```mermaid\nflowchart LR\n Read[\"mouse.tax_rate\"]:::cyan\n InstDict{\"in
mouse.__dict__?\"}:::orange\n ClassDict{\"in
Product.__dict__?\"}:::orange\n MRO{\"in any
base class?\"}:::orange\n Found1[\"return instance value\"]:::green\n Found2[\"return class value\"]:::green\n Found3[\"return base class value\"]:::green\n Fail[\"AttributeError\"]:::red\n\n Read --> InstDict\n InstDict -->|yes| Found1\n InstDict -->|no| ClassDict\n ClassDict -->|yes| Found2\n ClassDict -->|no| MRO\n MRO -->|yes| Found3\n MRO -->|no| 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\nThe diagram shows the full lookup. For most reads in everyday code, one of the first two checks succeeds. The instance dict is the fast path for attributes that vary per instance (`name`, `price`, `stock`); the class dict is the fast path for shared values and methods (`tax_rate`, `currency`, every method defined in the class body).\n\nThe asymmetric part to remember: **writes always go to the instance**. An assignment `mouse.tax_rate = 0.05` writes to `mouse.__dict__`, not to the class. The class attribute is untouched. The instance now has its own `tax_rate` that shadows the class one for that instance only.\n\n---\n\n# Shadowing: How Instance Attributes Hide Class Attributes\n\nAfter establishing that reads search the instance first, the next step is what happens when both the instance and the class have an attribute with the same name. The instance wins, but only for that instance. Other instances still see the class value.\n\n\n```python\nclass Product:\n tax_rate = 0.08\n\n def __init__(self, name, price):\n self.name = name\n self.price = price\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nkeyboard = Product(\"Mechanical Keyboard\", 89.99)\n\nprint(mouse.tax_rate, keyboard.tax_rate) # both from the class\n\nmouse.tax_rate = 0.05 # creates an instance attribute on mouse\n\nprint(mouse.tax_rate, keyboard.tax_rate) # mouse from itself, keyboard still from class\nprint(Product.tax_rate) # the class is untouched\n```\n\n\nBefore the assignment, neither instance has a `tax_rate` of its own, so both reads fall through to the class. The line `mouse.tax_rate = 0.05` writes a new key into `mouse.__dict__`. After that, reading `mouse.tax_rate` finds the value on the instance and stops (step 1 of the lookup). Reading `keyboard.tax_rate` still doesn't find anything on the instance and falls through to the class (step 2), so it still returns `0.08`. Reading `Product.tax_rate` directly goes straight to the class and confirms the class value never changed.\n\nThe shadowing also appears in the dictionaries:\n\n\n```python\nprint(mouse.__dict__)\nprint(keyboard.__dict__)\n```\n\n\n`mouse.__dict__` now has a `tax_rate` key (the shadow), while `keyboard.__dict__` doesn't. The class still has its own `tax_rate` of `0.08`; the lookup stops at the instance for `mouse` because it found a match there first.\n\nThe shadow can be undone with `del`:\n\n\n```python\ndel mouse.tax_rate\nprint(mouse.tax_rate) # back to the class value\n```\n\n\nRemoving the instance attribute means the lookup falls through to the class again. `mouse` is back to seeing the shared value.\n\nThis shadowing rule is one of Python's stranger corners and the source of plenty of bugs. A short way to keep it straight: **reads see the instance if it has the name, otherwise the class. Writes always go to the instance, never the class.**\n\n---\n\n# The Shared Mutable Class Attribute Trap\n\nThe shadowing rule works as expected for immutable values like strings, numbers, and tuples. Assignments to an instance attribute create a new value on the instance without touching the class. But mutable class attributes (lists, dicts, sets) behave differently.\n\n**What's wrong with this code?**\n\n\n```python\nclass Cart:\n items = [] # class attribute, shared across all instances\n\n def add(self, item):\n self.items.append(item)\n\ncart_a = Cart()\ncart_a.add(\"Mouse\")\n\ncart_b = Cart()\ncart_b.add(\"Keyboard\")\n\nprint(cart_a.items)\nprint(cart_b.items)\n```\n\n\nBoth carts show both items. The class attribute `items` is one list, and every instance is reading and mutating that one list through `self.items`. When `cart_a.add(\"Mouse\")` runs, `self.items.append(\"Mouse\")` mutates the list living on the class. When `cart_b.add(\"Keyboard\")` runs, it mutates the same list. The result: every cart sees the same items, because there's only one list.\n\nThe trap hinges on the distinction between **assignment** and **mutation**:\n\n- `self.items = [...]` is an assignment. It creates a new instance attribute that shadows the class one.\n- `self.items.append(...)` is a mutation. It modifies the object `self.items` refers to, which (because no instance ever assigned its own `items`) is the class-level list.\n\nThe difference shows up in `__dict__`:\n\n\n```python\nprint(cart_a.__dict__)\nprint(cart_b.__dict__)\nprint(Cart.__dict__[\"items\"])\n```\n\n\nNeither cart has anything in its own `__dict__`. The list lives on the class, and both instances are reading and mutating that one list through the fallback lookup.\n\n**Fix:** initialize the mutable attribute as an instance attribute in `__init__`, not as a class attribute.\n\n\n```python\nclass Cart:\n def __init__(self):\n self.items = [] # instance attribute, per-instance\n\n def add(self, item):\n self.items.append(item)\n\ncart_a = Cart()\ncart_a.add(\"Mouse\")\n\ncart_b = Cart()\ncart_b.add(\"Keyboard\")\n\nprint(cart_a.items)\nprint(cart_b.items)\n```\n\n\nNow each cart gets its own list in `__init__`, and `self.items.append(...)` mutates the per-instance list. The class no longer has an `items` attribute at all; each instance carries its own.\n\nThe general rule: **mutable values (lists, dicts, sets) should almost always be instance attributes, not class attributes**. Class attributes fit shared constants, configuration that genuinely is the same for every instance, and immutable defaults. When the requirement is \"every instance should start with an empty list\", that list belongs in `__init__`, not at class scope.\n\nThis trap is a correctness issue, not a performance one. The bug usually shows up far from the class definition (a test failing for \"no reason\", a customer's cart having items from another customer's session), which makes it expensive to debug. The fix takes one line; the diagnosis can take an hour.\n\n\n```mermaid\nflowchart TD\n A[\"Cart.items = []
at class scope\"]:::orange\n\n B[\"cart_a = Cart()\"]:::cyan\n C[\"cart_b = Cart()\"]:::cyan\n\n A -->|\"both instances share
this one list\"| B\n A --> C\n\n D[\"cart_a.add('Mouse')
mutates Cart.items\"]:::red\n E[\"cart_b.add('Keyboard')
also mutates Cart.items\"]:::red\n\n B --> D\n C --> E\n\n F[\"Cart.items == ['Mouse', 'Keyboard']
both carts see both items\"]:::red\n\n D --> F\n E --> F\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\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 flow of the bug. One list lives on the class. Both instances reach that list through `self.items`. Each `add` mutates the same object, so the final state is visible through both instances. The red nodes mark the consequence: the mutation reaches the class, and both carts end up with both items.\n\n---\n\n# Common Uses of Class Attributes\n\nWhen are class attributes a good fit? A few patterns come up regularly enough to recognize.\n\n### Constants\n\nIf a value is the same for every instance and shouldn't change at runtime, a class attribute is a clean place for it. The class is the natural namespace, and reading `Class.CONSTANT` documents that the value belongs to the class.\n\n\n```python\nclass Product:\n MAX_PRICE = 100_000.0\n MIN_PRICE = 0.01\n DEFAULT_TAX_RATE = 0.08\n\n def __init__(self, name, price):\n if not (Product.MIN_PRICE <= price <= Product.MAX_PRICE):\n raise ValueError(f\"price out of range: {price}\")\n self.name = name\n self.price = price\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nprint(f\"{mouse.name}: ${mouse.price}\")\nprint(f\"Allowed range: ${Product.MIN_PRICE} to ${Product.MAX_PRICE}\")\n```\n\n\nThe three constants describe the class's rules. Storing them on the class means they're available wherever the class is, they're easy to find when looking up the limits, and changing one number updates every place that uses it. Uppercase signals \"this is a constant; don't mutate it\".\n\n### Shared Defaults\n\nIf a value is a sensible default for every instance and rarely overridden, a class attribute can serve as the default. Reads fall through to the class until an instance sets its own value, at which point the shadowing rule takes over.\n\n\n```python\nclass Order:\n status = \"placed\"\n shipping_method = \"standard\"\n\n def __init__(self, order_id, customer):\n self.order_id = order_id\n self.customer = customer\n\na = Order(101, \"Alice\")\nb = Order(102, \"Bob\")\n\nprint(f\"{a.order_id}: {a.status}, {a.shipping_method}\")\nprint(f\"{b.order_id}: {b.status}, {b.shipping_method}\")\n\na.status = \"shipped\"\na.shipping_method = \"express\"\n\nprint(f\"{a.order_id}: {a.status}, {a.shipping_method}\")\nprint(f\"{b.order_id}: {b.status}, {b.shipping_method}\")\n```\n\n\nBoth orders start with the class defaults (`placed`, `standard`). When `a` updates its `status` and `shipping_method`, those updates create instance attributes that shadow the class values for `a` only. `b` still reads from the class. This is a clean pattern when most instances genuinely use the defaults and a small minority deviate.\n\nThe same pattern would be a bug if the default were mutable (a list, dict, or set), for the reasons covered above. Use class-attribute defaults only for immutable values; for mutable defaults, set them per instance in `__init__`.\n\n### Per-Class Counters\n\nA class attribute that gets mutated through the class itself can serve as a counter or registry. Every instance affects the same shared value, which is sometimes the goal.\n\n\n```python\nclass Product:\n instance_count = 0\n\n def __init__(self, name, price):\n self.name = name\n self.price = price\n Product.instance_count = Product.instance_count + 1\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nkeyboard = Product(\"Mechanical Keyboard\", 89.99)\ncable = Product(\"USB Cable\", 9.99)\n\nprint(f\"Created {Product.instance_count} products\")\n```\n\n\nThe constructor reads and writes `Product.instance_count` directly (through the class, not through `self`). Going through the class is the key: `self.instance_count = self.instance_count + 1` would read the class value but write to the instance, creating a shadow on every instance and leaving the class counter at `0` forever.\n\nThis pattern shows up in factories, ID generators, and bookkeeping for debug tooling. Use it carefully: shared mutable state is easy to misuse, and a function-level counter or a separate registry object is often cleaner.\n\n### Class-Level Metadata\n\nSometimes a class attribute carries metadata about the class itself: a name, a version, a category, a configuration object. It doesn't change per instance and isn't a \"default\" so much as a property of the class.\n\n\n```python\nclass PaymentProcessor:\n name = \"AlgoMaster Pay\"\n version = \"2.1.0\"\n supported_currencies = (\"USD\", \"EUR\", \"GBP\", \"INR\")\n\nprint(f\"{PaymentProcessor.name} v{PaymentProcessor.version}\")\nprint(f\"Currencies: {', '.join(PaymentProcessor.supported_currencies)}\")\n```\n\n\nThe tuple `supported_currencies` is immutable, so the shared-mutable trap doesn't apply. Reading these through the class (without creating any instance) is the typical access pattern, because the metadata describes the class itself, not any particular instance.\n\n---\n\n# Class vs Instance: How to Choose\n\nWhen modeling a new class, the question \"should this attribute be on the class or on the instance?\" comes up for every piece of data. A few rules of thumb:\n\n\n| Question | If the answer is yes... |\n|----------|------------------------|\n| Will this value differ from one instance to the next? | Instance attribute (set in `__init__`) |\n| Is this value mutable (list, dict, set)? | Instance attribute (almost always) |\n| Is this value the same for every instance and shouldn't change at runtime? | Class attribute (constant, uppercase) |\n| Is this value an immutable default that most instances use but a few override? | Class attribute (snake_case, but consider explicit instance default for clarity) |\n| Are you tracking something across the whole class (counter, registry, cache)? | Class attribute, mutated through the class |\n| Does this represent the class's identity or metadata (name, version)? | Class attribute |\n\n\nThe single most reliable instinct: **if it's mutable and per-instance, use `__init__`**. That one rule sidesteps the worst of the shared-mutable trap. When in doubt about an immutable value, defaulting to an instance attribute is usually safe; an immutable value can be promoted to a class attribute later if it really is the same across every instance.\n\nA worked example that uses both:\n\n\n```python\nclass Product:\n # class attributes (shared)\n MAX_DISCOUNT = 0.50 # constant\n DEFAULT_CURRENCY = \"USD\" # immutable default\n instance_count = 0 # per-class counter\n\n def __init__(self, name, price, currency=None):\n # instance attributes (per-object)\n self.name = name\n self.price = price\n self.currency = currency or Product.DEFAULT_CURRENCY\n self.tags = [] # mutable, must be per-instance\n\n Product.instance_count = Product.instance_count + 1\n\n def add_tag(self, tag):\n self.tags.append(tag)\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nmouse.add_tag(\"wireless\")\nmouse.add_tag(\"ergonomic\")\n\nkeyboard = Product(\"Mechanical Keyboard\", 89.99, currency=\"EUR\")\nkeyboard.add_tag(\"backlit\")\n\nprint(f\"{mouse.name}: {mouse.tags}, {mouse.currency}\")\nprint(f\"{keyboard.name}: {keyboard.tags}, {keyboard.currency}\")\nprint(f\"Total products created: {Product.instance_count}\")\nprint(f\"Max discount allowed: {Product.MAX_DISCOUNT * 100}%\")\n```\n\n\nEvery choice in the class fits its category: `MAX_DISCOUNT` and `DEFAULT_CURRENCY` are immutable and shared (class), `instance_count` is shared mutable state managed through the class (class, with explicit `Product.attr` updates), and `name`, `price`, `currency`, and `tags` vary per instance (set in `__init__`). The mutable `tags` list is per instance, which sidesteps the shared-list trap.\n\n---\n\n# Type Annotations on Class Attributes (PEP 526)\n\nPython allows annotating class attributes with type hints, the same way function parameters are annotated. The annotations don't change runtime behavior; they document intent and help tools like `mypy` catch type mistakes.\n\n\n```python\nclass Product:\n MAX_PRICE: float = 100_000.0\n DEFAULT_CATEGORY: str = \"general\"\n\n def __init__(self, name: str, price: float):\n self.name = name\n self.price = price\n\nprint(Product.MAX_PRICE)\nprint(Product.DEFAULT_CATEGORY)\n```\n\n\nThe `: float` and `: str` annotations are documentation as far as the interpreter is concerned. Reading them shows a future reader the expected type of each attribute, and type checkers can flag code that assigns the wrong type.\n\nA `ClassVar` annotation also exists for cases where being explicit that an attribute is a class attribute, not an instance attribute, matters. This is most important with `@dataclass`, which would otherwise treat any annotated class-level assignment as an instance attribute description:\n\n\n```python\nfrom dataclasses import dataclass\nfrom typing import ClassVar\n\n@dataclass\nclass Product:\n name: str\n price: float\n DEFAULT_TAX_RATE: ClassVar[float] = 0.08\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nprint(mouse.name, mouse.price)\nprint(Product.DEFAULT_TAX_RATE)\nprint(\"DEFAULT_TAX_RATE\" in mouse.__dict__)\n```\n\n\nThe `ClassVar[float]` annotation tells `@dataclass` \"don't include this in the generated `__init__`; keep it on the class\". Without `ClassVar`, the dataclass would add `DEFAULT_TAX_RATE` to the constructor's parameter list, which is almost never the right behavior for a constant. The print at the end confirms the attribute didn't end up on the instance.\n\n`ClassVar` can be used outside dataclasses too, where it's purely documentation. Tools and readers see \"this is intentionally a class attribute\"; the interpreter still resolves the lookup through the same MRO walk as any other class-level name.","pageType":"python"}

Class Attributes

Get Premium