How Does Python Handle Private Attributes?

An attribute whose name starts with two underscores is mangled by the interpreter. The interpreter puts the class name in front of it, so that it cannot accidentally clash with an attribute of the same name in a subclass.

class Account:
    def __init__(self, balance):
        self.__balance = balance

    def get_balance(self):
        return self.__balance

    def set_balance(self, value):
        if value < 0:
            raise ValueError('balance cannot be negative')
        self.__balance = value


acc = Account(100)
print(acc.get_balance())   # 100
acc.set_balance(150)
print(acc.get_balance())   # 150

# The real attribute name is mangled.
print(acc._Account__balance)  # 150

try:
    print(acc.__balance)
except AttributeError as error:
    print('AttributeError:', error)

The attribute really does exist, but under the name _Account__balance. Inside the class body, the compiler rewrites every reference to __balance, so the public methods all see the same mangled attribute and everything works in a consistent way.

The access from outside the class fails because acc.__balance is looked up exactly as it is written, and there is no attribute with that exact name. The mangled name can still be reached, as the third block shows. Mangling is a change of name and not a way of locking the data away.

Notice the check inside set_balance. Because the attribute is meant to stay private, a public method that checks the value before storing it is the normal way to keep the object in a valid state.

Python has two underscore conventions, and they mean different things. A single leading underscore, such as _name, is a convention only. It tells other programmers that the attribute is internal, and it is left out of wildcard imports such as from module import *. Nothing stops anybody from using it, though.

A double leading underscore, such as __name, triggers name mangling. When the class body is compiled, any identifier of the form __name with at most one trailing underscore is rewritten to _ClassName__name. The attribute genuinely exists under that name inside the instance, which is why you can still reach it with acc._Account__balance.

The purpose of mangling is not security. It is to avoid name collisions. Because the mangled name includes the class name, a subclass that also defines __value cannot accidentally overwrite the private attribute of its parent. That is a real benefit, and it is the reason mangling exists at all.

What mangling is not is access control. Anybody who knows the mangled name can read or write the attribute, and Python has no mechanism that truly prevents it. The normal approach in Python is therefore to expose a read-only property and keep the underlying attribute private, so that your validation always runs.

Two final details. Name mangling applies to attributes and not to method names, and it does not apply to names with two leading underscores and two or more trailing underscores, because those are left alone.