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 shouldn't rely on it
        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 you're ignoring the warning sign

# Trying to access the private attribute directly:
try:
    print(account.__balance)            # This WILL raise AttributeError
except AttributeError as error:
    print(f"Direct access blocked: {error}")

# Name mangling in action — the attribute still exists, just renamed:
print(account._BankAccount__balance)    # Works, but NEVER do this in real code

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

    @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"""
        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, truly immutable
    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

    def __validate_env(self, env_name: str) -> str:
        """Guards against typos in APP_ENV."""
        if env_name not in self.SUPPORTED_ENVIRONMENTS:
            raise ValueError(
                f"APP_ENV must be one of {self.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
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
try:
    config.database_url = "postgresql://evil-host:1234/hack"
except AttributeError as error:
    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 can't accidentally collide with it.
    """

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

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

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


class InventoryItem(AuditedEntity):
    """
    Subclass that also has a concept it wants to call __modification_count
    (e.g., how many times the quantity has been adjusted for a different report).
    Without name mangling, these would collide and break the base class audit.
    """

    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)    # audit_count -> 1
widget.sell(30)       # audit_count -> 2
widget.sell(10)       # audit_count -> 3

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

# Proving the two __counts live in completely separate namespaces:
print(vars(widget))   # Shows all instance attributes with their mangled names