Encapsulation — hiding internal state, name mangling (`__name`): Worked examples

Before anything, one word we lean on constantly: an attribute is just a named box glued to an object. If you write obj.balance, then balance is an attribute — a label pointing at a value stored inside obj. When Python "mangles" a name, it secretly rewrites that label to a longer one. Keep that picture: a label being quietly rewritten.

Figure — Encapsulation — hiding internal state, name mangling (`__name`)

The scenario matrix

Every question this topic can ask falls into one of these cells. We will hit each row with at least one worked example.

#	Case class	The tricky bit	Example
A	`__name` — plain private	mangles to `_Class__name`	Ex 1
B	`__name_` — one trailing `_`	STILL mangles (≤1 back)	Ex 2
C	`__name__` — dunder	does NOT mangle (≥2 back)	Ex 3
D	`_name` — single underscore	convention only, no mangle	Ex 4
E	Inheritance clash	two `__data` become two boxes	Ex 5
F	Access from OUTSIDE the class	mangled name typed literally works	Ex 6
G	Degenerate: `__` accessed in wrong class	subclass can't see parent's `__x`	Ex 7
H	Real-world word problem	invariant guarded by property	Ex 8
I	Exam twist: `getattr`/`__dict__`	mangling happens at compile time, not lookup	Ex 9

Row by row, the decision the interpreter makes is a tiny yes/no machine. Look at the flowchart:

Every example below is just a walk down this tree.

Ex 1 — Case A: plain `__name`

Worked example Statement

class Vault:
    def __init__(self):
        self.__gold = 50
    def peek(self):
        return self.__gold
 
v = Vault()

What is v.peek()? What key appears in v.__dict__? What does v.__gold do?

Forecast: Guess all three before reading. (Hint: one of them raises.)

Identify the name. __gold — two leading underscores, zero trailing. Why this step? We must classify the name before predicting anything; the flowchart's first two branches decide everything.
Apply the rule. Inside class Vault, __gold becomes ==_Vault__gold==. So the box is actually labelled _Vault__gold. Why this step? The interpreter rewrote the label at compile time; the original word __gold no longer exists anywhere as a key.
Evaluate v.peek(). Inside peek, self.__gold is also rewritten to self._Vault__gold — same label — so it finds the box and returns 50. Why this step? Code written inside the class gets mangled the same way, so reads and writes agree.
Evaluate v.__dict__. The stored key is '_Vault__gold', value 50. Why this step? __dict__ shows the real labels, which are the mangled ones.
Evaluate v.__gold. Typed outside the class, __gold is NOT mangled (mangling only happens inside a class body), so Python looks for a box literally named __gold — none exists → AttributeError. Why this step? This is the whole "looks private" illusion.

Verify: the mangled key _Vault__gold holds 50, so getattr(v, "_Vault__gold") == 50. Checked in VERIFY.

Ex 2 — Case B: one trailing underscore `__name_`

Forecast: Two front, one back — does the "one back" spoil it?

Count trailing underscores. __x_ has exactly one trailing underscore. Why this step? The rule excludes only names with two or more trailing underscores.
Apply the rule. One trailing _ is allowed, so it mangles to ==_Box__x_== (note the trailing _ is kept). Why this step? Mangling rewrites the leading underscores' meaning but copies the rest of the name verbatim, trailing _ included.

Verify: getattr(b, "_Box__x_") == 7. Checked in VERIFY.

Ex 3 — Case C: dunder `name` (the exam trap)

Forecast: It has two underscores in front — surely it mangles? (It does not.)

Count trailing underscores. __ping__ ends with two underscores. Why this step? Two-or-more trailing → the flowchart sends us to "leave unchanged."
Conclusion: no mangling. The box keeps the literal label __ping__. Why this step? Dunders are reserved for Python's own machinery (__init__, __str__ …); mangling them would break the language, so they are exempt.
Access from outside. r.__ping__ finds the un-mangled box directly and returns "pong". Why this step? Because the label was never rewritten, the outside spelling matches the stored spelling.

Verify: the literal key __ping__ exists and equals "pong". Checked in VERIFY.

Ex 4 — Case D: single underscore `_name`

Forecast: Only one underscore — convention, not machinery.

Count leading underscores. Just one. Why this step? The rule needs at least two leading underscores; one is not enough.
Conclusion. No mangling. Key stays _tea, and c._tea returns 3 from anywhere. Why this step? A single _ is a politeness sign ("internal, please don't touch"), enforced by nobody.

Verify: c._tea == 3. Checked in VERIFY.

Ex 5 — Case E: inheritance clash (the reason mangling exists)

Worked example Statement

class Base:
    def __init__(self):
        self.__data = "base"
    def reveal(self):
        return self.__data
 
class Child(Base):
    def __init__(self):
        super().__init__()
        self.__data = "child"
    def reveal_child(self):
        return self.__data
 
k = Child()

What are k.reveal() and k.reveal_child()? How many keys in k.__dict__?

Forecast: Naively, Child.__data overwrites Base.__data → both would say "child". Mangling saves us. Guess the real answers first.

Mangle inside Base. __data written in Base becomes _Base__data = "base". Why this step? Mangling uses the class where the code is written, not the runtime class.
Mangle inside Child. __data written in Child becomes _Child__data = "child". Why this step? Different class body → different prefix → different box.
reveal reads _Base__data. reveal is defined in Base, so its self.__data compiled to self._Base__data → "base". Why this step? Methods carry the mangling of their own defining class.
reveal_child reads _Child__data. Defined in Child, so self.__data → self._Child__data → "child". Why this step? Same principle, other class.
Count keys. Two distinct boxes: _Base__data and _Child__data. So len(k.__dict__) == 2. Why this step? Two mangled names never collide — exactly the clash-avoidance goal.

Verify: all three checked in VERIFY via a simulated class.

Ex 6 — Case F: reaching in from OUTSIDE (mangling is not security)

Forecast: If mangling were security, this would fail. Does it?

Type the mangled name literally. v._Vault__gold — written outside any class body, so no mangling is applied to what you typed. Why this step? Mangling only fires on names written inside a class; here you supply the final name yourself.
Look it up. The box _Vault__gold genuinely exists (Ex 1), so this returns 50. Why this step? Nothing stops direct access — proving mangling is collision avoidance, not a lock.

Verify: getattr(v, "_Vault__gold") == 50. Checked in VERIFY.

Ex 7 — Case G: degenerate — a subclass tries to read the parent's `__x`

Worked example Statement

class Parent:
    def __init__(self):
        self.__secret = 99
 
class Kid(Parent):
    def steal(self):
        return self.__secret     # written INSIDE Kid
 
j = Kid()

What does j.steal() do?

Forecast: Kid inherits from Parent, so surely it can read __secret? Watch the mangling.

Mangle __secret in Parent. Box stored as _Parent__secret = 99. Why this step? __init__ lives in Parent.
Mangle __secret in Kid. Inside steal, self.__secret is rewritten with Kid's prefix → self._Kid__secret. Why this step? The read is compiled in Kid, so it uses _Kid__.
Look up _Kid__secret. No such box exists (only _Parent__secret does) → AttributeError. Why this step? The two names differ by class prefix, so the subclass literally cannot name the parent's private box the "easy" way — a feature, keeping internals from leaking across the hierarchy.

Verify: simulated — looking up _Kid__secret on an object holding only _Parent__secret fails. Checked in VERIFY.

Ex 8 — Case H: real-world word problem (invariant guarded)

Worked example Statement

A thermostat must never be set below absolute zero, $- 273.15^{\circ} C$ . Model it so t.celsius = -300 is rejected but t.celsius = 25 works, and t.fahrenheit is computed read-only.

class Thermostat:
    def __init__(self, c):
        self._celsius = c
    @property
    def celsius(self):
        return self._celsius
    @celsius.setter
    def celsius(self, v):
        if v < -273.15:
            raise ValueError("below absolute zero")
        self._celsius = v
    @property
    def fahrenheit(self):
        return self._celsius * 9/5 + 32
 
t = Thermostat(25)

Compute t.fahrenheit. What happens for t.celsius = -300?

Forecast: Guess the Fahrenheit of $25^{\circ} C$ before computing.

Store internal state. _celsius (single underscore) marks it internal. Why this step? We want controlled access, not clash-avoidance, so a property is the Pythonic tool — the underscore just discourages raw poking.
Compute Fahrenheit. $F = C \cdot \frac{9}{5} + 32 = 25 \cdot 1.8 + 32 = 45 + 32 = 77$ . Why this step? fahrenheit is derived, so it recomputes on every read — no stale copy.
Try the bad set. t.celsius = -300 runs the setter; $- 300 < - 273.15$ → ValueError. Why this step? The setter is the guard enforcing the invariant $C \geq - 273.15$ .
Try a good set. t.celsius = 25 passes the check and stores. Why this step? Valid values flow through untouched, so callers use clean t.celsius = ... syntax.

See Properties and Descriptors and Class Invariants & Validation for the machinery behind @property.

Verify: $25 \cdot 9/5 + 32 = 77$ . Checked in VERIFY.

Ex 9 — Case I: exam twist — `getattr` with the original name

Forecast: getattr takes a string. Does the string get mangled?

Key fact. Mangling happens at compile time on identifiers written as code inside a class body. A string passed to getattr is never mangled. Why this step? This is the trap — mangling is a source-code rewrite, not a runtime lookup transform.
getattr(v, "__gold", ...). Looks for a box literally named __gold; none exists → returns the default "MISSING". Why this step? The real box is _Vault__gold, spelled differently.
getattr(v, "_Vault__gold", ...). Finds the real box → returns 50. Why this step? You supplied the true (mangled) key as a string, matching the stored label.

Verify: both branches checked in VERIFY.

Recall Self-test — one per matrix row

__gold inside class Vault becomes what key? ::: _Vault__gold Does __x_ (one trailing underscore) mangle? ::: Yes — only ≥2 trailing underscores escape. Does __ping__ mangle? ::: No — it is a dunder (two trailing underscores). Does _tea mangle? ::: No — needs at least two leading underscores. In Ex 5, how many keys are in k.__dict__? ::: 2 (_Base__data and _Child__data). Can outsiders read v._Vault__gold? ::: Yes — mangling is not security. Why does Kid.steal() (Ex 7) fail? ::: self.__secret in Kid mangles to _Kid__secret, which doesn't exist. Fahrenheit of $2 5^{\circ}$ C? ::: $77.0$ Does a string passed to getattr get mangled? ::: No — mangling is a compile-time source rewrite only.

See also: Abstraction — hiding complexity behind interfaces, Inheritance — base and derived classes, Access Modifiers (Java vs Python), and the Hinglish walkthrough 2.1.06 Encapsulation — hiding internal state, name mangling (`__name`) (Hinglish).