Classes, Objects & State¶

from dataclasses import dataclass
from datetime import datetime

class BankAccount:
    bank_name    = "PyBank"              # class attribute: shared by all instances
    _interest    = 0.025                 # class attribute: convention = internal

    def __init__(self, owner: str, initial_balance: float = 0.0):
        self.owner     = owner           # instance attribute
        self._balance  = initial_balance # _ = "internal, not public API"
        self._history: list[dict] = []

    # ── Instance methods ──────────────────────────────────────────────────────
    def deposit(self, amount: float) -> None:
        if amount <= 0:
            raise ValueError(f"Deposit amount must be positive, got {amount}")
        self._balance += amount
        self._history.append({"type": "deposit", "amount": amount,
                               "ts": datetime.utcnow().isoformat()})

    def withdraw(self, amount: float) -> None:
        if amount <= 0:
            raise ValueError("Withdrawal must be positive")
        if amount > self._balance:
            raise ValueError(f"Insufficient funds: {self._balance:.2f} < {amount:.2f}")
        self._balance -= amount
        self._history.append({"type": "withdraw", "amount": amount,
                               "ts": datetime.utcnow().isoformat()})

    # ── Property: controlled read access ─────────────────────────────────────
    @property
    def balance(self) -> float:
        return round(self._balance, 2)

    @property
    def transaction_count(self) -> int:
        return len(self._history)

    # ── Class method: alternative constructor ────────────────────────────────
    @classmethod
    def from_dict(cls, data: dict) -> "BankAccount":
        """Create an account from a serialized dict (e.g., from a database row)."""
        account = cls(data["owner"], data.get("balance", 0.0))
        return account

    # ── Static method: utility with logical coupling to this class ────────────
    @staticmethod
    def validate_amount(amount) -> bool:
        """Returns True if amount is a valid positive number."""
        return isinstance(amount, (int, float)) and amount > 0

    def __repr__(self) -> str:
        return f"BankAccount(owner={self.owner!r}, balance={self.balance})"

# Usage
acc = BankAccount("Ada", 500.0)
acc.deposit(250)
acc.withdraw(100)
print(acc.balance)         # 650.0
print(acc)                 # BankAccount(owner='Ada', balance=650.0)

# Alternative constructor
acc2 = BankAccount.from_dict({"owner": "Bob", "balance": 200.0})

# Class attribute access
print(BankAccount.bank_name)    # "PyBank"
print(acc.bank_name)            # "PyBank"  — instances inherit class attrs

# Class attribute mutation trap
class Config:
    flags = []   # SHARED — dangerous if you append to it

c1 = Config()
c2 = Config()
c1.flags.append("debug")    # mutates the SHARED class attribute
c2.flags                    # ["debug"]  — c2 is affected!

# CORRECT: create per-instance in __init__
class Config:
    def __init__(self):
        self.flags = []      # each instance gets its own list

c1 = Config(); c2 = Config()
c1.flags.append("debug")
c2.flags                    # []  — unaffected

# Reading vs assigning class attributes through instances
class Counter:
    count = 0               # class attribute

c = Counter()
Counter.count += 1          # modifies the class attribute — all see it
c.count                     # 1

c.count = 99                # creates an INSTANCE attribute, shadowing the class one
Counter.count               # 1  — class attribute unchanged
c.count                     # 99 — instance attribute hides it

class Temperature:
    def __init__(self, celsius: float):
        self.celsius = celsius   # triggers the setter below if defined

    @property
    def celsius(self) -> float:
        return self._celsius

    @celsius.setter
    def celsius(self, value: float) -> None:
        if value < -273.15:
            raise ValueError(f"Temperature below absolute zero: {value}")
        self._celsius = float(value)

    @celsius.deleter
    def celsius(self) -> None:
        raise AttributeError("Temperature cannot be deleted")

    @property
    def fahrenheit(self) -> float:
        """Read-only computed property — no setter."""
        return self._celsius * 9/5 + 32

    @property
    def kelvin(self) -> float:
        return self._celsius + 273.15

t = Temperature(100)
t.fahrenheit      # 212.0   — computed, no stored state
t.kelvin          # 373.15

t.celsius = -10   # triggers setter, validates
t.celsius = -300  # ValueError: Temperature below absolute zero

# Property as a refactor safety net:
# Start with plain attribute: self.radius = r
# Later add validation: @property + setter
# ALL callers that wrote obj.radius += 1 continue to work unchanged

import json
from datetime import date

class Report:
    default_format = "pdf"

    def __init__(self, title: str, data: list, fmt: str = None):
        self.title  = title
        self.data   = data
        self.format = fmt or self.__class__.default_format

    # Instance method: works on self
    def render(self) -> str:
        return f"[{self.format.upper()}] {self.title}: {len(self.data)} rows"

    # @classmethod: alternative constructors — the most common use case
    @classmethod
    def from_json(cls, json_str: str) -> "Report":
        """Deserialize from JSON — uses cls so subclasses work correctly."""
        payload = json.loads(json_str)
        return cls(payload["title"], payload["data"],
                   payload.get("format", cls.default_format))

    @classmethod
    def daily_template(cls) -> "Report":
        """Factory for today's daily report template."""
        return cls(f"Daily Report {date.today()}", [])

    # @staticmethod: pure utility with no class/instance access needed
    @staticmethod
    def sanitize_title(title: str) -> str:
        """Remove special characters from a report title."""
        return "".join(c for c in title if c.isalnum() or c in " _-")

# Usage
r1 = Report("Sales Q2", [1, 2, 3])
r2 = Report.from_json('{"title": "Marketing", "data": [], "format": "html"}')
r3 = Report.daily_template()
safe = Report.sanitize_title("Q2 Report! (Final)")   # "Q2 Report Final"