Encapsulation and access: keep the rule with the state

Keep an object’s invariant behind an intent-based API, then compare Java access rules with Python’s conventions. Objects and access · Object-oriented programming.

A shop app shows a customer's wallet balance as -5. No payment took it below zero, yet some code wrote that number. Many objects have a rule like this: a balance never goes below zero. Encapsulation means keeping an object's data and its rules together, so other code cannot change the data directly. It has to ask for an intent-based operation, one named for what the caller wants done, such as deposit(4), and the object checks the request first. Follow two wallets that both start at 12: one lets any code overwrite the balance, the other accepts only deposits.

The rule that must always hold is the object's invariant: here balance >= 0. What a request must satisfy before the object accepts it is a precondition: a deposit must be a positive whole number. Zero is a valid balance, but zero is not a valid deposit under this contract. A private field can be touched only by code inside its own class; a public operation can be called by any code.

Compare two separate wallets, each starting at 12. UnsafeWallet has a private balance but also a public blind setBalance(value): a setter overwrites a field with whatever it is given, while a getter only reads it. Calling setBalance(-5) replaces 12 with -5, breaking the invariant. Wallet exposes deposit instead: deposit(-5) is rejected and leaves 12; deposit(0) is also rejected and leaves 12; deposit(4) passes the check and adds 4, changing 12 to 16. Replacing a balance and adding a deposit are different operations, deliberately compared as API designs.

The rejection happens before a write; it is not an automatic rollback of a bad write. A private field helps only when the surrounding API preserves the rule. A blind setter offers a path around it, while an intent-based operation checks its request at the point that owns the state.

Java and Python name the boundary differently

In Java, a private member is checked by the language’s access rules at compile time. For an unrelated ordinary caller outside the Wallet’s top-level class, a direct wallet.balance access is rejected before it can run; an accessible public deposit call can enter the Wallet method, which may update its own private field. Java also has package and protected access; the deeper section below covers them.

Python does not provide a Java-like private instance field. A single leading underscore marks an implementation detail that callers are asked to respect. A double leading underscore triggers name mangling, which helps avoid accidental clashes with a subclass name: inside class Wallet, __balance is stored as _Wallet__balance, so it remains an ordinary object attribute reachable through that name. An ordinary caller can read or assign wallet._balance directly: the underscore itself does not run the deposit check. The convention can guide an API, but it does not enforce a compile-time barrier.

Here the two snippets preserve the same wallet rule with language-specific mechanisms. Java blocks ordinary direct access to balance; Python asks callers to use deposit while storing the implementation detail in _balance.

final class Wallet {
    private int balance = 0;

    public void deposit(int amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException("amount must be positive");
        }
        balance = Math.addExact(balance, amount);
    }

    public int balance() {
        return balance;
    }
}

class Wallet:
    def __init__(self):
        self._balance = 0

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

    @property
    def balance(self):
        return self._balance

These examples define an amount as a positive whole-number unit. Math.addExact makes an overflowing deposit throw instead of wrapping to a negative balance, and the Python check accepts only exact integers.

To design a class this way, first write down the rule that must never break. Then offer one operation for each thing callers really want to do, such as deposit, and check the request inside it. Keep the field itself hidden. If the rule changes later, say a deposit limit, you edit one method instead of every caller.

Transfer the rule to a seat pool

A SeatPool has capacity 8 and starts with 4 seats available. Its invariant is 0 <= available <= capacity. Its reserve(count) operation accepts a positive integer no greater than the available seats. Starting at 4, reserve(3) passes and writes 1; reserve(2) is rejected because only 1 remains; reserve(0) is rejected because a reservation must be positive. Both rejected requests leave 1 available. The invariant describes valid pool state; the precondition describes which request the operation accepts.

Recap

• Start with the invariant and expose an operation that can preserve it; a modifier name alone is not a design.
• Java access checks and Python underscore conventions have different strength and meaning.
• Expose only the operations callers need, so a rule has one place to change.

// p1/Base.java
package p1;

public class Base {
    protected int code = 7;
}

// p2/Child.java
package p2;

import p1.Base;

public class Child extends Base {
    int readThroughChild() {
        Child child = this;
        return child.code;              // allowed
    }

    int readThroughBase() {
        Base base = this;
        return base.code;               // compile-time error
    }
}

class Base:
    def __init__(self):
        self._code = 7


def read_through_both_names(value):
    child = value
    base = value
    return child._code, base._code


record = Base()
read_through_both_names(record)

Next, follow call arguments and rebinding across a method boundary. Later, explore shallow and deep copy to choose which links an edit should isolate. Practise invariant-preserving operations in Stack Fundamentals, where push and pop must keep the structure valid.