Phase 2: Pythonic Thinking

from dataclasses import dataclass

@dataclass
class Card:
    suit:  str
    value: int

    def __str__(self) -> str:
        # print(card) → "A♠" not "Card(suit='spades', value=14)"
        symbols = {'spades':'♠', 'hearts':'♥', 'clubs':'♣', 'diamonds':'♦'}
        names   = {11:'J', 12:'Q', 13:'K', 14:'A'}
        face    = names.get(self.value, str(self.value))
        return f"{face}{symbols[self.suit]}"

    def __repr__(self) -> str:
        # repr() is for developers — unambiguous, reproducible
        return f"Card(suit={self.suit!r}, value={self.value})"

    def __lt__(self, other: 'Card') -> bool:
        # Makes cards sortable with sorted() and min()/max()
        return self.value < other.value


class Hand:
    def __init__(self, cards: list[Card] = None):
        self._cards = cards or []

    # len(hand) → number of cards
    def __len__(self) -> int:
        return len(self._cards)

    # card in hand → True/False
    def __contains__(self, card: Card) -> bool:
        return card in self._cards

    # for card in hand: ... → iterate naturally
    def __iter__(self):
        return iter(self._cards)

    # hand[0] → first card
    def __getitem__(self, index: int) -> Card:
        return self._cards[index]

    # print(hand) → readable representation
    def __str__(self) -> str:
        return " | ".join(str(c) for c in self._cards)

    def add(self, card: Card) -> None:
        self._cards.append(card)


# ── Now your class works like a built-in type ──
hand = Hand([
    Card('spades', 14),
    Card('hearts', 7),
    Card('clubs',  11),
])

print(hand)                           # A♠ | 7♥ | J♣
print(len(hand))                       # 3
print(Card('spades', 14) in hand)     # True
print(sorted(hand))                    # sorted by value — works!
print(max(hand))                       # highest card — works!
for card in hand:                      # for loop — works!
    print(card)

class Multiplier:
    """A configured callable — like a function with state."""
    def __init__(self, factor: int):
        self.factor = factor

    def __call__(self, value: int) -> int:
        return value * self.factor

# Create configured callable objects
double = Multiplier(2)
triple = Multiplier(3)

print(double(5))    # 10  — called like a function!
print(triple(7))    # 21

# Can pass them anywhere a function is expected
nums = [1, 2, 3, 4]
print(list(map(double, nums)))  # [2, 4, 6, 8]

# Functions can return other functions
def make_greeter(greeting: str):
    def greet(name: str) -> str:
        return f"{greeting}, {name}!"
    return greet   # return the function itself, not a call

hello = make_greeter("Hello")
yo    = make_greeter("Yo")

print(hello("Jude"))   # "Hello, Jude!"
print(yo("Jude"))      # "Yo, Jude!"
# greet() "closes over" the greeting variable — this is a CLOSURE

# A wrapper adds behavior before/after calling the original
def timer(func):
    import time
    def wrapper(*args, **kwargs):
        start  = time.time()
        result = func(*args, **kwargs)   # call the original
        end    = time.time()
        print(f"{func.__name__} took {end-start:.4f}s")
        return result
    return wrapper

def slow_add(a, b):
    import time; time.sleep(0.1)
    return a + b

# Manually wrap it
slow_add = timer(slow_add)
slow_add(3, 4)
# slow_add took 0.1003s

# @timer is EXACTLY the same as: slow_add = timer(slow_add)
# It's just syntactic sugar — cleaner to read

@timer
def slow_add(a: int, b: int) -> int:
    import time; time.sleep(0.1)
    return a + b

slow_add(3, 4)    # automatically timed, every call

import functools

def timer(func):
    @functools.wraps(func)   # ← ALWAYS add this to your wrappers
    def wrapper(*args, **kwargs):
        import time
        start  = time.time()
        result = func(*args, **kwargs)
        print(f"{func.__name__} took {time.time()-start:.4f}s")
        return result
    return wrapper

# Without @functools.wraps:
# slow_add.__name__ → "wrapper"  ← BAD
# With @functools.wraps:
# slow_add.__name__ → "slow_add" ← CORRECT

import functools, time

# ── 1. Retry decorator — re-runs on failure ──
def retry(times: int = 3, delay: float = 1.0):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    print(f"Attempt {attempt} failed: {e}")
                    if attempt < times:
                        time.sleep(delay)
            raise RuntimeError(f"{func.__name__} failed after {times} attempts")
        return wrapper
    return decorator

@retry(times=3, delay=0.5)
def fetch_data(url: str) -> dict:
    # Automatically retried 3 times on any exception
    import requests
    return requests.get(url).json()

# ── 2. Cache/memoize — remember expensive results ──
from functools import lru_cache

@lru_cache(maxsize=128)   # built into Python stdlib!
def fibonacci(n: int) -> int:
    if n < 2: return n
    return fibonacci(n - 1) + fibonacci(n - 2)
    # Without @lru_cache: fib(40) calls itself ~100 million times
    # With @lru_cache:    fib(40) calls itself 40 times

# ── 3. Validate arguments ──
def require_positive(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        for arg in args:
            if isinstance(arg, (int, float)) and arg <= 0:
                raise ValueError(f"All arguments must be positive, got {arg}")
        return func(*args, **kwargs)
    return wrapper

@require_positive
def calculate_area(width: float, height: float) -> float:
    return width * height

import math

class Circle:
    def __init__(self, radius: float):
        self.radius = radius   # this calls the setter below

    # ── radius: validated read/write ──
    @property
    def radius(self) -> float:
        return self._radius

    @radius.setter
    def radius(self, value: float) -> None:
        if value < 0:
            raise ValueError(f"Radius must be ≥ 0, got {value}")
        self._radius = value

    # ── computed properties — read-only, no setter ──
    @property
    def area(self) -> float:
        # Calculated on demand — not stored
        return math.pi * self._radius ** 2

    @property
    def circumference(self) -> float:
        return 2 * math.pi * self._radius

    @property
    def diameter(self) -> float:
        return self._radius * 2

    def __repr__(self) -> str:
        return f"Circle(radius={self._radius})"


# ── Usage — reads like attribute access, runs like methods ──
c = Circle(5)
print(c.radius)          # 5          — property getter
print(c.area)            # 78.54...   — computed, no ()!
print(c.circumference)   # 31.41...
c.radius = 10           # property setter — validates
print(c.area)            # 314.15...  — automatically updated
c.radius = -1           # ValueError: Radius must be ≥ 0, got -1

import time

class Timer:
    """Context manager that measures elapsed time."""

    def __enter__(self) -> 'Timer':
        # Called when entering the with block
        self.start   = time.perf_counter()
        self.elapsed = 0.0
        return self    # this becomes the 'as' variable

    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
        # Called when leaving the with block (always)
        self.elapsed = time.perf_counter() - self.start
        print(f"Elapsed: {self.elapsed:.4f}s")
        return False   # don't suppress exceptions


# Usage
with Timer() as t:
    time.sleep(0.25)
    print("doing work...")
# Elapsed: 0.2502s  (printed automatically)
print(f"Total was: {t.elapsed:.4f}s")   # accessible after block

from contextlib import contextmanager
import sqlite3

@contextmanager
def database_connection(db_path: str):
    """Manage a SQLite connection — auto-commit or rollback."""
    conn = sqlite3.connect(db_path)
    try:
        yield conn          # ← everything above is __enter__
        conn.commit()         # only reached if no exception
    except Exception:
        conn.rollback()     # roll back on error
        raise               # re-raise the exception
    finally:
        conn.close()        # ← everything in finally is __exit__


# Clean, safe database operations
with database_connection("game.db") as conn:
    conn.execute("INSERT INTO players VALUES (?, ?)", ("Jude", 100))
# auto-committed if success, auto-rolled-back if error, always closed


# Another example — temporarily change directory
import os

@contextmanager
def working_directory(path: str):
    original = os.getcwd()
    try:
        os.chdir(path)
        yield
    finally:
        os.chdir(original)   # ALWAYS restore, even on error

with working_directory("/tmp"):
    print(os.getcwd())   # /tmp
# Back to original directory automatically

# ── 1. Reading large files line by line ──
def read_large_file(filepath: str):
    """Read a file one line at a time — no matter how big it is."""
    with open(filepath) as f:
        for line in f:
            yield line.strip()

# Process a 10GB log file with constant memory:
for line in read_large_file("huge.log"):
    if "ERROR" in line:
        print(line)


# ── 2. Infinite sequence ──
def counter(start: int = 0):
    """Count forever — only compute what you ask for."""
    n = start
    while True:
        yield n
        n += 1

from itertools import islice
first_10 = list(islice(counter(5), 10))
# [5, 6, 7, 8, 9, 10, 11, 12, 13, 14]


# ── 3. Generator expression (like list comprehension, but lazy) ──
# List comprehension — builds all results NOW
squares_list = [x**2 for x in range(1_000_000)]   # uses ~8MB

# Generator expression — computes on demand
squares_gen  = (x**2 for x in range(1_000_000))   # uses ~200 bytes!
# Note: parentheses instead of brackets

# Both work identically in a for loop or sum()
total = sum(x**2 for x in range(1_000_000))  # no brackets needed inside ()


# ── 4. Pipeline — chain generators together ──
def parse_logs(lines):
    for line in lines:
        yield line.split(" | ")

def filter_errors(records):
    for record in records:
        if len(record) > 1 and record[0] == "ERROR":
            yield record

# Each stage only processes one item at a time — memory stays flat
lines   = read_large_file("app.log")
records = parse_logs(lines)
errors  = filter_errors(records)
for err in errors:
    print(err)

from itertools import (
    chain, islice, groupby, product,
    combinations, permutations,
    takewhile, dropwhile, cycle, repeat
)

# ── chain — flatten multiple iterables into one ──
a = [1, 2, 3]
b = [4, 5, 6]
c = [7, 8, 9]
list(chain(a, b, c))
# [1, 2, 3, 4, 5, 6, 7, 8, 9]

# ── islice — take first N items from any iterable ──
list(islice(range(1000), 5))
# [0, 1, 2, 3, 4]

# ── groupby — group consecutive items by a key ──
# IMPORTANT: input must be sorted by the key first!
data = [
    {"name": "Alice", "dept": "eng"},
    {"name": "Bob",   "dept": "eng"},
    {"name": "Carol", "dept": "hr"},
    {"name": "Dave",  "dept": "hr"},
]
data.sort(key=lambda x: x["dept"])
for dept, members in groupby(data, key=lambda x: x["dept"]):
    names = [m["name"] for m in members]
    print(f"{dept}: {names}")
# eng: ['Alice', 'Bob']
# hr:  ['Carol', 'Dave']

# ── product — cartesian product (nested loops collapsed) ──
colors = ["red", "blue"]
sizes  = ["S", "M", "L"]
list(product(colors, sizes))
# [('red','S'), ('red','M'), ('red','L'), ('blue','S'), ...]

# ── combinations — all unique pairs ──
players = ["Alice", "Bob", "Carol", "Dave"]
list(combinations(players, 2))
# All possible 2-player matchups — 6 pairs

# ── takewhile / dropwhile — conditional slicing ──
data = [2, 4, 6, 7, 8, 10]
list(takewhile(lambda x: x % 2 == 0, data))  # [2, 4, 6]  — stops at 7
list(dropwhile(lambda x: x % 2 == 0, data))  # [7, 8, 10] — skips until 7

# ── cycle — repeat an iterable forever ──
colors_cycle = cycle(["red", "green", "blue"])
list(islice(colors_cycle, 7))
# ['red', 'green', 'blue', 'red', 'green', 'blue', 'red']

BaseException
├── SystemExit           # sys.exit() — don't catch this
├── KeyboardInterrupt    # Ctrl+C — don't catch this either
└── Exception            # catch this or its children
    ├── ValueError       # wrong value type/range
    ├── TypeError        # wrong type entirely
    ├── KeyError         # dict key not found
    ├── IndexError       # list index out of range
    ├── AttributeError   # attribute doesn't exist on object
    ├── FileNotFoundError# subclass of OSError
    ├── PermissionError  # subclass of OSError
    ├── RuntimeError     # generic runtime error
    └── StopIteration    # iterator exhausted (don't catch)

def load_config(path: str) -> dict:
    try:
        with open(path) as f:
            data = json.load(f)

    except FileNotFoundError:
        # Specific — file doesn't exist
        print(f"Config not found: {path}. Using defaults.")
        return {}

    except json.JSONDecodeError as e:
        # Specific — file exists but isn't valid JSON
        raise ValueError(f"Config file corrupt: {path}") from e
        # ↑ "from e" attaches the original exception — keeps context

    except PermissionError:
        # Can't recover — re-raise with more info
        raise PermissionError(f"Cannot read config: {path}")

    else:
        # Runs ONLY if no exception was raised — often overlooked!
        print(f"Config loaded: {len(data)} keys")
        return data

    finally:
        # Runs ALWAYS — with or without exception
        print("load_config complete")


# ── What NOT to do ──────────────────────────────────
# NEVER do this — hides ALL errors including bugs
try:
    do_something()
except:            # bare except catches EVERYTHING, even SystemExit
    pass

# NEVER do this — too broad
try:
    do_something()
except Exception:  # hides bugs disguised as "errors"
    print("something went wrong")  # no info, no re-raise

# Define a hierarchy for your app
class AppError(Exception):
    """Base exception for all app errors."""
    pass

class ValidationError(AppError):
    """Raised when input data fails validation."""
    def __init__(self, field: str, message: str):
        self.field   = field
        self.message = message
        super().__init__(f"Validation failed for '{field}': {message}")

class NotFoundError(AppError):
    """Raised when a requested resource doesn't exist."""
    def __init__(self, resource: str, identifier):
        self.resource   = resource
        self.identifier = identifier
        super().__init__(f"{resource} '{identifier}' not found")


# ── Usage ──
def get_player(player_id: int) -> dict:
    if not isinstance(player_id, int) or player_id <= 0:
        raise ValidationError("player_id", "must be a positive integer")
    player = db.find(player_id)
    if not player:
        raise NotFoundError("Player", player_id)
    return player

# ── Callers can be very specific ──
try:
    player = get_player(42)
except ValidationError as e:
    print(f"Bad input: {e.field}")
except NotFoundError as e:
    print(f"Missing: {e.resource} {e.identifier}")
except AppError as e:
    print(f"App error: {e}")   # catches all app errors

from typing import (
    Optional, Union, Any, TypeVar,
    Callable, Sequence, Mapping,
    TypedDict, Protocol, Literal, Final
)

# ── Optional — value or None (very common) ──
def find_user(user_id: int) -> Optional[dict]:
    # Python 3.10+ cleaner syntax: dict | None
    return db.get(user_id)   # might be None

# ── Union — one of several types ──
def parse_id(raw: Union[str, int]) -> int:
    # Python 3.10+: str | int
    return int(raw)

# ── Callable — a function type ──
def apply(
    func: Callable[[int, int], int],   # takes 2 ints, returns int
    a: int, b: int
) -> int:
    return func(a, b)

# ── TypeVar — generic functions ──
T = TypeVar('T')

def first(items: list[T]) -> T:
    # Return type is same T as element type
    return items[0]

first([1, 2, 3])         # inferred: int
first(["a", "b"])       # inferred: str

# ── TypedDict — dict with a known shape ──
class PlayerData(TypedDict):
    name:    str
    hp:      int
    level:   int
    alive:   bool

def display_player(p: PlayerData) -> None:
    # mypy knows p["name"] is a str, p["hp"] is an int
    print(f"{p['name']} — {p['hp']} HP")

# ── Literal — only specific values allowed ──
Direction = Literal["north", "south", "east", "west"]

def move(direction: Direction) -> None:
    print(f"Moving {direction}")

move("north")   # ✅ valid
move("up")      # mypy error: not a valid Direction

# ── Protocol — structural subtyping ("duck typing with types") ──
class Drawable(Protocol):
    def draw(self) -> None: ...

def render_all(objects: list[Drawable]) -> None:
    for obj in objects:
        obj.draw()

# Any class with a draw() method satisfies Drawable
# — no explicit inheritance needed. True duck typing + types.

from dataclasses import dataclass, field, asdict, astuple
from typing import ClassVar
import datetime

@dataclass
class Task:
    # Required fields (no default) must come before optional ones
    title:    str
    priority: int

    # Optional fields with defaults
    done:     bool    = False
    tags:     list[str] = field(default_factory=list)
    # ↑ NEVER use default=[] — mutable defaults are shared!
    #   default_factory creates a NEW list for each instance

    # Auto-set field — not in __init__ signature
    created:  str    = field(
        default_factory=lambda: datetime.datetime.now().isoformat(),
        init=False    # excluded from constructor
    )

    # Class variable (shared, not per-instance)
    MAX_PRIORITY: ClassVar[int] = 5

    # You can still add methods normally
    def complete(self) -> None:
        self.done = True

    # __post_init__ — runs after the generated __init__
    def __post_init__(self) -> None:
        if not 1 <= self.priority <= self.MAX_PRIORITY:
            raise ValueError(
                f"Priority must be 1–{self.MAX_PRIORITY}, got {self.priority}"
            )
        self.title = self.title.strip()   # clean up input


# ── Frozen dataclass — immutable (like Java record) ──
@dataclass(frozen=True)
class Point:
    x: float
    y: float
    # frozen=True: auto-generates __hash__, prevents mutation
    # Can be used in sets and as dict keys

p = Point(3.0, 4.0)
print(asdict(p))      # {'x': 3.0, 'y': 4.0} — to dict, free!
# p.x = 5  ← FrozenInstanceError — immutable


# ── Ordered dataclass — sortable ──
@dataclass(order=True)
class Score:
    value:      int
    player_name: str

scores = [Score(85, "Jude"), Score(92, "Ana"), Score(78, "Max")]
print(sorted(scores))  # sorted by value, then name — free!

from __future__  import annotations
from dataclasses import dataclass, field, asdict
from contextlib  import contextmanager
from typing      import Iterator, Literal, Optional
from pathlib     import Path
import json, datetime, functools, logging

logging.basicConfig(level=logging.INFO,
                    format="%(levelname)s %(message)s")
log = logging.getLogger(__name__)


# ─── Custom Exceptions ───────────────────────────
class TaskError(Exception): pass
class TaskNotFoundError(TaskError):
    def __init__(self, task_id: str):
        super().__init__(f"Task not found: {task_id!r}")
class ValidationError(TaskError):
    def __init__(self, field_name: str, msg: str):
        super().__init__(f"{field_name}: {msg}")


# ─── Logging decorator ──────────────────────────
def log_mutation(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        log.info(f"{func.__name__} called")
        return result
    return wrapper


# ─── Priority type ───────────────────────────────
Priority = Literal[1, 2, 3, 4, 5]
PRIORITY_LABELS = {1:"low", 2:"normal", 3:"high", 4:"urgent", 5:"critical"}


# ─── Task dataclass ──────────────────────────────
@dataclass(order=True)
class Task:
    title:    str
    _priority: int          = field(default=2, repr=False)
    done:     bool           = field(default=False, compare=False)
    tags:     list[str]      = field(default_factory=list, compare=False)
    due:      Optional[str]  = field(default=None, compare=False)
    created:  str            = field(
        default_factory=lambda: datetime.date.today().isoformat(),
        init=False, compare=False
    )

    def __post_init__(self) -> None:
        if not self.title.strip():
            raise ValidationError("title", "cannot be blank")
        self.title = self.title.strip()

    @property
    def priority(self) -> int:
        return self._priority

    @priority.setter
    def priority(self, value: int) -> None:
        if not 1 <= value <= 5:
            raise ValidationError("priority", "must be 1–5")
        self._priority = value

    @property
    def is_overdue(self) -> bool:
        if not self.due: return False
        return datetime.date.fromisoformat(self.due) < datetime.date.today()

    def __str__(self) -> str:
        status  = "✓" if self.done else ("!" if self.is_overdue else "○")
        plabel  = PRIORITY_LABELS[self._priority]
        due_str = f" due:{self.due}" if self.due else ""
        return f"[{status}] {self.title} [{plabel}]{due_str}"


# ─── Context manager for file I/O ────────────────
@contextmanager
def task_store(path: Path) -> Iterator[list[Task]]:
    tasks: list[Task] = []
    if path.exists():
        raw = json.loads(path.read_text())
        tasks = [Task(**r) for r in raw]
    try:
        yield tasks
    finally:
        path.write_text(json.dumps([asdict(t) for t in tasks], indent=2))


# ─── TaskManager ─────────────────────────────────
class TaskManager:
    def __init__(self, path: str = "tasks.json"):
        self._path  = Path(path)
        self._tasks: list[Task] = self._load()

    def _load(self) -> list[Task]:
        if not self._path.exists(): return []
        return [Task(**r) for r in json.loads(self._path.read_text())]

    def _save(self) -> None:
        self._path.write_text(
            json.dumps([asdict(t) for t in self._tasks], indent=2))

    @log_mutation
    def add(self, title: str, priority: int = 2,
            tags: list[str] = None, due: Optional[str] = None) -> Task:
        task = Task(title=title, _priority=priority,
                    tags=tags or [], due=due)
        self._tasks.append(task)
        self._save()
        return task

    def pending(self) -> Iterator[Task]:
        """Generator — yields pending tasks by priority (highest first)."""
        for task in sorted(self._tasks, reverse=True):
            if not task.done:
                yield task

    def overdue(self) -> Iterator[Task]:
        """Generator — yields only overdue pending tasks."""
        return (t for t in self.pending() if t.is_overdue)

    def __len__(self) -> int:      return len(self._tasks)
    def __iter__(self):             return iter(self._tasks)
    def __repr__(self) -> str:      return f"TaskManager({len(self)} tasks)"


if __name__ == "__main__":
    mgr = TaskManager()
    mgr.add("Learn Phase 3 — The Ecosystem", priority=5)
    mgr.add("Ship Death Road prototype",     priority=4, due="2026-07-01")
    mgr.add("Read The Pragmatic Programmer",  priority=2)
    print(f"\n{mgr}\n")
    for task in mgr.pending():
        print(task)