Name Mangling and Privacy

Python has no `private` keyword. What it has instead are two spellings that look alike and operate on completely different levels: a leading **single** underscore, which is a message to human readers, and a leading **double** underscore, which is an instruction to the compiler. ## `_name` — the convention A single leading underscore on a module-level name, a class attribute, a method or a function means "this is internal; I may change it without warning". The interpreter enforces nothing. `obj._buffer` reads fine from anywhere, `dir(obj)` lists it, and `vars(obj)` shows it spelled exactly as written. The one place the language notices the prefix is star-import: `from module import *` skips module-level names that begin with a single underscore — unless the module defines `__all__`, in which case `__all__` alone decides what is exported. Everything else about the convention is enforced socially, by code review and by linters that flag reaching into another object's underscore names. ## `__name` — the rewrite An identifier written textually inside a class body that begins with two or more underscores and does **not** end in two or more underscores is transformed by the compiler into `_ClassName__name`, with the class name's own leading underscores stripped. This is *private name mangling*. It happens while the class body is compiled, so nothing resolves it at run time — by the time the code executes, the identifier simply **is** `_Order__token`: ```python class Order: def __init__(self): self.__token = "x" print(vars(Order())) # {'_Order__token': 'x'} ``` The rewrite applies to every identifier in the class body, not only to attributes: method names, class-level constants, and even bare name references inside a method. A method that reads a module-level global written `__g` compiles to a lookup of `_ClassName__g` and raises `NameError` — a genuine surprise the first time you hit it. ## What mangling is actually for It exists to keep a base class's internal state from colliding with a subclass's. Imagine a base class that stores `self.__state` and a method that reads it. A subclass author who happens to pick the name `__state` for something unrelated does not corrupt the base: the base's code compiled to `_Base__state`, the subclass's to `_Sub__state`, and both keys sit side by side in the instance `__dict__`. The same property is what makes mangled names safe inside a mixin intended to be combined with classes it has never seen. ## What mangling is not It is not privacy, and describing it as "private" in an interview is the classic wrong answer. `obj._Order__token` works from any module. `vars(obj)` and `dir(obj)` display the mangled name. Debuggers, `pickle`, serializers and anything that walks `__dict__` see it. The mangled spelling is also a nuisance in exactly those places: `dataclasses`, ORM-style attribute mapping, and any helper that resolves attributes from strings must know the prefix, because the rewrite only touches identifiers in source code and never a string. ## Which to use Default to one underscore. It communicates intent, keeps the name stable for tests, debuggers and serialization, and costs nothing. Use two only where the collision risk is real: a widely subclassed base class or a mixin whose bookkeeping must not be silently overwritten. Using `__name` everywhere as a Java-style `private` produces mangled keys throughout your dumps and tracebacks while providing no protection whatsoever. ## The neighbouring spellings `__dunder__` names such as `__init__` end in two underscores, so the rule deliberately exempts them — mangling them would break every protocol method. A name with a *single* trailing underscore is not exempt: `__x_` inside `class Trail` still mangles to `_Trail__x_`. A **trailing** single underscore, as in `class_` or `id_`, is a separate convention for avoiding a clash with a keyword or a builtin, and involves no rewriting at all. Finally, if the enclosing class's name consists only of underscores, there is nothing left after stripping them and no mangling occurs. ## Why the language settled here Enforced privacy needs the runtime to check who is asking on every attribute access, and Python's object model deliberately does not have that machinery: attributes are dictionary entries, and any code holding the object can read the dictionary. Rather than fake a guarantee it could not keep, the language shipped the cheap half of the problem — making sure two unrelated authors do not accidentally choose the same attribute name in the same object — and left intent to convention. That is why the honest one-sentence summary of `__name` is "namespaced by class", not "private". ## How it shows up in review The practical signal in a code review is a caller reaching past an underscore. `other._parser.reset()` is a design smell, not an error, and the fix is usually to add a method rather than to add underscores. Conversely, a class whose every attribute is spelled with two underscores is a class whose tracebacks, `repr` output, pickles and test fixtures all carry the class name inside attribute keys for no benefit — that is the pattern to push back on.