{"title":"Name Mangling","description":"","content":"Name mangling is Python's one piece of compile-time machinery for attribute visibility. Writing `self.__balance` inside a class body causes Python to rewrite that to `self._ClassName__balance` everywhere in the class. This lesson covers how the rewrite works, why it exists, what problem it solves in subclass hierarchies, and where its limits are.\n\n---\n\n# The Rewrite Rule\n\nPython applies name mangling to any identifier inside a class body that starts with **two leading underscores and ends with at most one trailing underscore**. The compiler replaces the identifier with an underscore, the class name, and the original identifier:\n\n\n```python\nclass Customer:\n def __init__(self, balance):\n self.__balance = balance\n\n def show(self):\n return self.__balance\n\nalice = Customer(100.0)\nprint(vars(alice))\nprint(alice._Customer__balance)\n```\n\n\nThe instance dictionary doesn't contain `__balance`. It contains `_Customer__balance`. Inside the class body, both `self.__balance = balance` in `__init__` and `return self.__balance` in `show` were rewritten to use the mangled name. The class's methods read naturally; the storage key is something else.\n\nThe rewrite happens at compile time, once per class. It doesn't fire on every method call; the compiler has already done the substitution by the time the class object exists. From then on, the name `__balance` only resolves correctly inside code that was compiled as part of the `Customer` class body, because that's where the substitution happened.\n\n\n```mermaid\nflowchart LR\n Source[\"Source code:
self.__balance\"]:::cyan\n Compile[\"Class body
compiled\"]:::orange\n Rewrite[\"Rewrite to:
self._Customer__balance\"]:::green\n Stored[\"Stored on instance
as _Customer__balance\"]:::teal\n\n Source --> Compile --> Rewrite --> Stored\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 traces the lifecycle of a double-underscore attribute. The source code uses the short name, the compiler rewrites it during class body compilation, the rewrite produces a longer name that includes the class, and the attribute lives on the instance under that longer name. There's no runtime check that says \"is this attribute private\"; the rewrite happens once and the longer name is a different string from then on.\n\nSome details about the rule that matter in practice:\n\n- The class name used for mangling is the **class where the source code appears**, not the runtime type of the instance. The subclass section explains why this matters.\n- Only names with **at most one trailing underscore** are mangled. `__x` and `__x_` get mangled; `__x__` doesn't.\n- The mangling is a textual transformation on identifiers. It doesn't apply to string keys or dynamic attribute access. `getattr(obj, \"__balance\")` will not find the mangled storage.\n\n---\n\n# Why Mangling Exists: Subclass Collisions\n\nThe reason Python has name mangling at all isn't to provide privacy. It's to prevent a specific class of bug: a base class and a subclass independently picking the same internal attribute name and overwriting each other without any warning.\n\nConsider two classes written by different authors. The base class is part of a library; the subclass is in application code. Both happen to use `self.__id` for their own internal bookkeeping:\n\n\n```python\nclass Product:\n def __init__(self, name):\n self.name = name\n self.__id = f\"prod-{name}\"\n\n def show_product_id(self):\n return self.__id\n\nclass SubscriptionProduct(Product):\n def __init__(self, name, plan):\n super().__init__(name)\n self.__id = f\"sub-{plan}\"\n\n def show_sub_id(self):\n return self.__id\n\nsub = SubscriptionProduct(\"Pro Tier\", \"monthly\")\nprint(sub.show_product_id())\nprint(sub.show_sub_id())\nprint(vars(sub))\n```\n\n\nBoth classes write `self.__id`, but each one is rewritten using the name of the class where the source code lives. `Product.__init__` is in the `Product` class body, so its `self.__id` becomes `self._Product__id`. `SubscriptionProduct.__init__` is in the `SubscriptionProduct` class body, so its `self.__id` becomes `self._SubscriptionProduct__id`. The instance ends up with two separate attributes, one for each layer of the hierarchy.\n\nWhen `Product.show_product_id` does `return self.__id`, the lookup is for `_Product__id`, because that line of code was compiled as part of `Product`. It finds `\"prod-Pro Tier\"` and returns it. When `SubscriptionProduct.show_sub_id` does `return self.__id`, the lookup is for `_SubscriptionProduct__id`, because that line was compiled as part of `SubscriptionProduct`. It finds `\"sub-monthly\"`.\n\n\n```mermaid\nflowchart TD\n SubInst[\"SubscriptionProduct instance\"]:::cyan\n\n Attr1[\"_Product__id
prod-Pro Tier\"]:::orange\n Attr2[\"_SubscriptionProduct__id
sub-monthly\"]:::green\n\n Method1[\"Product.show_product_id
looks up _Product__id\"]:::teal\n Method2[\"SubscriptionProduct.show_sub_id
looks up _SubscriptionProduct__id\"]:::teal\n\n SubInst --- Attr1\n SubInst --- Attr2\n\n Attr1 --> Method1\n Attr2 --> Method2\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 storage layout. A `SubscriptionProduct` instance carries both `_Product__id` and `_SubscriptionProduct__id` as separate attributes. Each method only sees the one that matches the class where it was defined. Without name mangling, the second `__init__` would overwrite the first, and `show_product_id` would return `\"sub-monthly\"`, which is the wrong value for the base class's purposes.\n\nThis is the case that name mangling was designed for: a base class that wants to keep its internal state safe from subclass accidents. The author of `Product` doesn't have to know what attribute names `SubscriptionProduct` (or any other subclass) might use, and the author of `SubscriptionProduct` doesn't have to read the base class's source to avoid collisions. The mangling rule handles it automatically as long as both sides use the double-underscore convention.\n\nThe mangling isn't asking \"is this attribute private?\" It's asking \"which class authored this reference?\" The answer determines which mangled name the code looks for, and that's what keeps the two classes' attributes from colliding.\n\n---\n\n# The Mangling Is Based on the Source Class, Not the Runtime Type\n\nOne detail is easy to get wrong: name mangling uses the **class where the source code physically appears**, not the runtime type of `self`. This is a compile-time rule, and it follows the source, not the object.\n\n\n```python\nclass Base:\n def __init__(self):\n self.__data = \"from Base\"\n\n def reveal(self):\n return self.__data # rewritten inside Base -> self._Base__data\n\nclass Sub(Base):\n pass\n\nb = Base()\ns = Sub()\n\nprint(b.reveal())\nprint(s.reveal())\nprint(vars(s))\n```\n\n\n`Sub` doesn't define `__data` of its own and doesn't override `reveal`. When `s.reveal()` runs, Python finds `reveal` on `Base` (because of the normal MRO walk) and executes its body. The line `return self.__data` was compiled as part of `Base`, so the mangled name embedded in the bytecode is `_Base__data`. Even though `s` is a `Sub` instance, the lookup is still for `_Base__data`, which `Base.__init__` set, so it succeeds.\n\nNow consider what happens if `Sub` writes its own `self.__data`:\n\n\n```python\nclass Base:\n def __init__(self):\n self.__data = \"from Base\"\n\n def reveal(self):\n return self.__data # always looks up _Base__data\n\nclass Sub(Base):\n def __init__(self):\n super().__init__()\n self.__data = \"from Sub\" # writes to _Sub__data, separate attribute\n\ns = Sub()\nprint(s.reveal())\nprint(vars(s))\n```\n\n\n`Sub.__init__` writes `_Sub__data`. `Base.reveal` still looks up `_Base__data` because that's the mangled name embedded in its bytecode. The two attributes coexist on the same instance, and `reveal` returns the base's value, not the subclass's. This is what makes mangling useful as collision protection: a subclass can use any double-underscore name without disturbing the base class's storage.\n\nThis is also why double-underscore names don't behave like overrides in the usual sense. Overriding a method (or a single-underscore attribute) means the subclass's version takes precedence at lookup time. Overriding a double-underscore attribute doesn't override anything; it creates a separate, parallel attribute. That difference is the point. A regular override fits when both classes refer to the same conceptual field. A double-underscore mangled name fits when both classes happen to use the same identifier for unrelated internal state.\n\n---\n\n# Mangling Is Not Privacy\n\nOne limitation deserves emphasis: name mangling does not hide anything. The attribute is still on the instance, still readable, still writable. The mangled name is a different identifier, and any caller willing to type it can reach the value.\n\n\n```python\nclass Customer:\n def __init__(self, balance):\n self.__balance = balance\n\nalice = Customer(100.0)\n\n# Direct access through the original name fails.\ntry:\n print(alice.__balance)\nexcept AttributeError as e:\n print(f\"AttributeError: {e}\")\n\n# Access through the mangled name succeeds.\nprint(alice._Customer__balance)\n\n# Writing through the mangled name also works.\nalice._Customer__balance = -9999.0\nprint(alice._Customer__balance)\n```\n\n\nThe attribute is reachable. The mangled name is derived from a documented rule, and any caller who knows the rule can read or write the value. Python's design treats this as a feature, not a hole. Mangling was never meant to lock the attribute up; it exists to keep accidents from happening when two classes use the same `__name` for unrelated purposes. Locking would have required a different language design.\n\nThe mangling can also be bypassed using `getattr` or `setattr` with the mangled name as a string:\n\n\n```python\nclass Customer:\n def __init__(self, balance):\n self.__balance = balance\n\nalice = Customer(100.0)\nprint(getattr(alice, \"_Customer__balance\"))\nsetattr(alice, \"_Customer__balance\", 500.0)\nprint(getattr(alice, \"_Customer__balance\"))\n```\n\n\n`getattr` and `setattr` take a string and don't apply any name mangling. They look up the name as passed in. The mangled name works through them too. There's nothing the class can do to prevent this; Python's attribute model is open by default.\n\nNormal attribute access has no overhead (mangling happens once at compile time). Writing `instance._ClassName__attr` to reach into a class's mangled state opts out of the safety the mangling offered, and the next release of that class can rename the attribute without warning. The mangled name isn't a stable API.\n\nFor actual access control (preventing reads or writes, not discouraging them), Python doesn't ship a built-in tool. The closest options are `__slots__` (to forbid arbitrary new attributes), `@property` with no setter (to make a read-only attribute), or descriptors with custom `__set__` logic that raises on writes. All of those guard against specific kinds of misuse, but none of them prevent a determined caller from reaching into the instance dictionary.\n\n---\n\n# Dunders Are Exempt\n\nA name with two leading underscores **and** two trailing underscores is a \"dunder\" (double underscore on both sides). Dunders are not mangled. They're reserved by Python for the language's own protocols.\n\n\n```python\nclass Product:\n def __init__(self, name): # dunder, not mangled\n self.name = name\n\n def __str__(self): # dunder, not mangled\n return f\"Product({self.name})\"\n\nmouse = Product(\"Wireless Mouse\")\nprint(str(mouse))\nprint(mouse.__init__)\nprint(mouse.__str__)\n```\n\n\n`__init__` and `__str__` are stored under their written names, not under `_Product__init__` and `_Product__str__`. The trailing pair of underscores exempts them from the mangling rule.\n\nThe reason for the exemption is that dunders are how Python's protocols hook into classes. The interpreter calls `cls.__init__` on instantiation, `obj.__str__` when `str(obj)` runs, `obj.__len__` when `len(obj)` runs, and so on. If those names were mangled, the interpreter would have to know each subclass's name to find them, which would break the protocol mechanism. The language carves out dunders and leaves them alone.\n\nDon't invent your own dunder names. The double-underscore-on-both-sides naming pattern is reserved for the language. New protocols (like the buffer protocol or the iterator protocol) might add dunders in the future, and a method named `__myhelper__` could collide with a name the standard library starts using. For a \"private internal\" name, use a single underscore for \"internal\" or a double leading underscore (with at most one trailing underscore) for mangled.\n\n\n```mermaid\nflowchart LR\n Pub[\"name\"]:::cyan\n Prot[\"_internal\"]:::orange\n Priv[\"__hidden\"]:::green\n Dun[\"__init__\"]:::red\n\n Pub --> P1[\"stored as: name\"]:::teal\n Prot --> P2[\"stored as: _internal\"]:::teal\n Priv --> P3[\"mangled to: _Class__hidden\"]:::teal\n Dun --> P4[\"stored as: __init__
(not mangled)\"]:::teal\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 classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram lays out the four cases the mangling rule recognizes. Bare names are stored under their written form. Single-underscore names are also stored under their written form (the underscore is a convention, not a rewrite). Double-underscore names are rewritten to include the class. Dunders are stored under their written form because the trailing pair of underscores opts them out of the rewrite.\n\n---\n\n# When to Use Mangling, and When Not To\n\nThe practical question: when should a double-underscore name appear in your own code?\n\nThe answer: rarely. Most Python code does fine with the single-underscore convention. Mangling adds a small barrier against accidental access from outside the class, but it also makes the attribute harder to inspect during debugging (because `vars(instance)` shows the mangled name, not the one written in source) and harder to refer to in test fixtures that might need to reach into the internal state for setup.\n\nThe case where mangling pays off is **base classes that are designed to be subclassed and have internal attributes that subclasses must not overwrite**. A framework class that expects user code to inherit from it, with internal bookkeeping that the user shouldn't touch (and shouldn't be able to break by accident through picking the same attribute name), is the use case for double underscores. The mangling rewrites the attribute with the class name, so the subclass's same-spelled attribute lives elsewhere on the instance and the two never collide.\n\nOutside base classes meant for inheritance, mangling usually isn't needed. Use the single underscore. The decision laid out in a table:\n\n\n| Situation | Use single `_` | Use double `__` |\n| ---------------------------------------------------------------------- | -------------- | --------------- |\n| Ordinary internal state on a class that nobody subclasses | Yes | No |\n| Helper methods used only by the class itself | Yes | No |\n| Internal state on a base class meant to be subclassed | Maybe | Yes (if collision risk is real) |\n| Naming conflict with a likely subclass attribute (e.g., `__id`, `__type`) | No | Yes |\n| Anything you want a real lock on (no access from outside) | No (use property/slots) | No |\n\n\nTwo rows are worth highlighting. The third row is the use case where mangling fits: when collision risk is real, mangling is the answer. The last row is the trap: double underscores sometimes get reached for to obtain true privacy, but Python doesn't give privacy, just an awkwardly-named accessor.\n\nPython codebases tend to use double underscores sparingly. The Python standard library uses them in a few base classes (parts of `collections`, `unittest`, some abstract base classes), but for ordinary application code, the single-underscore convention does almost all the work. When in doubt, single underscore is the safer default.\n\n---\n\n# Inspecting What's Really Stored\n\nThe fastest way to understand what mangling did to a class is to look at the instance directly. `vars(instance)` returns the instance's `__dict__`, which is the literal storage that backs attribute lookups.\n\n\n```python\nclass Order:\n def __init__(self, order_id):\n self.order_id = order_id # public\n self._customer = \"Alice\" # internal (convention)\n self.__total = 49.99 # private (mangled)\n self.__status_ = \"placed\" # also mangled (only one trailing _)\n\no = Order(1001)\nprint(vars(o))\n```\n\n\nFour attributes, three different storage rules. `order_id` and `_customer` are stored under their written names. `__total` and `__status_` are both mangled because both have two leading underscores and at most one trailing underscore. Defining `__status__` instead (two trailing underscores) would make it a dunder and exempt from mangling.\n\n`dir(instance)` shows more, including the class's methods and the dunders inherited from `object`:\n\n\n```python\nmangled_only = [n for n in dir(o) if n.startswith(\"_Order__\")]\nprint(mangled_only)\n```\n\n\nFiltering for the `_ClassName__` prefix isolates the mangled storage. This is a useful trick when debugging to see which attributes the class created through mangling versus which it created as plain underscore-prefixed names.\n\nTo confirm the mangling rule in the REPL:\n\n\n```python\nclass Foo:\n def __init__(self):\n self.__bar = 1\n self.__baz_ = 2\n self.__qux__ = 3 # dunder, not mangled\n\nf = Foo()\nprint(sorted(vars(f).keys()))\n```\n\n\n`__bar` and `__baz_` are both mangled because each has at most one trailing underscore. `__qux__` has two trailing underscores, which puts it in dunder territory, so it's stored under its original name. This is the kind of quick check worth running once when learning the rule, because the trailing-underscore distinction is the easiest part to overlook.","pageType":"python"}

Name Mangling

Get Premium