Python Encapsulation: Public, Protected and Private

3Python Encapsulation: explained step by step

Imagine a bank account object where any line of code, anywhere in the program, can write acct.balance = -5000. Nothing stops it, and the object quietly becomes invalid. Encapsulation is the habit of keeping an object's data together with the methods that work on it, and then letting the data change only through those methods, so they can check every request.

Why hide internal data?

Here is a class with no protection at all:

class NaiveAccount:
    def __init__(self, owner, balance):
        self.owner = owner
        self.balance = balance

acct = NaiveAccount("Asha", 100)
acct.balance = -5000          # nothing stops this
print(acct.owner, acct.balance)

A balance of -5000 can never be right, but the class has no way to refuse it. Keeping the data behind methods gives you three things:

• The object stays valid. The rules (a balance is never negative) live in one place, so no other code can break them by accident.
• You can change the inside later. If code outside only uses deposit() and get_balance(), you can store the money as cents or in a list tomorrow and nobody else has to change.
• It is simpler to use. Other programmers only need to learn a handful of methods, not every detail of how the object works.

Public, protected and private

Languages like Java have keywords such as private that the compiler enforces. Python has no such keywords. It uses naming conventions instead:

One underscore: a sign on the door

A single leading underscore is a message to other programmers: this is an internal detail, use the methods instead.

class BankAccount:
    def __init__(self, owner, balance=0):
        self.owner = owner
        self._balance = balance       # internal: use the methods

    def get_balance(self):
        return self._balance

acct = BankAccount("Asha", 100)
print(acct.get_balance())
print(acct._balance)                  # works, but you are ignoring the sign

Python does not block that last line. The underscore works like a "staff only" sign: it tells everyone that this name may change without warning, and that code relying on it is on its own.

Two underscores: name mangling

A name that starts with two underscores (and does not end with two) is mangled: Python rewrites it to _ClassName__name when it reads the class. Code inside the class is rewritten too, so the methods keep working. Code outside asks for a name that no longer exists.

class Vault:
    def __init__(self, code):
        self.__code = code

    def check(self, guess):
        return guess == self.__code

vault = Vault(4821)
print(vault.check(4821))
print(sorted(vars(vault)))
print([name for name in dir(vault) if "code" in name])
print(vault._Vault__code)
try:
    print(vault.__code)
except AttributeError as err:
    print("AttributeError:", err)

The attribute is still there under its mangled name, so anyone can reach it. Mangling is not security. Its real purpose is to stop a name from clashing by accident, for example when someone later builds a new class on top of yours and picks the same attribute name. Most Python code never needs it and uses a single underscore instead.

A small public interface

Think of the public methods as the buttons on a machine: deposit, withdraw, get_balance. Everything else stays inside. Every method that changes the data checks the request first. When a value makes no sense, the method raises ValueError (the right type of value, but an unacceptable one). That is louder than quietly returning False, because a caller cannot ignore an exception by accident. If you need a reminder of how try and except work, see the exceptions lesson.

class BankAccount:
    def __init__(self, owner, balance=0):
        self.owner = owner
        self._balance = balance

    def deposit(self, amount):
        if amount <= 0:
            raise ValueError("deposit must be positive")
        self._balance += amount

    def withdraw(self, amount):
        if amount <= 0:
            raise ValueError("withdrawal must be positive")
        if amount > self._balance:
            raise ValueError("not enough money")
        self._balance -= amount

    def get_balance(self):
        return self._balance

acct = BankAccount("Asha", 100)
acct.deposit(50)
for bad in (-20, 500):
    try:
        acct.withdraw(bad)
    except ValueError as err:
        print("Refused:", err)
print(acct.get_balance())

Both bad requests are refused and the balance is still 150. The rule "never negative" is enforced in exactly one place.

Getter-style methods

get_balance() is a getter: a method whose job is to hand back an internal value. Its partner, a setter, stores a new value after checking it. In Python you only write them when they add something, such as validation. An attribute with no rules can simply be public, and a plain owner attribute is perfectly fine.

Calling acct.get_balance() is a little clumsy compared with acct.balance. The next lesson, on properties, shows how to keep the nice attribute-style spelling and still run your checks behind the scenes.

Don't hand out your internals

If a getter returns an internal list or dictionary, the caller receives the real object and can change it behind your back. Return a copy instead:

def get_songs(self):
    return list(self._songs)      # a copy: callers cannot change the original

"We are all consenting adults"

Python's designers trust programmers. Instead of locking things away, the language gives you conventions and expects you to follow them. Treat an underscore as a contract: use the public methods, and if you do reach into _something (for example while debugging), know that the class's author is free to break it in the next version.

Which one should I use?

• Start with a public name.
• Use _name for helper methods and for data that has rules to protect.
• Use __name only when you really need to avoid clashes between classes, which is rare.
• Anything that must never be wrong (a balance, a temperature range) should be changed only by methods that check it.