Encapsulation in Python Explained — Access Control, Properties and Real-World Patterns

class BankAccount:
    def __init__(self, owner: str, initial_balance: float):
        # PUBLIC: intended to be read by anyone
        self.owner = owner

        # PROTECTED: internal bookkeeping — subclasses may need it,
        # but outside callers should not rely on it.
        # The single underscore is a social contract, not a lock.
        self._transaction_history = []

        # PRIVATE: name mangling kicks in here.
        # Python renames this to _BankAccount__balance internally.
        # Subclasses cannot accidentally stomp on it.
        self.__balance = initial_balance

    def get_balance(self) -> float:
        """The only sanctioned way to read the balance."""
        return self.__balance

    def deposit(self, amount: float) -> None:
        if amount <= 0:
            raise ValueError("Deposit amount must be positive.")
        self.__balance += amount
        self._transaction_history.append(f"Deposit: +{amount}")


account = BankAccount("Alice", 1000.0)
account.deposit(250.0)

print(account.owner)                    # Public — totally fine
print(account.get_balance())            # Public method — fine
print(account._transaction_history)     # Works, but the underscore means: please do not

# Accessing the private attribute directly:
try:
    print(account.__balance)            # AttributeError — mangled name is different
except AttributeError as error:
    print(f"Direct access blocked: {error}")

# Name mangling in action — the attribute still exists, just renamed:
# This is how you confirm it exists in debugging. Never do this in production.
print(account._BankAccount__balance)

class UserProfile:
    def __init__(self, username: str, age: int):
        self.username = username   # Still public — no validation needed here
        self.age = age             # This calls the setter defined below
                                   # so validation runs at construction too

    @property
    def age(self) -> int:
        """The getter — called whenever you READ user.age"""
        return self.__age          # Returns the private backing field

    @age.setter
    def age(self, value: int) -> None:
        """The setter — called whenever you WRITE user.age = something.

        CRITICAL: we assign to self.__age, NOT self.age.
        Writing self.age = value here would call this setter again
        and cause infinite recursion (RecursionError).
        """
        if not isinstance(value, int):
            raise TypeError(f"Age must be an integer, got {type(value).__name__}.")
        if value < 0 or value > 130:
            raise ValueError(f"Age {value} is outside the valid range (0-130).")
        self.__age = value         # Store in the private backing field

    @age.deleter
    def age(self) -> None:
        """The deleter — called when you do 'del user.age'"""
        raise AttributeError("Deleting age is not allowed — use age = 0 to reset.")

    def __repr__(self) -> str:
        return f"UserProfile(username={self.username!r}, age={self.__age})"


# Normal usage — looks identical to a plain attribute
alice = UserProfile("alice99", 28)
print(alice)                # __repr__ is called

alice.age = 29              # Calls the setter transparently
print(alice.age)            # Calls the getter

# Validation in action
try:
    alice.age = -1
except ValueError as error:
    print(f"Validation caught it: {error}")

try:
    alice.age = "twenty"
except TypeError as error:
    print(f"Type check caught it: {error}")

try:
    del alice.age
except AttributeError as error:
    print(f"Delete blocked: {error}")

import os

class AppConfig:
    """
    Single source of truth for application configuration.
    Validates settings at construction time so the rest of the app
    can trust that any AppConfig instance is always in a valid state.
    """

    # Class-level constant — shared across all instances
    SUPPORTED_ENVIRONMENTS = {"development", "staging", "production"}

    def __init__(self):
        # Private: raw values loaded once at startup
        self.__db_host = self.__require_env("DB_HOST")
        self.__db_port = self.__parse_port(os.environ.get("DB_PORT", "5432"))
        self.__env_name = self.__validate_env(os.environ.get("APP_ENV", "development"))
        self.__debug_mode = os.environ.get("DEBUG", "false").lower() == "true"

    # --- Private helpers: implementation details, not part of the API ---

    @staticmethod
    def __require_env(key: str) -> str:
        """Blows up early with a clear message if a required variable is missing."""
        value = os.environ.get(key)
        if value is None:
            raise EnvironmentError(
                f"Required environment variable '{key}' is not set. "
                f"Check your .env file or deployment config."
            )
        return value

    @staticmethod
    def __parse_port(raw_value: str) -> int:
        """Ensures the port is a valid integer in a usable range."""
        try:
            port = int(raw_value)
        except ValueError:
            raise ValueError(f"DB_PORT must be an integer, got: {raw_value!r}")
        if not (1 <= port <= 65535):
            raise ValueError(f"DB_PORT {port} is outside valid range (1-65535).")
        return port

    @classmethod
    def __validate_env(cls, env_name: str) -> str:
        """Guards against typos in APP_ENV.

        Declared as classmethod because it only needs SUPPORTED_ENVIRONMENTS,
        a class-level constant — no instance data required.
        """
        if env_name not in cls.SUPPORTED_ENVIRONMENTS:
            raise ValueError(
                f"APP_ENV must be one of {cls.SUPPORTED_ENVIRONMENTS}, got: {env_name!r}"
            )
        return env_name

    # --- Public read-only properties: the deliberate API ---

    @property
    def database_url(self) -> str:
        """Computed property — assembles the URL on demand from private parts."""
        return f"postgresql://{self.__db_host}:{self.__db_port}/appdb"

    @property
    def is_production(self) -> bool:
        return self.__env_name == "production"

    @property
    def debug_enabled(self) -> bool:
        return self.__debug_mode

    def __repr__(self) -> str:
        # Safe to log — never exposes raw credentials
        return (
            f"AppConfig(env={self.__env_name!r}, "
            f"db_host={self.__db_host!r}, "
            f"debug={self.__debug_mode})"
        )


# --- Simulating environment variables for the demo ---
os.environ["DB_HOST"] = "db.internal.myapp.com"
os.environ["DB_PORT"] = "5432"
os.environ["APP_ENV"] = "development"
os.environ["DEBUG"] = "true"

config = AppConfig()
print(config)                    # Safe repr — no credentials exposed
print(config.database_url)       # Computed on the fly
print(config.is_production)      # False in development
print(config.debug_enabled)      # True

# The outside world cannot overwrite the database URL — no setter defined
try:
    config.database_url = "postgresql://evil-host:1234/hack"
except AttributeError as error:
    # Python 3.11+: "property 'database_url' of 'AppConfig' object has no setter"
    # Python 3.10 and earlier: "can't set attribute"
    print(f"Read-only enforced: {error}")

class AuditedEntity:
    """
    Base class that tracks how many times any method modifies the object.
    Uses __modification_count so subclasses cannot accidentally collide with it.
    """

    def __init__(self):
        self.__modification_count = 0   # Stored as _AuditedEntity__modification_count

    def _record_modification(self) -> None:
        """Protected helper — subclasses call this after any mutation."""
        self.__modification_count += 1

    def get_audit_count(self) -> int:
        return self.__modification_count


class InventoryItem(AuditedEntity):
    """
    Subclass with its own internal quantity attribute.
    Without name mangling, if it also defined __modification_count,
    it would silently corrupt the base class audit counter.
    Name mangling prevents that collision entirely.
    """

    def __init__(self, product_name: str, quantity: int):
        super().__init__()
        self.product_name = product_name
        self.__quantity = quantity           # Stored as _InventoryItem__quantity

    def restock(self, units: int) -> None:
        if units <= 0:
            raise ValueError("Units to restock must be positive.")
        self.__quantity += units
        self._record_modification()          # Tells the base class: a change happened

    def sell(self, units: int) -> None:
        if units > self.__quantity:
            raise ValueError(f"Cannot sell {units} units; only {self.__quantity} in stock.")
        self.__quantity -= units
        self._record_modification()

    def get_quantity(self) -> int:
        return self.__quantity

    def __repr__(self) -> str:
        return (
            f"InventoryItem(product={self.product_name!r}, "
            f"qty={self.__quantity}, "
            f"modifications={self.get_audit_count()})"
        )


widget = InventoryItem("Widget Pro", 100)
widget.restock(50)    # qty -> 150, audit_count -> 1
widget.sell(30)       # qty -> 120, audit_count -> 2
widget.sell(10)       # qty -> 110, audit_count -> 3

print(widget)
print(f"Audit trail shows {widget.get_audit_count()} modifications.")

# vars() proves both __counts live in completely separate namespaces:
print(vars(widget))

class BankAccount:
    def __init__(self, account_holder: str, initial_balance: float):
        self.holder = account_holder
        self.__balance = initial_balance

    @property
    def balance(self) -> float:
        return self.__balance

    def withdraw(self, amount: float) -> None:
        """
        Tries to withdraw amount. Raises ValueError if insufficient funds.
        The caller does not need to check balance beforehand.
        Validation is here, not scattered across callers.
        """
        if amount <= 0:
            raise ValueError("Withdrawal amount must be positive.")
        if amount > self.__balance:
            raise ValueError(
                f"Insufficient funds. Available: {self.__balance:.2f}, Requested: {amount:.2f}"
            )
        self.__balance -= amount

    def deposit(self, amount: float) -> None:
        if amount <= 0:
            raise ValueError("Deposit amount must be positive.")
        self.__balance += amount


# --- Anti-pattern: asking and then acting (separate account for clarity) ---
bad_account = BankAccount("Bob (anti-pattern demo)", 1000.0)
print(f"Balance before: {bad_account.balance:.2f}")

# The caller checks state and decides — this is the anti-pattern.
# Two problems:
# 1. The business rule (amount <= balance) is now duplicated in every caller.
# 2. In a multithreaded context, another thread could change balance
#    between the check on line N and the withdraw on line N+1 (TOCTOU bug).
if bad_account.balance >= 300:
    bad_account.withdraw(300)
    print("Anti-pattern withdraw succeeded (balance check done by caller).")

# --- Good encapsulation: tell the object what you want (separate account) ---
good_account = BankAccount("Alice (good pattern demo)", 1000.0)

# The object decides if the withdrawal is allowed.
# Business logic lives in one place. Caller handles success or failure.
good_account.withdraw(400)
print(f"Good pattern: withdrew 400. Remaining: {good_account.balance:.2f}")

try:
    good_account.withdraw(800)  # Will fail — object enforces the rule
except ValueError as error:
    print(f"Object enforced its rule: {error}")

import sys

# --- Without __slots__: default dict-based instance storage ---
class ProductWithDict:
    def __init__(self, name: str, price: float):
        self.name = name
        self.__price = price

    @property
    def price(self) -> float:
        return self.__price


# --- With __slots__: fixed attribute slots ---
class ProductWithSlots:
    __slots__ = ('name', '_ProductWithSlots__price')  # slot for property backing field

    def __init__(self, name: str, price: float):
        self.name = name
        self.__price = price  # stored in the slot, not __dict__

    @property
    def price(self) -> float:
        return self.__price


# Memory comparison
dict_product = ProductWithDict("Widget", 9.99)
slot_product = ProductWithSlots("Widget", 9.99)

print(f"With __dict__:  {sys.getsizeof(dict_product.__dict__)} bytes for __dict__ alone")
print(f"With __slots__: no __dict__ — slots live in the class structure")
print(f"Instance size (dict):  {sys.getsizeof(dict_product)} bytes")
print(f"Instance size (slots): {sys.getsizeof(slot_product)} bytes")

# Safety demonstration: __slots__ prevents accidental attribute creation
try:
    slot_product.unexpected_attr = "this should not exist"
except AttributeError as error:
    print(f"\nSlots safety caught it: {error}")

# Properties still work exactly the same way through slots
print(f"\nPrice via property: {slot_product.price}")

# Normal dict-based class allows accidental attributes silently
dict_product.unexpected_attr = "oops — a typo created a new attribute"
print(f"Dict class allows accidental attr: {dict_product.unexpected_attr}")