Python Classes and Objects Explained — OOP Patterns That Actually Make Sense

class BankAccount:
    # Class attribute — shared across ALL instances of BankAccount
    interest_rate = 0.03

    def __init__(self, owner_name: str, opening_balance: float = 0.0):
        # Instance attributes — unique to each BankAccount object
        self.owner_name = owner_name
        self.balance = opening_balance
        self._transaction_history = []  # Underscore signals 'treat this as private'

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

    def withdraw(self, amount: float) -> None:
        if amount > self.balance:
            raise ValueError("Insufficient funds")
        self.balance -= amount
        self._transaction_history.append(f"Withdrew £{amount:.2f}")

    def apply_interest(self) -> None:
        # Accessing the class attribute via self — works, but be aware of the lookup order
        earned = self.balance * BankAccount.interest_rate
        self.balance += earned
        self._transaction_history.append(f"Interest applied: £{earned:.2f}")

    def get_statement(self) -> str:
        lines = [f"Account owner: {self.owner_name}",
                 f"Balance: £{self.balance:.2f}",
                 "Transactions:"]
        lines.extend(f"  - {entry}" for entry in self._transaction_history)
        return "\n".join(lines)


# Creating two INDEPENDENT objects from the same class
alices_account = BankAccount(owner_name="Alice", opening_balance=500.0)
bobs_account = BankAccount(owner_name="Bob", opening_balance=100.0)

alices_account.deposit(250.0)
alices_account.apply_interest()
bobs_account.deposit(50.0)
bobs_account.withdraw(30.0)

print(alices_account.get_statement())
print()
print(bobs_account.get_statement())

# Prove they are independent — changing Bob's balance doesn't touch Alice's
print(f"\nAre they the same object? {alices_account is bobs_account}")

class Product:
    # Class attribute tracking how many Product objects exist
    _product_count = 0
    TAX_RATE = 0.20  # 20% VAT — a constant belonging to the Product concept

    def __init__(self, name: str, price_ex_tax: float, category: str):
        self.name = name
        self.price_ex_tax = price_ex_tax
        self.category = category
        Product._product_count += 1  # Increment shared counter on every new instance

    # --- INSTANCE METHOD: needs to read this specific product's price ---
    def price_inc_tax(self) -> float:
        return self.price_ex_tax * (1 + Product.TAX_RATE)

    def describe(self) -> str:
        return (f"{self.name} ({self.category}) — "
                f"£{self.price_ex_tax:.2f} ex VAT / "
                f"£{self.price_inc_tax():.2f} inc VAT")

    # --- CLASS METHOD: alternative constructor — build from a CSV string ---
    @classmethod
    def from_csv_row(cls, csv_string: str) -> "Product":
        # csv_string format: "name,price,category"
        name, price, category = csv_string.strip().split(",")
        return cls(name=name, price_ex_tax=float(price), category=category)

    # --- CLASS METHOD: factory that accesses shared class state ---
    @classmethod
    def total_products_created(cls) -> int:
        return cls._product_count

    # --- STATIC METHOD: pure utility — belongs here logically but needs no state ---
    @staticmethod
    def is_valid_price(price: float) -> bool:
        # A price check doesn't need any Product instance or class data
        return isinstance(price, (int, float)) and price >= 0


# Standard construction
headphones = Product(name="Wireless Headphones", price_ex_tax=79.99, category="Electronics")

# Alternative construction via class method — clean API, no manual parsing by the caller
shirt = Product.from_csv_row("Cotton Shirt,24.99,Clothing")
novel = Product.from_csv_row("The Midnight Library,8.99,Books")

print(headphones.describe())
print(shirt.describe())
print(novel.describe())

print(f"\nTotal products created: {Product.total_products_created()}")

# Static method — call on the class, no instance needed
print(f"\nIs -5.00 a valid price? {Product.is_valid_price(-5.00)}")
print(f"Is 19.99 a valid price? {Product.is_valid_price(19.99)}")

class Employee:
    def __init__(self, full_name: str, salary: float, department: str):
        self.full_name = full_name
        self.department = department
        self._salary = None          # Will be set via the property setter below
        self.salary = salary         # Triggers the @salary.setter validation immediately

    # @property turns this method into a readable attribute: employee.salary
    @property
    def salary(self) -> float:
        return self._salary

    # @salary.setter is called when someone writes: employee.salary = 50000
    @salary.setter
    def salary(self, new_salary: float) -> None:
        if not isinstance(new_salary, (int, float)):
            raise TypeError(f"Salary must be numeric, got {type(new_salary).__name__}")
        if new_salary < 0:
            raise ValueError(f"Salary cannot be negative: {new_salary}")
        self._salary = float(new_salary)

    # A computed property — no setter needed, this is read-only
    @property
    def annual_bonus(self) -> float:
        # Senior staff (salary > 60k) get 15%, everyone else gets 8%
        rate = 0.15 if self._salary > 60_000 else 0.08
        return round(self._salary * rate, 2)

    @property
    def display_name(self) -> str:
        # Derive first name from full name — computed on demand, not stored
        return self.full_name.split()[0]

    def __repr__(self) -> str:
        # __repr__ is for developers — shown in the REPL, logs, and debugging
        return (f"Employee(full_name={self.full_name!r}, "
                f"salary={self._salary}, department={self.department!r})")

    def __str__(self) -> str:
        # __str__ is for end users — shown by print()
        return (f"{self.display_name} | {self.department} | "
                f"£{self._salary:,.2f} salary | £{self.annual_bonus:,.2f} bonus")


# Property setter validates on creation — no separate validate() call needed
junior_dev = Employee(full_name="Maria Santos", salary=45_000, department="Engineering")
senior_dev = Employee(full_name="James Okafor", salary=85_000, department="Engineering")

print(junior_dev)
print(senior_dev)

# Property setter validates on update too
junior_dev.salary = 52_000  # Promotion — triggers setter validation
print(f"\nAfter promotion: {junior_dev}")

# This is blocked by our setter
try:
    junior_dev.salary = -1000
except ValueError as e:
    print(f"\nCaught invalid salary update: {e}")

# repr() is what you see in a REPL or when printing a list of objects
print(f"\nrepr: {repr(junior_dev)}")