# Creating a tuple — parentheses (or even just commas)
point = (3, 4)               # x=3, y=4
rgb_red = (255, 0, 0)        # red colour in RGB
single = (42,)               # single-item tuple MUST have a trailing comma!
also_tuple = 1, 2, 3         # parentheses are optional — commas create tuples

# Accessing items — same as lists, by index
print(point[0])   # 3 — x coordinate
print(point[1])   # 4 — y coordinate

# UNPACKING — pulling items out into separate variables
x, y = point     # x=3, y=4
r, g, b = rgb_red  # r=255, g=0, b=0

# Tuples cannot be changed (this would cause a TypeError)
# point[0] = 10  # TypeError: 'tuple' object does not support item assignment

# ─── WHY USE TUPLES INSTEAD OF LISTS? ──────────────────────────
# 1. They signal "this data should not change" — good for code clarity
# 2. They are slightly faster than lists
# 3. They can be used as dictionary keys (lists cannot!)
# 4. Functions often return multiple values as a tuple

def min_max(numbers):
    """Return the minimum and maximum of a list."""
    return min(numbers), max(numbers)    # Python returns a tuple

low, high = min_max([3, 1, 4, 1, 5])
print(f"Min: {low}, Max: {high}")  # Min: 1, Max: 5

# ─── NAMED TUPLES — tuples with labels ──────────────────────────
from collections import namedtuple

# Create a "template" called Color with fields r, g, b
Color = namedtuple("Color", ["r", "g", "b"])
red = Color(255, 0, 0)
print(red.r)      # 255 — access by name (much clearer than red[0])
print(red.g)      # 0
print(red)        # Color(r=255, g=0, b=0)

# Creating a dictionary
user = {
    "name": "Alice",     # "name" is the key, "Alice" is the value
    "age": 30,           # "age" is the key, 30 is the value
    "email": "alice@example.com"
}

# ─── READING VALUES ─────────────────────────────────────────────
print(user["name"])           # "Alice" — access by key
# user["phone"]               # KeyError! "phone" doesn't exist

# .get() is SAFER — returns None (or a default) if key doesn't exist
print(user.get("phone"))           # None — no error, just None
print(user.get("phone", "N/A"))    # "N/A" — custom default value

# ─── ADDING / UPDATING VALUES ──────────────────────────────────
user["city"] = "New York"     # add a new key-value pair
user["age"]  = 31             # update an existing value (age was 30, now 31)
user.update({"age": 32, "country": "USA"})  # update multiple at once

# ─── REMOVING VALUES ───────────────────────────────────────────
del user["city"]              # remove key "city" and its value
removed = user.pop("country", None)  # remove and return value; None if not found

# ─── ITERATING (LOOPING) ───────────────────────────────────────
for key in user:              # loop over all keys
    print(key)                # prints: name, age, email

for value in user.values():   # loop over all values
    print(value)

for key, value in user.items():  # loop over key-value pairs
    print(f"{key} = {value}")    # name = Alice, age = 32, etc.

# ─── CHECKING EXISTENCE ─────────────────────────────────────────
print("name" in user)      # True — does key "name" exist?
print("phone" in user)     # False — no "phone" key

# ─── DICT COMPREHENSION ─────────────────────────────────────────
# Create a dict of numbers and their squares
squares = {x: x**2 for x in range(6)}
# {0:0, 1:1, 2:4, 3:9, 4:16, 5:25}

# ─── defaultdict — no KeyError when accessing missing keys ──────
from collections import defaultdict
word_count = defaultdict(int)  # missing keys default to 0
for word in ["apple", "banana", "apple", "cherry", "apple"]:
    word_count[word] += 1      # no KeyError even on first access!
# {"apple": 3, "banana": 1, "cherry": 1}

# ─── Merging two dicts (Python 3.9+) ────────────────────────────
defaults = {"timeout": 30, "retries": 3}
custom   = {"host": "localhost", "retries": 5}
merged   = {**defaults, **custom}   # custom values override defaults
# OR in Python 3.9+:
merged   = defaults | custom        # same result, cleaner syntax

# Creating a set — curly braces (but no key:value pairs — that would be a dict!)
fruits = {"apple", "banana", "cherry", "apple"}  # "apple" appears twice
print(fruits)   # {"apple", "banana", "cherry"} — only ONE apple!
# Note: the order may differ each time you run it — sets are UNORDERED

# Creating a set from a list (great for removing duplicates)
numbers = [1, 2, 2, 3, 3, 3, 4, 4, 4, 4]
unique = set(numbers)       # {1, 2, 3, 4}
unique_list = list(unique)  # convert back to list if needed

# ─── ADDING AND REMOVING ─────────────────────────────────────────
fruits.add("grape")          # add one item
fruits.remove("banana")      # remove item (raises error if not there)
fruits.discard("mango")      # remove if present (NO error if not there)

# ─── MEMBERSHIP TEST — the main reason to use sets ─────────────
# This is O(1) — super fast even with millions of items
print("apple" in fruits)     # True
print("mango" in fruits)     # False

# Compare: checking in a LIST is O(n) — it checks every item one by one
# Checking in a SET is O(1) — instant, uses a hash lookup

# ─── SET OPERATIONS (like in maths) ─────────────────────────────
a = {1, 2, 3, 4}
b = {3, 4, 5, 6}

print(a | b)   # UNION: {1,2,3,4,5,6} — everything in either set
print(a & b)   # INTERSECTION: {3,4} — only what's in BOTH sets
print(a - b)   # DIFFERENCE: {1,2} — in 'a' but NOT in 'b'
print(a ^ b)   # SYMMETRIC DIFFERENCE: {1,2,5,6} — in one but not both

# ─── frozenset — an immutable set ───────────────────────────────
fs = frozenset({1, 2, 3})  # cannot add or remove items
# Can be used as a dict key (regular sets cannot)

# Basic unpacking — number of variables must match number of items
point = (10, 20)
x, y = point           # x=10, y=20

rgb = (255, 128, 0)
red, green, blue = rgb # red=255, green=128, blue=0

# ─── STARRED EXPRESSIONS — grab the "rest" ──────────────────────
# The * before a variable name means "put everything else in here"
numbers = [1, 2, 3, 4, 5]
first, second, *rest = numbers
# first=1, second=2, rest=[3, 4, 5]

first, *middle, last = [1, 2, 3, 4, 5]
# first=1, middle=[2, 3, 4], last=5

# ─── SWAP WITHOUT A TEMP VARIABLE ───────────────────────────────
# In many languages, swapping requires a temporary variable:
# temp = a; a = b; b = temp

# In Python, you can do it in one line:
a, b = 10, 20
a, b = b, a    # now a=20, b=10  — elegant!

# ─── UNPACKING IN LOOPS ─────────────────────────────────────────
# Very common pattern — unpacking tuples while looping
pairs = [(1, "one"), (2, "two"), (3, "three")]
for number, word in pairs:    # unpack each tuple automatically
    print(f"{number} = {word}")

# ─── DICT UNPACKING WITH ** ─────────────────────────────────────
defaults = {"timeout": 30, "retries": 3}
# The ** operator "spreads" a dict into key=value pairs
config = {"host": "localhost", **defaults, "retries": 5}
# The later "retries": 5 overrides defaults' "retries": 3
# Result: {"host": "localhost", "timeout": 30, "retries": 5}

# ─── LIST UNPACKING WITH * ──────────────────────────────────────
def add(a, b, c):
    return a + b + c

nums = [1, 2, 3]
result = add(*nums)   # same as add(1, 2, 3) — * unpacks the list into args

# ─── FOR LOOP — repeat for each item in a collection ────────────
fruits = ["apple", "banana", "cherry"]
for fruit in fruits:       # fruit takes each value in turn
    print(fruit)           # prints apple, then banana, then cherry

# ─── RANGE — loop a specific number of times ───────────────────
for i in range(5):         # i goes 0, 1, 2, 3, 4
    print(i)               # prints 0 to 4

# range(start, stop, step) — start included, stop NOT included
for i in range(1, 11):     # 1 to 10 (not 11)
    print(i)

for i in range(0, 20, 2):  # every 2nd number: 0, 2, 4, 6, ... 18
    print(i)

# ─── ENUMERATE — loop with automatic index numbering ────────────
# enumerate() gives you BOTH the index AND the value at each step
for index, fruit in enumerate(fruits):
    print(f"{index}: {fruit}")
# 0: apple
# 1: banana
# 2: cherry

# Start counting from 1 instead of 0
for index, fruit in enumerate(fruits, start=1):
    print(f"{index}. {fruit}")
# 1. apple   2. banana   3. cherry

# ─── ZIP — loop over two lists in parallel ──────────────────────
names  = ["Alice", "Bob", "Charlie"]
scores = [90, 85, 78]
for name, score in zip(names, scores):   # pairs them up: (Alice,90), (Bob,85)...
    print(f"{name} scored {score}")

# ─── WHILE LOOP — repeat while a condition is True ──────────────
count = 0
while count < 5:           # keep looping as long as count < 5
    print(count)
    count += 1             # IMPORTANT: must change count or loop runs forever!

# ─── BREAK — exit the loop early ────────────────────────────────
for number in range(100):
    if number == 10:
        break              # stop looping immediately when number reaches 10
    print(number)          # prints 0 to 9

# ─── CONTINUE — skip the rest of this iteration ─────────────────
for number in range(10):
    if number % 2 == 0:    # if number is even...
        continue           # ...skip the rest of this loop body and go to next
    print(number)          # prints only odd numbers: 1, 3, 5, 7, 9

# ─── FOR-ELSE — a Python-specific feature ───────────────────────
# The 'else' block runs ONLY if the loop completed WITHOUT a break
for number in [2, 4, 6, 8]:
    if number % 3 == 0:
        print(f"Found divisible by 3: {number}")
        break
else:
    print("No number divisible by 3 was found")  # this runs here

# Match on exact values — like a cleaner if/elif chain
status_code = 404

match status_code:
    case 200:
        print("OK — Success")
    case 404:
        print("Not Found")      # this runs
    case 500:
        print("Server Error")
    case _:                     # _ is the "wildcard" — matches anything
        print("Unknown status")

# ─── MATCH ON DICTIONARY STRUCTURE ─────────────────────────────
command = {"action": "move", "direction": "north"}

match command:
    case {"action": "move", "direction": d}:
        # 'd' is automatically filled with the value from the dict
        print(f"Moving {d}")         # "Moving north"
    case {"action": "attack", "weapon": w}:
        print(f"Attacking with {w}")
    case _:
        print("Unknown command")

# ─── MATCH ON TYPES ─────────────────────────────────────────────
def describe(value):
    match value:
        case int(n) if n > 0:       # matches positive integers
            return f"positive int: {n}"
        case int(n):                # matches any other integer
            return f"int: {n}"
        case str(s):                # matches any string
            return f"string of length {len(s)}"
        case [x, y]:                # matches a list with exactly 2 items
            return f"two-element list: {x}, {y}"
        case None:
            return "nothing"
        case _:
            return "something else"

# ─── BASIC TRY/EXCEPT ────────────────────────────────────────────
try:
    result = 10 / 0           # this raises ZeroDivisionError
except ZeroDivisionError:
    print("Cannot divide by zero!")   # this runs instead of crashing

# ─── CATCHING MULTIPLE EXCEPTION TYPES ──────────────────────────
try:
    number = int("not a number")   # raises ValueError
except ZeroDivisionError as e:
    print(f"Division error: {e}")
except ValueError as e:
    print(f"Value error: {e}")     # this runs
except (TypeError, AttributeError) as e:
    print(f"Type or attribute error: {e}")  # catch multiple in one line

# ─── ELSE AND FINALLY ────────────────────────────────────────────
try:
    result = 10 / 2
except ZeroDivisionError:
    print("division failed")
else:
    # 'else' runs ONLY if NO exception was raised
    print(f"Success! Result: {result}")   # this runs
finally:
    # 'finally' ALWAYS runs — whether or not an exception happened
    # Use it for cleanup (closing files, database connections, etc.)
    print("This always runs — cleanup here")

# ─── RAISING YOUR OWN EXCEPTIONS ────────────────────────────────
def set_age(age):
    if not isinstance(age, int):
        raise TypeError("Age must be an integer")    # raise stops execution
    if age < 0 or age > 150:
        raise ValueError("Age must be between 0 and 150")
    return age

# ─── CUSTOM EXCEPTION CLASSES ────────────────────────────────────
# Create your own exception types by inheriting from Exception
class ValidationError(ValueError):
    """Raised when user input fails validation."""
    def __init__(self, field, message):
        # Call the parent Exception's __init__ with a formatted message
        super().__init__(f"Field '{field}': {message}")
        self.field = field    # store the field name for later use

def validate_email(email):
    if "@" not in email:
        raise ValidationError("email", "must contain @")

try:
    validate_email("notanemail")
except ValidationError as e:
    print(e)           # "Field 'email': must contain @"
    print(e.field)     # "email" — we can access the field name

class Animal:
    """Base class for all animals."""
    def __init__(self, name: str):
        self.name = name

    def speak(self) -> str:
        """Override this in child classes."""
        return f"{self.name} makes a sound"

    def describe(self) -> str:
        return f"I am {self.name}"


# ─── CHILD CLASS — inherits from Animal ──────────────────────────
class Dog(Animal):
    def __init__(self, name: str, breed: str):
        # super().__init__ calls the PARENT class's __init__
        # This sets self.name (defined in Animal) for us
        # Without this, the Animal's __init__ wouldn't run
        super().__init__(name)
        self.breed = breed    # additional attribute specific to Dog

    def speak(self) -> str:
        # OVERRIDING the parent's speak() method
        # Dog has its own version of speak()
        return f"{self.name} says: Woof!"

    def fetch(self, item: str) -> str:
        return f"{self.name} fetches the {item}!"


class Cat(Animal):
    def speak(self) -> str:
        return f"{self.name} says: Meow!"


# ─── POLYMORPHISM — same interface, different behaviour ──────────
# All animals have a speak() method, but each acts differently
animals = [Dog("Rex", "Husky"), Cat("Whiskers"), Dog("Buddy", "Poodle")]
for animal in animals:
    print(animal.speak())   # Each calls its own version of speak()
# Rex says: Woof!
# Whiskers says: Meow!
# Buddy says: Woof!

# ─── isinstance() — check what type an object is ─────────────────
rex = Dog("Rex", "Husky")
print(isinstance(rex, Dog))      # True — rex IS a Dog
print(isinstance(rex, Animal))   # True — Dog inherits from Animal, so rex IS also an Animal
print(isinstance(rex, Cat))      # False

# ─── ABSTRACT BASE CLASS — force child classes to implement a method ──
from abc import ABC, abstractmethod

class Shape(ABC):
    """Abstract base class. Cannot be instantiated directly."""

    @abstractmethod
    def area(self) -> float:
        """Every Shape MUST implement this method."""
        ...   # ... means "no body — child must provide it"

    @abstractmethod
    def perimeter(self) -> float: ...

class Circle(Shape):
    def __init__(self, radius: float):
        self.radius = radius

    def area(self) -> float:
        return 3.14159 * self.radius ** 2

    def perimeter(self) -> float:
        return 2 * 3.14159 * self.radius

class Rectangle(Shape):
    def __init__(self, width: float, height: float):
        self.width = width
        self.height = height

    def area(self) -> float:
        return self.width * self.height

    def perimeter(self) -> float:
        return 2 * (self.width + self.height)

# Shape()  # TypeError! Can't instantiate an abstract class
c = Circle(5)
r = Rectangle(4, 6)
print(c.area())       # 78.53975
print(r.area())       # 24

class Vector:
    """A 2D mathematical vector."""
    def __init__(self, x: float, y: float):
        self.x = x
        self.y = y

    def __repr__(self) -> str:
        # Called when Python needs a "developer-friendly" representation
        # Used in the REPL and for debugging
        return f"Vector({self.x}, {self.y})"

    def __str__(self) -> str:
        # Called when you print() or str() an object
        # Should be a user-friendly string
        return f"({self.x}, {self.y})"

    def __add__(self, other: "Vector") -> "Vector":
        # Called when you use the + operator: v1 + v2
        return Vector(self.x + other.x, self.y + other.y)

    def __sub__(self, other: "Vector") -> "Vector":
        # Called when you use the - operator: v1 - v2
        return Vector(self.x - other.x, self.y - other.y)

    def __mul__(self, scalar: float) -> "Vector":
        # Called when you use *: v * 3  (Vector on the LEFT)
        return Vector(self.x * scalar, self.y * scalar)

    def __rmul__(self, scalar: float) -> "Vector":
        # Called when Vector is on the RIGHT: 3 * v
        return self.__mul__(scalar)

    def __len__(self) -> int:
        # Called when you use len(): len(v)
        return 2   # a 2D vector always has 2 components

    def __getitem__(self, index: int) -> float:
        # Called when you use indexing: v[0], v[1]
        return (self.x, self.y)[index]

    def __eq__(self, other: "Vector") -> bool:
        # Called when you use ==: v1 == v2
        return self.x == other.x and self.y == other.y

    def __abs__(self) -> float:
        # Called when you use abs(): abs(v)
        # Returns the length (magnitude) of the vector
        return (self.x**2 + self.y**2) ** 0.5

    def __bool__(self) -> bool:
        # Called in an if statement: if v:
        # A zero vector (0, 0) is falsy; any other vector is truthy
        return self.x != 0 or self.y != 0


v1 = Vector(3, 4)
v2 = Vector(1, 2)

print(v1)               # (3, 4) — calls __str__
print(repr(v1))         # Vector(3, 4) — calls __repr__
print(v1 + v2)          # (4, 6) — calls __add__
print(v1 - v2)          # (2, 2) — calls __sub__
print(v1 * 2)           # (6, 8) — calls __mul__
print(3 * v1)           # (9, 12) — calls __rmul__
print(abs(v1))          # 5.0 — calls __abs__ (Pythagorean theorem: √(3²+4²)=5)
print(len(v1))          # 2 — calls __len__
print(v1[0])            # 3 — calls __getitem__
print(v1 == Vector(3,4))# True — calls __eq__

class Temperature:
    """Temperature stored in Celsius, accessible in both scales."""
    def __init__(self, celsius: float = 0):
        # Store the value with a "private" name (leading underscore is convention)
        # The leading _ signals "internal use only" but doesn't enforce it
        self._celsius = celsius

    @property
    def celsius(self) -> float:
        """Getter — runs when you READ: temp.celsius"""
        return self._celsius

    @celsius.setter
    def celsius(self, value: float):
        """Setter — runs when you WRITE: temp.celsius = 25"""
        if value < -273.15:
            raise ValueError("Temperature cannot go below absolute zero!")
        self._celsius = value

    @property
    def fahrenheit(self) -> float:
        """A read-only computed property — converts Celsius to Fahrenheit."""
        # No setter means this property is READ-ONLY
        return self._celsius * 9/5 + 32

    @classmethod
    def from_fahrenheit(cls, f: float) -> "Temperature":
        """Alternative constructor — create from a Fahrenheit value."""
        return cls((f - 32) * 5/9)  # convert to Celsius and create instance


t = Temperature(100)
print(t.celsius)      # 100 — uses the getter
print(t.fahrenheit)   # 212.0 — computed automatically
t.celsius = 25        # uses the setter (runs the validation)
print(t.fahrenheit)   # 77.0

# t.celsius = -300    # ValueError! Below absolute zero

boiling = Temperature.from_fahrenheit(212)  # 100°C
print(boiling.celsius)   # 100.0

# ─── NORMAL FUNCTION vs GENERATOR ───────────────────────────────
def squares_list(n):
    """Regular function: computes ALL squares, stores them in memory."""
    result = []
    for x in range(n):
        result.append(x ** 2)
    return result  # returns a complete list — all in memory at once

def squares_generator(n):
    """Generator function: produces ONE square at a time."""
    for x in range(n):
        yield x ** 2   # 'yield' pauses the function and returns one value
                       # next time next() is called, execution resumes HERE

# The difference in memory usage is huge for large n:
squares_list(1_000_000)      # allocates ~8 MB for the list
squares_generator(1_000_000) # uses almost zero memory!

# ─── USING A GENERATOR ───────────────────────────────────────────
gen = squares_generator(5)
print(next(gen))   # 0  — asks for the first value
print(next(gen))   # 1  — asks for the second value
print(next(gen))   # 4  — asks for the third value
# ... and so on. After all values are exhausted, StopIteration is raised.

# You can also use a generator in a for loop (most common usage)
for square in squares_generator(10):
    print(square)   # 0, 1, 4, 9, 16, 25, 36, 49, 64, 81

# ─── FIBONACCI NUMBER GENERATOR ──────────────────────────────────
def fibonacci_gen(limit):
    """Generates Fibonacci numbers up to a limit."""
    a, b = 0, 1
    while a <= limit:
        yield a          # pause and return 'a'
        a, b = b, a + b  # then swap: new_a = old_b, new_b = old_a + old_b

print(list(fibonacci_gen(50)))   # [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

# ─── INFINITE GENERATOR ──────────────────────────────────────────
def count_forever(start=0):
    """An infinite sequence — generates numbers forever."""
    n = start
    while True:    # this runs forever — that's OK for a generator!
        yield n
        n += 1

# Get just the first 5 numbers from an infinite sequence
from itertools import islice
first_five = list(islice(count_forever(10), 5))  # [10, 11, 12, 13, 14]

# ─── GENERATOR EXPRESSION — like a list comprehension, but lazy ──
# List comprehension — computes everything NOW:
squares_list_expr = [x**2 for x in range(1_000_000)]  # 8 MB

# Generator expression — computes on demand:
squares_gen_expr = (x**2 for x in range(1_000_000))   # near-zero memory
# Just change [] to () to get a generator

total = sum(squares_gen_expr)   # sum without storing all values!

# ─── yield from — delegating to another generator ────────────────
def flatten(nested):
    """Flattens a nested list structure."""
    for item in nested:
        if isinstance(item, list):
            yield from flatten(item)  # delegate to recursive call
        else:
            yield item

result = list(flatten([1, [2, [3, 4]], [5, 6], 7]))
print(result)  # [1, 2, 3, 4, 5, 6, 7]

# ─── SINGLETON WITH METACLASS ────────────────────────────────────
# A Singleton class allows only ONE instance to ever exist
class SingletonMeta(type):
    """Metaclass that ensures only one instance exists."""
    _instances = {}   # class-level dict tracking instances

    def __call__(cls, *args, **kwargs):
        # This runs whenever you try to create a new instance: cls()
        if cls not in cls._instances:
            # First time — create and store the instance
            cls._instances[cls] = super().__call__(*args, **kwargs)
        # Always return the stored instance (same one every time)
        return cls._instances[cls]

class DatabasePool(metaclass=SingletonMeta):
    """Only one connection pool ever exists."""
    def __init__(self):
        self.connections = []
        print("Creating database pool...")  # only prints once!

pool1 = DatabasePool()   # creates new instance
pool2 = DatabasePool()   # returns the SAME instance
print(pool1 is pool2)    # True — they are literally the same object!

# ─── DESCRIPTOR — custom attribute access ────────────────────────
class PositiveNumber:
    """A descriptor that only accepts positive numbers."""
    def __set_name__(self, owner, name):
        self.name = f"_{name}"   # internal storage name with underscore

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self   # when accessed on the class itself
        return getattr(obj, self.name, 0)   # return stored value or 0

    def __set__(self, obj, value):
        if not isinstance(value, (int, float)) or value <= 0:
            raise ValueError(f"{self.name} must be a positive number")
        setattr(obj, self.name, value)   # store the validated value

class Product:
    price = PositiveNumber()      # price must always be positive
    quantity = PositiveNumber()   # quantity must always be positive

    def __init__(self, name: str, price: float, quantity: int):
        self.name = name
        self.price = price          # goes through __set__ — validates!
        self.quantity = quantity

p = Product("Widget", 9.99, 100)
print(p.price)      # 9.99
# p.price = -5      # ValueError! Must be positive

from dataclasses import dataclass, field, asdict, astuple

# @dataclass automatically creates:
# - __init__(self, name, age, email, tags)
# - __repr__ that shows all fields
# - __eq__ that compares all fields
@dataclass
class User:
    name:  str
    age:   int
    email: str = ""                        # default value
    tags:  list[str] = field(default_factory=list)  # mutable default!
    # IMPORTANT: use field(default_factory=list) not tags: list[str] = []
    # Because [] as a default would be shared (the mutable default arg trap)

    def __post_init__(self):
        """Runs after __init__ — great for validation."""
        if self.age < 0:
            raise ValueError("Age cannot be negative")
        self.name = self.name.strip()   # clean up name

u = User("Alice", 30, "alice@example.com")
print(u)          # User(name='Alice', age=30, email='alice@example.com', tags=[])
print(asdict(u))  # {"name": "Alice", "age": 30, ...} — converts to dict

# ─── FROZEN DATACLASS — immutable ────────────────────────────────
@dataclass(frozen=True)
class Point:
    x: float
    y: float

p = Point(1.0, 2.0)
# p.x = 3.0   # FrozenInstanceError! Cannot modify a frozen dataclass
# Frozen dataclasses are hashable — can be used as dict keys or in sets!
d = {Point(0, 0): "origin", Point(1, 1): "one-one"}

# ─── ORDERED COMPARISON ──────────────────────────────────────────
@dataclass(order=True)
class Version:
    major: int
    minor: int
    patch: int

v1 = Version(1, 2, 3)
v2 = Version(1, 3, 0)
v3 = Version(2, 0, 0)
print(v1 < v2)    # True — compared field by field
print(sorted([v3, v1, v2]))  # [Version(1,2,3), Version(1,3,0), Version(2,0,0)]

from pydantic import BaseModel, Field, validator, model_validator
from typing import Optional

class Address(BaseModel):
    street: str
    city:   str
    country: str = "US"   # default value

class User(BaseModel):
    # Field() lets you add validation constraints and documentation
    name:  str = Field(min_length=1, max_length=100, description="User's full name")
    age:   int = Field(ge=0, le=150, description="Age in years")  # ge=greater equal, le=less equal
    email: str
    address: Optional[Address] = None   # nested model — None if not provided
    tags: list[str] = []

    @validator("name")
    @classmethod
    def clean_name(cls, v: str) -> str:
        """Strip whitespace from name."""
        return v.strip()

    @model_validator(mode="after")
    def check_adult_email(self) -> "User":
        """Adults (18+) must have an email address."""
        if self.age >= 18 and not self.email:
            raise ValueError("Adults must have an email address")
        return self

# ─── CREATING INSTANCES ──────────────────────────────────────────
user = User(name="  Alice  ", age=30, email="alice@example.com")
print(user.name)     # "Alice" — whitespace stripped by validator

# ─── VALIDATION ERRORS ───────────────────────────────────────────
try:
    invalid = User(name="", age=30, email="a@b.com")  # name too short!
except Exception as e:
    print(e)   # validation error details

# ─── SERIALIZATION ───────────────────────────────────────────────
user.model_dump()          # → Python dict
user.model_dump_json()     # → JSON string
User.model_validate({"name": "Bob", "age": 25, "email": "b@b.com"})  # from dict

# ─── SETTINGS MANAGEMENT ─────────────────────────────────────────
from pydantic_settings import BaseSettings   # pip install pydantic-settings

class AppSettings(BaseSettings):
    """Read settings from environment variables or .env file."""
    database_url: str         # must be set in environment
    secret_key:   str         # must be set in environment
    debug:        bool = False   # optional, defaults to False
    max_connections: int = 10

    class Config:
        env_file = ".env"     # also read from .env file

settings = AppSettings()   # reads from environment automatically

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough, RunnableLambda, RunnableParallel

llm    = ChatOpenAI(model="gpt-4o-mini")
parser = StrOutputParser()   # converts AI response object → plain string

# ─── BASIC CHAIN ──────────────────────────────────────────────────
# ChatPromptTemplate defines the structure with {placeholders}
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are an expert in {domain}. Give concise answers."),
    ("human",  "{question}"),
])

# The pipe | chains them together
# Data flows: input_dict → prompt → llm → parser → output_string
chain = prompt | llm | parser

result = chain.invoke({
    "domain":   "Python programming",
    "question": "What are list comprehensions?"
})
print(result)   # a plain string with the answer

# ─── BATCH PROCESSING ────────────────────────────────────────────
# Process multiple inputs in parallel
results = chain.batch([
    {"domain": "Python", "question": "What is a decorator?"},
    {"domain": "Python", "question": "What is a generator?"},
    {"domain": "SQL",    "question": "What is a JOIN?"},
])
# Returns a list of 3 results, processed concurrently

# ─── STREAMING ───────────────────────────────────────────────────
for chunk in chain.stream({"domain": "Python", "question": "Explain async"}):
    print(chunk, end="", flush=True)   # tokens arrive one at a time

# ─── PARALLEL EXECUTION ──────────────────────────────────────────
# Run two different chains at the same time on the same input
parallel_chain = RunnableParallel(
    summary  = ChatPromptTemplate.from_template("Summarize in one sentence: {text}") | llm | parser,
    keywords = ChatPromptTemplate.from_template("List 5 keywords from: {text}") | llm | parser,
)
output = parallel_chain.invoke({"text": "Python is a versatile programming language..."})
print(output["summary"])    # the summary
print(output["keywords"])   # the keywords

# ─── RUNNABLELAMBDA — wrap any function ─────────────────────────
def count_words(text: str) -> int:
    return len(text.split())

word_counter = RunnableLambda(count_words)
count_chain  = parser | word_counter   # first get string, then count words

# ─── BRANCHING — different paths based on content ────────────────
from langchain_core.runnables import RunnableBranch

classify_chain = (
    ChatPromptTemplate.from_template("Is this question about Python? Answer yes/no: {q}")
    | llm
    | parser
)

python_chain  = ChatPromptTemplate.from_template("Python expert: {q}") | llm | parser
general_chain = ChatPromptTemplate.from_template("General assistant: {q}") | llm | parser

branch = RunnableBranch(
    (lambda x: "python" in x["topic"].lower(), python_chain),  # condition, chain
    general_chain,  # default if no condition matches
)

from langchain_core.prompts import (
    ChatPromptTemplate,
    PromptTemplate,
    MessagesPlaceholder,
    FewShotPromptTemplate,
)
from langchain_core.messages import HumanMessage, AIMessage

# ─── BASIC CHAT PROMPT TEMPLATE ──────────────────────────────────
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful {role}. Be {style}."),
    ("human",  "{question}"),
])
# Fill in placeholders with a dict
filled = prompt.invoke({
    "role":     "Python tutor",
    "style":    "friendly and concise",
    "question": "What is a variable?",
})

# ─── MULTI-TURN CHAT WITH HISTORY ────────────────────────────────
# MessagesPlaceholder allows injecting a list of messages (conversation history)
chat_prompt = ChatPromptTemplate.from_messages([
    ("system",  "You are a helpful assistant."),
    MessagesPlaceholder(variable_name="history"),   # inject past messages here
    ("human",   "{input}"),
])
# When invoked, 'history' should be a list of HumanMessage/AIMessage objects
filled = chat_prompt.invoke({
    "history": [
        HumanMessage(content="Hi, my name is Alice."),
        AIMessage(content="Hello Alice! How can I help you?"),
    ],
    "input": "What is my name?"
})
# The AI will see the full conversation and answer "Your name is Alice."

# ─── FEW-SHOT TEMPLATE — teach by example ────────────────────────
# Few-shot prompting shows the AI examples of what you want
examples = [
    {"input": "happy",  "output": "sad"},
    {"input": "tall",   "output": "short"},
    {"input": "fast",   "output": "slow"},
]
example_template = PromptTemplate.from_template("Input: {input}\nOutput: {output}")

few_shot = FewShotPromptTemplate(
    examples=examples,
    example_prompt=example_template,
    prefix="Give the antonym (opposite) of each input word.",
    suffix="Input: {word}\nOutput:",
    input_variables=["word"],
)
print(few_shot.format(word="hot"))
# Output: ... examples ... Input: hot / Output:

# ─── PARTIAL PROMPTS — pre-fill some variables ───────────────────
base_prompt = ChatPromptTemplate.from_messages([
    ("system", "You are an expert in {domain}."),
    ("human",  "{question}"),
])
python_prompt = base_prompt.partial(domain="Python")  # domain is now fixed
result = python_prompt.invoke({"question": "What is a decorator?"})
# Only need to provide 'question' now

from langchain_core.output_parsers import (
    StrOutputParser,          # AI response → plain string
    JsonOutputParser,         # AI response → Python dict
    PydanticOutputParser,     # AI response → Pydantic object (validated!)
    CommaSeparatedListOutputParser,  # AI response → Python list
)
from langchain_core.prompts import PromptTemplate
from pydantic import BaseModel, Field

llm = ChatOpenAI(model="gpt-4o-mini")

# ─── STRING PARSER — the simplest ────────────────────────────────
chain = ChatPromptTemplate.from_template("Answer: {q}") | llm | StrOutputParser()
result = chain.invoke({"q": "What color is the sky?"})
print(type(result))   # <class 'str'>

# ─── JSON PARSER ─────────────────────────────────────────────────
json_chain = (
    PromptTemplate.from_template(
        "Return a JSON object with 'name' and 'score' for this text: {text}"
    )
    | llm
    | JsonOutputParser()
)
result = json_chain.invoke({"text": "Alice got 95/100"})
print(result["name"])    # "Alice"
print(result["score"])   # 95

# ─── PYDANTIC PARSER — structured AND validated ───────────────────
class MovieReview(BaseModel):
    title:   str   = Field(description="The movie title")
    rating:  float = Field(description="Rating from 1.0 to 10.0")
    summary: str   = Field(description="One-sentence summary")
    liked:   bool  = Field(description="Whether the reviewer liked it")

parser = PydanticOutputParser(pydantic_object=MovieReview)

prompt = PromptTemplate(
    template="Review this movie and provide your response.\n\n{format_instructions}\n\nMovie: {movie}",
    input_variables=["movie"],
    partial_variables={
        "format_instructions": parser.get_format_instructions()
        # This inserts instructions telling the AI how to format its response
    },
)

chain = prompt | llm | parser
review: MovieReview = chain.invoke({"movie": "Inception (2010)"})
print(review.title)    # "Inception"
print(review.rating)   # 9.2 (or whatever the AI says)
print(review.liked)    # True
# It's now a proper Pydantic object, not just a string!

from typing import TypedDict, Annotated
from dataclasses import dataclass, field
from langgraph.graph import StateGraph, START, END

# ─── EXAMPLE: RESEARCH AGENT WITH LOOP ───────────────────────────
@dataclass
class ResearchState:
    query:        str        = ""          # the user's question
    web_results:  list[str]  = field(default_factory=list)  # search results
    summary:      str        = ""          # final summary
    iterations:   int        = 0          # how many times we've searched
    is_complete:  bool       = False      # are we done?
    quality_ok:   bool       = False      # is the result good enough?

# ─── NODE FUNCTIONS ───────────────────────────────────────────────
def search_web(state: ResearchState) -> dict:
    """Search the web for information (simulated)."""
    print(f"Searching for: {state.query} (attempt {state.iterations + 1})")
    results = [
        f"Result {i}: Information about {state.query} — detail {i}"
        for i in range(1, 4)
    ]
    return {
        "web_results": results,
        "iterations": state.iterations + 1,
    }

def evaluate_results(state: ResearchState) -> dict:
    """Check if we have enough good results."""
    has_enough = len(state.web_results) >= 3
    return {"quality_ok": has_enough}

def summarize(state: ResearchState) -> dict:
    """Summarize the results into a final answer."""
    combined = " ".join(state.web_results)
    summary = f"Summary for '{state.query}': Based on {len(state.web_results)} sources: {combined[:100]}..."
    return {"summary": summary, "is_complete": True}

# ─── ROUTING FUNCTION ─────────────────────────────────────────────
# Returns the NAME of the next node to go to
def should_continue(state: ResearchState) -> str:
    """Decide whether to keep searching or to summarize."""
    if state.is_complete:
        return "done"              # we're done!
    if state.iterations >= 3:
        return "summarize"         # too many attempts, just summarize
    if not state.quality_ok:
        return "search"            # not enough results, search again
    return "summarize"             # results are good, summarize

# ─── BUILD THE GRAPH ──────────────────────────────────────────────
g = StateGraph(ResearchState)

g.add_node("search",   search_web)
g.add_node("evaluate", evaluate_results)
g.add_node("summarize", summarize)

g.add_edge(START, "search")          # always start with search
g.add_edge("search", "evaluate")     # after search, evaluate

# Conditional edge: based on should_continue(), go to "search", "summarize", or END
g.add_conditional_edges(
    "evaluate",          # from this node
    should_continue,     # call this function to decide
    {                    # map return values to node names
        "search":    "search",      # loop back to search
        "summarize": "summarize",   # proceed to summarize
        "done":      END,           # stop
    }
)
g.add_edge("summarize", END)

app = g.compile()
result = app.invoke(ResearchState(query="Python async programming"))
print(result.summary)

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from typing import TypedDict, Annotated

class State(TypedDict):
    messages: Annotated[list, add_messages]

llm = ChatOpenAI(model="gpt-4o-mini")

def chatbot(state):
    return {"messages": [llm.invoke(state["messages"])]}

graph = StateGraph(State)
graph.add_node("chatbot", chatbot)
graph.add_edge(START, "chatbot")
graph.add_edge("chatbot", END)

# ─── ADD CHECKPOINTER ─────────────────────────────────────────────
memory = MemorySaver()             # in-memory checkpointer (use SqliteSaver for persistence)
app = graph.compile(checkpointer=memory)

# ─── MULTI-TURN CONVERSATION ─────────────────────────────────────
# thread_id identifies this conversation — all messages are stored per thread
config = {"configurable": {"thread_id": "conversation-with-alice"}}

# Turn 1
r1 = app.invoke({"messages": [HumanMessage("Hi, my name is Alice and I love Python.")]}, config=config)
print(r1["messages"][-1].content)   # "Hello Alice! Python is a great language..."

# Turn 2 — previous messages are automatically restored from the checkpoint!
r2 = app.invoke({"messages": [HumanMessage("What programming language did I mention?")]}, config=config)
print(r2["messages"][-1].content)   # "You mentioned Python." — it remembers!

# ─── HUMAN-IN-THE-LOOP ────────────────────────────────────────────
# interrupt_before pauses execution BEFORE the specified node
# Useful for letting a human review/approve before a dangerous action
app_with_review = graph.compile(
    checkpointer=memory,
    interrupt_before=["chatbot"],   # pause before 'chatbot' runs
)

# Start execution — stops at the interrupt point
result = app_with_review.invoke({"messages": [HumanMessage("Delete all data")]}, config=config)
# ... at this point, a human can review the state ...

# To APPROVE and continue:
result = app_with_review.invoke(None, config=config)  # None = no new input, just continue

# ─── PERSISTENT CHECKPOINTING ────────────────────────────────────
# For production, use SqliteSaver to persist across restarts
# from langgraph.checkpoint.sqlite import SqliteSaver
# with SqliteSaver.from_conn_string("checkpoints.db") as checkpointer:
#     app = graph.compile(checkpointer=checkpointer)

from fastapi import FastAPI
from pydantic import BaseModel, Field, validator
from typing import Optional
from enum import Enum

app = FastAPI()

# ─── ENUMS — restrict to specific values ─────────────────────────
class Priority(str, Enum):
    low    = "low"
    medium = "medium"
    high   = "high"
    # priority can ONLY be one of these three values

class Status(str, Enum):
    pending    = "pending"
    in_progress = "in_progress"
    done       = "done"

# ─── REQUEST MODEL — what client sends ───────────────────────────
class TaskCreate(BaseModel):
    title:          str      = Field(min_length=1, max_length=200, example="Fix login bug")
    description:    Optional[str] = Field(None, max_length=2000)
    priority:       Priority = Priority.medium   # default to medium
    assignee_email: Optional[str] = None

    @validator("title")   # this runs before the object is created
    @classmethod
    def title_must_not_be_blank(cls, value):
        stripped = value.strip()
        if not stripped:
            raise ValueError("Title cannot be blank or just spaces")
        return stripped   # return cleaned value

# ─── RESPONSE MODEL — what server returns ────────────────────────
class TaskResponse(TaskCreate):   # inherit all fields from TaskCreate
    id:         int
    status:     Status  = Status.pending
    created_at: str

    class Config:
        from_attributes = True   # allows creating from SQLAlchemy ORM objects

# ─── NESTED MODELS ───────────────────────────────────────────────
class Address(BaseModel):
    street:   str
    city:     str
    zip_code: str = Field(pattern=r"^\d{5}$")   # regex: exactly 5 digits

class CompanyCreate(BaseModel):
    name:         str
    headquarters: Address          # nested Pydantic model
    branches:     list[Address] = []   # list of nested models

@app.post("/companies")
def create_company(data: CompanyCreate):
    # FastAPI automatically validates all nested fields too!
    return data.model_dump()

# ─── HIDING SENSITIVE FIELDS ─────────────────────────────────────
class UserWithPassword(BaseModel):
    id:              int
    name:            str
    email:           str
    hashed_password: str   # INTERNAL — should NEVER be in API response!

class UserPublic(BaseModel):
    id:    int
    name:  str
    email: str
    # hashed_password is intentionally missing

@app.get("/me", response_model=UserPublic)  # response_model filters the output!
def get_me():
    # Even though we return hashed_password, the response_model removes it
    user = UserWithPassword(id=1, name="Alice", email="a@x.com", hashed_password="$2b$12$secret")
    return user  # hashed_password will NOT appear in the response ✓

from fastapi import FastAPI, Query, Path, Header, Cookie
from typing import Optional

app = FastAPI()

# ─── PATH PARAMETERS ─────────────────────────────────────────────
# Declared in the URL pattern AND as function parameters
@app.get("/items/{item_id}")
def get_item(
    item_id: int = Path(
        ge=1,                              # must be >= 1
        le=9999,                           # must be <= 9999
        description="Item's primary key",
    ),
):
    return {"item_id": item_id}
# GET /items/42 → item_id=42
# GET /items/0  → 422 Validation Error (must be >= 1)
# GET /items/abc → 422 Validation Error (must be an integer)

# ─── QUERY PARAMETERS ────────────────────────────────────────────
# Everything NOT in the path pattern becomes a query parameter
@app.get("/search")
def search(
    q:        str           = Query(min_length=2, description="Search term"),
    page:     int           = Query(default=1, ge=1),
    per_page: int           = Query(default=20, ge=1, le=100),
    active:   Optional[bool] = Query(default=None),  # None means "show all"
    tags:     list[str]     = Query(default=[]),      # multi-value: ?tags=a&tags=b
):
    return {"q": q, "page": page, "per_page": per_page, "active": active, "tags": tags}
# GET /search?q=python&page=2&tags=web&tags=api
# → {"q": "python", "page": 2, "per_page": 20, "active": null, "tags": ["web","api"]}

# ─── HEADERS AND COOKIES ──────────────────────────────────────────
@app.get("/secure")
def secure_route(
    authorization:  str           = Header(description="Bearer token"),
    x_request_id:   Optional[str] = Header(default=None),  # custom header
    session_id:     Optional[str] = Cookie(default=None),   # from cookie
):
    return {
        "auth":       authorization,
        "request_id": x_request_id,
        "session":    session_id,
    }
# Note: Header() automatically converts header names
# X-Request-ID becomes x_request_id in Python (underscores, lowercase)

from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse
import logging

app = FastAPI()

# ─── CUSTOM EXCEPTION CLASS ──────────────────────────────────────
class AppError(Exception):
    """Base class for all application errors."""
    def __init__(self, code: str, message: str, status_code: int = 400):
        self.code        = code         # machine-readable error code (e.g. "USER_NOT_FOUND")
        self.message     = message      # human-readable message
        self.status_code = status_code  # HTTP status code
        super().__init__(message)

class NotFoundError(AppError):
    def __init__(self, resource: str, resource_id):
        super().__init__(
            code="NOT_FOUND",
            message=f"{resource} with id '{resource_id}' not found",
            status_code=404
        )

class ValidationAppError(AppError):
    def __init__(self, field: str, message: str):
        super().__init__(
            code="VALIDATION_ERROR",
            message=f"Invalid value for '{field}': {message}",
            status_code=422
        )

# ─── REGISTER EXCEPTION HANDLERS ─────────────────────────────────
@app.exception_handler(AppError)
async def app_error_handler(request: Request, exc: AppError):
    """Convert AppError into a consistent JSON response."""
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error":   exc.code,
            "message": exc.message,
        },
    )

@app.exception_handler(404)
async def not_found_handler(request: Request, exc: HTTPException):
    """Custom 404 response that includes the path."""
    return JSONResponse(
        status_code=404,
        content={
            "error":   "NOT_FOUND",
            "message": "The requested resource does not exist",
            "path":    str(request.url.path),
        },
    )

# ─── USING CUSTOM EXCEPTIONS ─────────────────────────────────────
@app.get("/users/{user_id}")
def get_user(user_id: int):
    if user_id not in [1, 2, 3]:  # mock check
        raise NotFoundError("User", user_id)
    return {"id": user_id, "name": f"User {user_id}"}