Python Core Fundamentals Interactive Studio

# import sys: Built-in system parameters & stream access (e.g. sys.stdout).
import sys

# from typing import TextIO: Type hint for I/O text streams.
from typing import TextIO

def format_simple_message(message: str) -> str:
    """Formats a string message. Output: 'Hello Python'"""
    if not isinstance(message, str):
        raise TypeError("Message must be a string")
    return str(message)

def format_multi_line(*lines: str) -> str:
    """Joins arguments into space-separated line. Output: 'Cloud Flask Python'"""
    return " ".join(str(line) for line in lines)

def print_to_stream(stream: TextIO, message: str, end: str = "\n") -> None:
    """Writes to a stream buffer. Output: 'Stream Output Success'"""
    stream.write(message + end)
    stream.flush()

from typing import Union, Tuple

Number = Union[int, float]

def calculate_power(base: Number, exponent: Number) -> Number:
    """Calculates power with type validation for integer and float types."""
    if not isinstance(base, (int, float)) or not isinstance(exponent, (int, float)):
        raise TypeError("Base and exponent must be int or float")
    return base ** exponent

def safe_division(numerator: Number, denominator: Number) -> float:
    """Performs division with zero division handling."""
    if not isinstance(numerator, (int, float)) or not isinstance(denominator, (int, float)):
        raise TypeError("Inputs must be numbers")
    if denominator == 0:
        raise ZeroDivisionError("Denominator cannot be zero")
    return float(numerator / denominator)

def convert_types(value: str) -> Tuple[int, float]:
    """Parses a string numerical input into int and float representations."""
    clean_val = value.strip()
    return int(float(clean_val)), float(clean_val)

# =========================================================================
# PYTHON OPERATORS & EXPRESSIONS ARCHITECTURE
# =========================================================================
import sys
import operator
from typing import Any, Dict, List, Tuple, Union

Numeric = Union[int, float]

# ── TITLE 1: ARITHMETIC AND ASSIGNMENT OPERATORS ──────────────────────────

def calculate_arithmetic_operations(a: Numeric, b: Numeric) -> Dict[str, Numeric]:
    if b == 0:
        raise ZeroDivisionError("Divisor cannot be zero.")
    return {
        "addition": a + b,        "subtraction": a - b,
        "multiplication": a * b,  "float_division": a / b,
        "floor_division": a // b, "modulus": a % b,
        "exponentiation": a ** b,
    }

def calculate_complex_arithmetic(c1: complex, c2: complex) -> Dict[str, complex]:
    return {"addition": c1 + c2, "multiplication": c1 * c2}

def demonstrate_assignment_operators(initial_value: float = 10.0) -> Dict[str, float]:
    val = float(initial_value)
    val += 5.0; val -= 3.0; val *= 2.0; val /= 4.0; val //= 2.0; val %= 2.0; val **= 3.0
    if (walrus_val := val + 99.0) > 50.0:
        return {"walrus_assign": walrus_val}
    return {"final": val}

def demonstrate_inplace_sequence_mutations() -> Tuple[List[int], Dict[str, int]]:
    numbers = [1, 2, 3]
    numbers += [4, 5]
    numbers *= 2
    counts = {"apples": 5}
    counts["apples"] += 10
    return numbers, counts

# ── TITLE 2: COMPARISON AND LOGICAL OPERATORS ─────────────────────────────

def evaluate_comparison_and_logical(x: int, y: int) -> Dict[str, bool]:
    return {
        "equal": x == y, "not_equal": x != y,
        "greater_than": x > y, "logical_and": (x > 0) and (y > 0),
        "logical_or": (x > 0) or (y > 0), "logical_not": not (x == y),
    }

def evaluate_chained_range_comparison(val: float, low: float, high: float) -> bool:
    return low <= val <= high

def evaluate_short_circuit_safety(numbers: List[int]) -> Tuple[bool, int]:
    safe_ratio_possible = len(numbers) > 0 and numbers[0] != 0
    calculated_value = 100 // numbers[0] if safe_ratio_possible else -1
    return safe_ratio_possible, calculated_value

def perform_bitwise_operations(a: int, b: int) -> Dict[str, int]:
    return {"bitwise_and": a & b, "bitwise_or": a | b, "left_shift": a << 2}

# ── TITLE 3: ADVANCED OPERATORS, CUSTOM DUNDERS AND RANGE ─────────────────

class CustomVector2D:
    def __init__(self, x: Numeric, y: Numeric) -> None:
        self.x, self.y = float(x), float(y)

    def __add__(self, other: Any) -> "CustomVector2D":
        return CustomVector2D(self.x + other.x, self.y + other.y)

    def __mul__(self, scalar: Numeric) -> "CustomVector2D":
        return CustomVector2D(self.x * scalar, self.y * scalar)

    def __contains__(self, value: Numeric) -> bool:
        return value == self.x or value == self.y

class PermissionFlags:
    READ = 1 << 2   # 4
    WRITE = 1 << 1  # 2
    EXEC = 1 << 0   # 1

    def __init__(self, mask: int = 0) -> None:
        self.mask = mask

    def __or__(self, other: Any) -> "PermissionFlags":
        return PermissionFlags(self.mask | (other.mask if isinstance(other, PermissionFlags) else other))

    def __contains__(self, flag: int) -> bool:
        return (self.mask & flag) == flag

def inspect_operator_module_and_dunders() -> Dict[str, Any]:
    a, b = 15, 4
    students = [{"name": "Alice", "score": 92}, {"name": "Charlie", "score": 95}]
    sorted_students = sorted(students, key=operator.itemgetter("score"), reverse=True)
    return {"op_add": operator.add(a, b), "top_student": sorted_students[0]["name"]}

def inspect_range_operator_features(start: int, stop: int, step: int) -> Dict[str, Any]:
    r = range(start, stop, step)
    return {"contains_5": (start + step) in r, "memory_bytes": sys.getsizeof(r)}

def inspect_range_attributes_and_methods() -> Dict[str, Any]:
    r = range(1, 10)
    return {"public_methods": [attr for attr in dir(r) if not attr.startswith("__")]}

# from typing import List: Imports List container for return type annotation List[str].
from typing import List

def reverse_string(text: str) -> str:
    """Reverses an input string using slice notation with strict type validation."""
    # Step 1: Validate input type to ensure parameter 'text' is a valid Python string (str).
    if not isinstance(text, str):
        # Raise TypeError if caller passes an invalid data type (e.g., integer or list).
        raise TypeError("Input must be a string")
    # Step 2: Perform sequence reversing using slice step notation text[::-1].
    return text[::-1]

def format_user_greeting(username: str, role: str = "Developer") -> str:
    """Formats a modern f-string user greeting with default values and text normalization."""
    # Step 1: Check if username is empty or falsy.
    if not username:
        # Raise ValueError if username string is empty ("").
        raise ValueError("Username cannot be empty")
    # Step 2: Clean whitespace with .strip(), normalize casing with .capitalize(), and format f-string.
    return f"Welcome {username.strip().capitalize()} ({role})"

def extract_words(text: str) -> List[str]:
    """Splits text into words and cleans trailing punctuation using list comprehension."""
    # Step 1: Handle empty text edge case immediately by returning an empty list.
    if not text:
        return []
    # Step 2: Tokenize text.split(), strip punctuation word.strip(",.!?" ), and filter empty tokens.
    return [word.strip(",.!?") for word in text.split() if word.strip()]

import collections, functools, itertools, operator, random
from typing import List, Tuple, Union, Optional, Any, Dict

def starter_list_examples() -> Dict[str, Any]:
    """Starter examples demonstrating Python Lists (list) for beginners."""
    fruits = ["apple", "banana", "cherry"]
    first_fruit = fruits[0]
    fruits.append("orange")
    fruits[1] = "blueberry"
    removed_item = fruits.pop(0)
    return {"remaining_fruits": fruits, "first_fruit": first_fruit, "removed": removed_item}

def manage_list_elements(elements: List[Any], item_to_add: Optional[Any] = None, remove_index: Optional[int] = None) -> Tuple[List[Any], Optional[Any]]:
    """Appends elements and pops by index with bounds safety. Output: ([20, 30, 40], 10)"""
    if not isinstance(elements, list):
        raise TypeError("First argument 'elements' must be a valid Python list")
    working_list = elements.copy()
    popped_item = None
    if item_to_add is not None:
        working_list.append(item_to_add)
    if remove_index is not None:
        if not isinstance(remove_index, int):
            raise TypeError("Index to remove must be an integer")
        if remove_index < -len(working_list) or remove_index >= len(working_list):
            raise IndexError("remove_index is out of range")
        popped_item = working_list.pop(remove_index)
    return working_list, popped_item

def execute_all_dir_list_methods(initial_items: List[Any]) -> Dict[str, Any]:
    """Executes all 11 built-in methods from dir(list): append, clear, copy, count, extend, index, insert, pop, remove, reverse, sort"""
    if not isinstance(initial_items, list):
        raise TypeError("Input must be a list")
    working = initial_items.copy()           # 1. copy()
    working.append("cherry")                # 2. append()
    working.extend(["date", "elderberry"])   # 3. extend()
    working.insert(1, "fig")                 # 4. insert()
    cnt = working.count("apple")            # 5. count()
    idx = working.index("fig")               # 6. index()
    popped = working.pop(0)                  # 7. pop()
    if "cherry" in working:
        working.remove("cherry")             # 8. remove()
    working.reverse()                        # 9. reverse()
    str_list = [str(i) for i in working]
    str_list.sort()                          # 10. sort()
    cleared = working.copy()
    cleared.clear()                          # 11. clear()
    return {"modified": working, "count_apple": cnt, "popped": popped, "sorted": str_list, "cleared": cleared}

def process_list_with_standard_libraries(items: List[Any], numbers: List[int]) -> Dict[str, Any]:
    """Integrates collections (deque, Counter), itertools (chain, combinations), functools (reduce), operator (itemgetter), and random"""
    dq = collections.deque(items)
    dq.appendleft("first_header")
    freq = dict(collections.Counter(items))
    chained = list(itertools.chain(items, ["extra_1", "extra_2"]))
    combos = list(itertools.combinations(numbers[:3], 2))
    total = functools.reduce(lambda a, b: a + b, numbers, 0)
    recs = [{"name": "Dilshad", "score": 98}, {"name": "Monika", "score": 92}]
    sorted_recs = sorted(recs, key=operator.itemgetter("score"), reverse=True)
    rng = random.Random(42)
    sampled = rng.sample(items, min(2, len(items)))
    return {"deque": list(dq), "counter": freq, "chained": chained, "reduce_sum": total, "operator_sorted": sorted_recs, "sample": sampled}

import sys, itertools
from typing import List, Dict, Tuple, Union, Optional, Any

Number = Union[int, float]

def starter_list_comprehension_examples() -> Dict[str, Any]:
    """Starter examples demonstrating List Comprehensions for beginners."""
    squares = [x ** 2 for x in range(1, 6)]
    evens = [x for x in range(1, 11) if x % 2 == 0]
    words = ["hello", "cloud", "flask", "python"]
    uppercase_words = [word.upper() for word in words]
    return {"squares": squares, "evens": evens, "uppercase_words": uppercase_words}

def basic_and_conditional_comprehensions(numbers: List[Number], threshold: Number = 0) -> Dict[str, List[Any]]:
    """Basic [x**2 for x in nums], filter [x for x in nums if x > threshold], ternary [x if x >= 0 else 0 for x in nums]"""
    if not isinstance(numbers, list):
        raise TypeError("Input must be a list")
    squared = [x ** 2 for x in numbers]
    filtered = [x for x in numbers if x > threshold]
    clamped = [x if x >= 0 else 0 for x in numbers]
    return {"squared": squared, "filtered": filtered, "clamped": clamped}

def nested_and_matrix_comprehensions(matrix: List[List[Any]]) -> Dict[str, Any]:
    """Matrix flattening [x for row in matrix for x in row] and transposing [[row[i] for row in matrix] for i in range(cols)]"""
    flattened = [element for row in matrix for element in row]
    cols = len(matrix[0]) if matrix else 0
    transposed = [[row[i] for row in matrix] for i in range(cols)]
    return {"flattened": flattened, "transposed": transposed}

def dict_set_and_generator_comprehensions(items: List[Any]) -> Dict[str, Any]:
    """Dict comprehension {x: len(x)}, set comprehension {x.upper()}, generator memory comparison sys.getsizeof()"""
    length_dict = {str(item): len(str(item)) for item in items}
    unique_set = {str(item).upper() for item in items}
    list_comp = [x ** 2 for x in range(10000)]
    gen_expr = (x ** 2 for x in range(10000))
    return {"dict": length_dict, "set": unique_set, "list_bytes": sys.getsizeof(list_comp), "gen_bytes": sys.getsizeof(gen_expr)}

def comprehension_vs_standard_libraries(numbers: List[int]) -> Dict[str, Any]:
    """Benchmarking comprehension vs map(), filter(), itertools.starmap(), itertools.compress(), any(), and all()"""
    map_res = list(map(lambda x: x * 2, numbers))
    comp_map = [x * 2 for x in numbers]
    filter_res = list(filter(lambda x: x % 2 == 0, numbers))
    comp_filter = [x for x in numbers if x % 2 == 0]
    return {"map_match": map_res == comp_map, "filter_match": filter_res == comp_filter, "has_even": any(x % 2 == 0 for x in numbers)}

import collections, sys
from typing import Tuple, List, Dict, Any

def starter_tuple_examples() -> Dict[str, Any]:
    """Starter examples demonstrating Python Tuples (tuple) for beginners."""
    color_rgb = (255, 128, 0)
    single_element_tuple = ("python",)
    red_val = color_rgb[0]
    green_blue_slice = color_rgb[1:]
    lat, lon = 36.1912, 44.0092
    return {"color_rgb": color_rgb, "extracted_red": red_val, "slice_green_blue": green_blue_slice, "unpacked_coordinates": (lat, lon)}

def tuple_packing_and_unpacking(a: Any, b: Any, c: Any) -> Dict[str, Any]:
    packed = (a, b, c)
    val1, val2, val3 = packed
    head, *rest = (a, b, c, "extra1")
    return {"packed": packed, "unpacked": [val1, val2, val3], "head": head, "rest": rest}

def execute_all_dir_tuple_methods(sample_tuple: Tuple[Any, ...]) -> Dict[str, Any]:
    first_item = sample_tuple[0] if sample_tuple else None
    cnt = sample_tuple.count(first_item)
    idx = sample_tuple.index(first_item)
    return {"count_first": cnt, "index_first": idx}

def tuple_memory_and_namedtuple(data_records: List[Tuple[str, int]]) -> Dict[str, Any]:
    Point = collections.namedtuple("Point", ["x", "y"])
    p = Point(10, 20)
    return {"point": p, "x": p.x, "is_lightweight": sys.getsizeof((1,2)) < sys.getsizeof([1,2])}

from typing import Set, FrozenSet, List, Dict, Any

def starter_set_examples() -> Dict[str, Any]:
    """Starter examples demonstrating Python Sets (set) for beginners."""
    numbers = [1, 2, 2, 3, 3, 3, 4]
    unique_numbers = set(numbers)
    fruit_set = {"apple", "banana", "cherry"}
    fruit_set.add("orange")
    fruit_set.discard("banana")
    return {"unique_numbers": list(unique_numbers), "fruit_set": list(fruit_set), "has_apple": "apple" in fruit_set}

def set_operations_and_math(set_a: Set[Any], set_b: Set[Any]) -> Dict[str, Any]:
    union_res = set_a | set_b
    intersection_res = set_a & set_b
    difference_res = set_a - set_b
    sym_diff_res = set_a ^ set_b
    return {"union": union_res, "intersection": intersection_res, "difference": difference_res}

def execute_all_dir_set_methods(initial_elements: List[Any]) -> Dict[str, Any]:
    s1 = set(initial_elements)
    s1.add("new_element")
    s1.discard("non_existent")
    frozen = frozenset(["immutable_1", "immutable_2"])
    return {"modified_set": s1, "frozenset": frozen}

import collections, json
from typing import Dict, List, Any, Tuple

def starter_dict_examples() -> Dict[str, Any]:
    """Starter examples demonstrating Python Dictionaries (dict) for beginners."""
    user_profile = {"username": "coder_starter", "level": "Beginner", "score": 100}
    user_name = user_profile["username"]
    user_role = user_profile.get("role", "Guest")
    user_profile["score"] = 150
    user_profile["language"] = "Python"
    return {"user_profile": user_profile, "accessed_username": user_name, "safe_get_role": user_role}

def execute_all_dir_dict_methods(initial_dict: Dict[str, Any]) -> Dict[str, Any]:
    d = initial_dict.copy()
    val_name = d.get("name", "Unknown")
    role_val = d.setdefault("role", "Developer")
    d.update({"status": "active"})
    return {"modified_dict": d, "get_name": val_name, "role": role_val}

def dict_standard_libraries_and_json(pairs: List[Tuple[str, Any]]) -> Dict[str, Any]:
    dd = collections.defaultdict(list)
    for k, v in pairs:
        dd[k].append(v)
    merged = {**{"a": 1}, **{"b": 2}}
    json_str = json.dumps(merged)
    return {"defaultdict": dict(dd), "json": json_str}

# =========================================================================
# IMPORT NOTES & MODULE DEPENDENCIES:
# - import sys: Used for runtime interpreter parameters and memory checks.
# - from typing import ...: PEP 484 type hints for parameters & return values.
# =========================================================================
import sys
from typing import Dict, List, Any, Union, Tuple, Optional

Number = Union[int, float]

def starter_if_examples() -> Dict[str, Any]:
    """Starter examples demonstrating Python conditional statements (if, if-else, if-elif-else)."""
    temperature = 25
    is_warm = False
    if temperature >= 20:
        is_warm = True

    user_age = 20
    access_granted = False
    if user_age >= 18:
        access_granted = True
    else:
        access_granted = False

    score = 88
    if score >= 90:
        grade = "A"
    elif score >= 80:
        grade = "B"
    elif score >= 70:
        grade = "C"
    else:
        grade = "F"

    return {"is_warm": is_warm, "access_granted": access_granted, "assigned_grade": grade}

def logical_operators_and_short_circuit() -> Dict[str, Any]:
    """Demonstrates logical operators ('and', 'or', 'not') and short-circuit evaluation."""
    has_license = True
    has_insurance = True
    has_violations = False

    can_drive = has_license and has_insurance
    is_clean_record = not has_violations
    is_eligible = (has_license and has_insurance) and not has_violations

    return {"can_drive": can_drive, "is_eligible": is_eligible}

def truthiness_and_falsiness_evaluator(val: Any) -> Dict[str, Any]:
    """Evaluates truth value testing across None, numbers, containers, and booleans."""
    is_truthy = bool(val)
    category = "Truthy Object"
    if val is None:
        category = "NoneType (Falsy)"
    elif val == 0 or val == 0.0 or val == "":
        category = "Zero/Empty Primitive (Falsy)"
    elif isinstance(val, (list, tuple, dict, set)) and len(val) == 0:
        category = "Empty Container (Falsy)"

    return {"is_truthy": is_truthy, "category": category}

def methods_and_attributes_in_conditionals(obj: Any, text: str, values: List[int]) -> Dict[str, Any]:
    """Demonstrates methods, attributes (hasattr, callable), and aggregators (all, any) inside if statements."""
    has_len = hasattr(obj, "__len__")
    is_callable = callable(obj)
    is_num_text = text.isdigit() if text else False
    all_pos = all(v > 0 for v in values) if values else False
    is_modern = sys.version_info >= (3, 10)

    return {"has_len": has_len, "is_callable": is_callable, "is_num_text": is_num_text, "all_pos": all_pos, "is_modern": is_modern}

# =========================================================================
# IMPORT NOTES & MODULE DEPENDENCIES:
# - import sys: Standard library module for interpreter parameters and maxsize checks.
# - import itertools: Standard library module for predicate iterator filtering (takewhile, dropwhile).
# - import time: High-resolution performance timer benchmarking for loop execution.
# - from typing import Dict, List, Any, Tuple, Optional, Union: PEP 484 type annotations.
# =========================================================================
import itertools
import sys
import time
from typing import Any, Dict, List, Optional, Tuple, Union

Number = Union[int, float]

def starter_while_loop_examples() -> Dict[str, Any]:
    """Starter examples demonstrating count-controlled and dual-variable while loops."""
    counter = 0
    count_list: List[int] = []
    while counter < 5:
        count_list.append(counter)
        counter += 1

    countdown = 5
    countdown_list: List[int] = []
    while countdown > 0:
        countdown_list.append(countdown)
        countdown -= 1

    x, y = 0, 10
    dual_steps: List[Tuple[int, int]] = []
    while x < 5 and y > 5:
        dual_steps.append((x, y))
        x += 1
        y -= 1

    total_sum = 0
    num = 1
    while num <= 10:
        total_sum += num
        num += 1

    return {
        "counter_sequence": count_list,
        "countdown_sequence": countdown_list,
        "dual_variable_steps": dual_steps,
        "accumulated_sum": total_sum,
        "final_counter_value": counter,
    }

def interactive_and_event_controlled_loops(
    quiz_guesses: List[int],
    pet_guesses: List[str],
    calc_op: Tuple[float, float, str],
) -> Dict[str, Any]:
    """Demonstrates event-controlled loops, sentinel evaluation, and interactive quiz/calculator logic."""
    if not isinstance(quiz_guesses, list):
        raise TypeError("Input 'quiz_guesses' must be a valid Python list")
    if not isinstance(pet_guesses, list):
        raise TypeError("Input 'pet_guesses' must be a valid Python list")

    quiz_attempts = 0
    quiz_success = False
    quiz_message = "No choices provided"
    idx = 0
    while idx < len(quiz_guesses) and quiz_attempts < 3:
        guess = quiz_guesses[idx]
        quiz_attempts += 1
        idx += 1
        if guess == 1:
            quiz_success = True
            quiz_message = "Correct! The company is Google."
            break
        elif guess == 3:
            quiz_success = False
            quiz_message = "Sorry, your guess was wrong. The answer was Google."
            break
        else:
            if quiz_attempts >= 3:
                quiz_message = "Maximum attempts reached."

    pet_attempts = 0
    pet_found = False
    idx = 0
    while idx < len(pet_guesses):
        ans = pet_guesses[idx].strip()
        pet_attempts += 1
        idx += 1
        if ans == "Raffi":
            pet_found = True
            break

    v1, v2, op = calc_op
    if op == "+":
        calc_result = v1 + v2
    elif op == "-":
        calc_result = v1 - v2
    elif op == "*":
        calc_result = v1 * v2
    elif op == "/":
        calc_result = v1 / v2 if v2 != 0 else "Error: Division by zero"
    else:
        calc_result = "Error: Unrecognized operator"

    return {
        "quiz_success": quiz_success,
        "quiz_attempts": quiz_attempts,
        "quiz_message": quiz_message,
        "pet_found": pet_found,
        "pet_attempts": pet_attempts,
        "calc_result": calc_result,
    }

def state_flags_and_accumulators(target_sum: int = 24) -> Dict[str, Any]:
    """Demonstrates boolean state flags (keep_going) and step accumulator tracking."""
    if not isinstance(target_sum, int) or target_sum <= 0:
        raise TypeError("Input 'target_sum' must be a positive integer")

    keep_going = True
    a, b = 0, 0
    accumulation_history: List[Tuple[int, int, int]] = []

    while keep_going:
        a += 5
        b += 7
        total = a + b
        accumulation_history.append((a, b, total))
        if total >= target_sum:
            keep_going = False

    pos = 0
    trajectory: List[int] = []
    status_active = True
    while status_active and pos < 50:
        pos += 12
        trajectory.append(pos)
        if pos >= 36:
            status_active = False

    return {
        "accumulation_history": accumulation_history,
        "final_total": accumulation_history[-1][2] if accumulation_history else 0,
        "trajectory": trajectory,
        "status_active": status_active,
    }

def loop_control_and_sentinels(
    numbers: List[int], stop_val: int = -1
) -> Dict[str, Any]:
    """Demonstrates loop control keywords ('break', 'continue') and 'while-else' behavior."""
    if not isinstance(numbers, list):
        raise TypeError("Input 'numbers' must be a valid Python list")

    idx = 0
    collected_before_sentinel: List[int] = []
    hit_sentinel = False
    while idx < len(numbers):
        curr = numbers[idx]
        if curr == stop_val:
            hit_sentinel = True
            break
        collected_before_sentinel.append(curr)
        idx += 1

    idx = 0
    valid_division_results: List[float] = []
    skipped_zero_count = 0
    while idx < len(numbers):
        curr = numbers[idx]
        idx += 1
        if curr == 0:
            skipped_zero_count += 1
            continue
        valid_division_results.append(round(100.0 / curr, 2))

    idx = 0
    else_executed = False
    while idx < len(numbers):
        if numbers[idx] == -99999:
            break
        idx += 1
    else:
        else_executed = True

    return {
        "collected_before_sentinel": collected_before_sentinel,
        "hit_sentinel": hit_sentinel,
        "valid_division_results": valid_division_results,
        "skipped_zero_count": skipped_zero_count,
        "else_executed": else_executed,
    }

# =========================================================================
# IMPORT NOTES & MODULE DEPENDENCIES:
# - import sys: Used for runtime interpreter parameters and memory checks.
# - import itertools: High-performance iterator tools (chain, islice, cycle).
# - from typing import ...: PEP 484 type hints for parameters & return values.
# =========================================================================
import sys
import itertools
from typing import Dict, List, Any, Union, Tuple, Optional

def starter_loop_examples() -> Dict[str, Any]:
    """Starter examples demonstrating Python 'for' loop structures (for, range, break, continue, else)."""
    fruits = ["apple", "banana", "cherry"]
    collected_fruits = []
    for fruit in fruits:
        collected_fruits.append(fruit.upper())

    range_numbers = []
    for i in range(1, 10, 2):
        range_numbers.append(i)

    counter = 0
    accumulated_sum = 0
    for step in range(1, 6):
        counter = step
        accumulated_sum += step

    filtered_sequence = []
    for num in range(1, 20):
        if num % 2 == 0:
            continue
        if num > 7:
            break
        filtered_sequence.append(num)

    return {
        "collected_fruits": collected_fruits,
        "range_numbers": range_numbers,
        "accumulated_counter": counter,
        "accumulated_sum": accumulated_sum,
        "filtered_sequence": filtered_sequence
    }
def enumerate_and_zip_iteration(names: List[str], scores: List[int]) -> Dict[str, Any]:
    """Demonstrates index tracking via enumerate() and sequence pairing via zip()."""
    indexed_students = []
    for rank, name in enumerate(names, start=1):
        indexed_students.append(f"#{rank} {name}")

    paired_results = []
    for name, score in zip(names, scores):
        paired_results.append((name, score))

    return {"indexed_students": indexed_students, "paired_results": paired_results}

# =========================================================================
# IMPORT NOTES & MODULE DEPENDENCIES:
# - import sys: Standard library module for CPython memory inspection (sys.getsizeof).
# - import datetime: Standard library module for datetime formatting specifiers (%B, %d, %j, %A).
# - from typing import Dict, List, Any, Tuple, Union, Optional: PEP 484 type annotations.
# =========================================================================
import datetime
import sys
from typing import Any, Dict, List, Optional, Tuple, Union

Number = Union[int, float]

def starter_range_examples() -> Dict[str, Any]:
    """Starter examples demonstrating range sequence generation and grid iteration."""
    stop_seq = list(range(5))
    start_stop_seq = list(range(2, 8))
    step_seq = list(range(1, 10, 2))
    countdown_seq = list(range(10, 0, -2))

    grid_matrix: List[List[int]] = []
    for r in range(3):
        row: List[int] = []
        for c in range(4):
            row.append(r * 4 + c)
        grid_matrix.append(row)

    horizontal_str = " -> ".join(str(x) for x in range(1, 6))

    return {
        "stop_sequence": stop_seq,
        "start_stop_sequence": start_stop_seq,
        "step_sequence": step_seq,
        "countdown_sequence": countdown_seq,
        "grid_matrix": grid_matrix,
        "horizontal_sequence": horizontal_str,
    }

def range_and_number_formatting(
    limit: int = 5,
    large_number: int = 1000000,
    float_val: float = 123.45678,
) -> Dict[str, Any]:
    """Demonstrates zero-padded range iteration, float precision, and thousand separators."""
    if not isinstance(limit, int) or limit < 0:
        raise TypeError("Input 'limit' must be a non-negative integer")

    zero_padded_list = [f"{i:02d}" for i in range(1, limit + 1)]
    custom_padded_list = [f"ITEM_{i:04d}" for i in range(1, limit + 1)]

    formatted_float_2dp = f"{float_val:.2f}"
    formatted_float_4dp = f"{float_val:.4f}"

    formatted_large_comma = f"{large_number:,}"
    formatted_large_underscore = f"{large_number:_}"

    return {
        "zero_padded_items": zero_padded_list,
        "custom_padded_items": custom_padded_list,
        "formatted_float_2dp": formatted_float_2dp,
        "formatted_float_4dp": formatted_float_4dp,
        "formatted_large_comma": formatted_large_comma,
        "formatted_large_underscore": formatted_large_underscore,
    }

def datetime_and_graphics_formatting(
    days_count: int = 5,
    pyramid_height: int = 4,
) -> Dict[str, Any]:
    """Demonstrates datetime specifiers over range intervals and 3D ASCII graphic patterns."""
    base_date = datetime.datetime(2026, 1, 1)
    formatted_dates: List[Dict[str, str]] = []

    for day_offset in range(days_count):
        current_date = base_date + datetime.timedelta(days=day_offset)
        formatted_dates.append({
            "iso": current_date.strftime("%Y-%m-%d"),
            "full_date": current_date.strftime("%A, %B %d, %Y"),
            "day_of_year": current_date.strftime("Day %j"),
        })

    pyramid_lines: List[str] = []
    for i in range(1, pyramid_height + 1):
        spaces = " " * (pyramid_height - i)
        stars = "*" * (2 * i - 1)
        pyramid_lines.append(f"{spaces}{stars}")

    single_sided_lines: List[str] = []
    for i in range(1, pyramid_height + 1):
        single_sided_lines.append("*" * i)

    decreasing_space_lines: List[str] = []
    for i in range(pyramid_height, 0, -1):
        spaces = " " * (pyramid_height - i)
        hashes = "#" * i
        decreasing_space_lines.append(f"{spaces}{hashes}")

    return {
        "formatted_dates": formatted_dates,
        "ascii_pyramid": pyramid_lines,
        "ascii_single_sided": single_sided_lines,
        "ascii_decreasing_space": decreasing_space_lines,
    }

def range_vs_xrange_mechanics() -> Dict[str, Any]:
    """Demonstrates dir(range), O(1) constant memory, containment testing, and Python 2 xrange comparison."""
    r = range(2, 20, 3)
    range_1k = range(1000)
    range_1m = range(1000000)
    list_1k = list(range(1000))

    return {
        "range_attributes": {"start": r.start, "stop": r.stop, "step": r.step, "length": len(r)},
        "sequence_methods": {"index_of_8": r.index(8), "count_of_8": r.count(8)},
        "containment_test": {"in_range": 14 in r, "not_in_range": 7 in r},
        "memory_benchmark": {
            "range_1k_bytes": sys.getsizeof(range_1k),
            "range_1m_bytes": sys.getsizeof(range_1m),
            "list_1k_bytes": sys.getsizeof(list_1k),
            "is_constant_memory": sys.getsizeof(range_1k) == sys.getsizeof(range_1m),
        },
        "dir_range_public_methods": sorted([m for m in dir(range) if not m.startswith("_")]),
    }

# =========================================================================
# PYTHON FUNCTIONS, LEGB SCOPE & RECURSION BASICS
# Sourced & Standardized from DilshadPython/Python/Function
# =========================================================================
import sys
import functools
import inspect
from typing import Dict, List, Any, Tuple, Callable

GLOBAL_COUNTER: int = 100

def starter_function_examples(
    name: str = "Developer",
    base_val: int = 10,
    *args: int,
    **kwargs: Any
) -> Dict[str, Any]:
    """Parameter passing, default parameters, *args, **kwargs, and tuple returns."""
    if not isinstance(name, str):
        raise TypeError("Input 'name' must be a valid string")
    if not isinstance(base_val, (int, float)):
        raise TypeError("Input 'base_val' must be a valid number")

    greeting_msg = f"Welcome, {name}! System Base Value: {base_val}"
    args_sum = base_val + sum(args)

    user_profile = {"name": name, "base_val": base_val}
    for key, value in kwargs.items():
        user_profile[key] = value

    def compute_stats(x: int, y: int) -> Tuple[int, int, float]:
        return x + y, x * y, (x + y) / 2.0

    add_res, mul_res, avg_res = compute_stats(base_val, 5)
    return {
        "greeting_msg": greeting_msg,
        "args_sum": args_sum,
        "unpacked_args_count": len(args),
        "user_profile": user_profile,
        "arithmetic_stats": {"sum": add_res, "product": mul_res, "average": avg_res},
    }

def scope_and_legb_rule(initial_value: int) -> Dict[str, Any]:
    """LEGB scope resolution, global, nonlocal, and state-retaining closures."""
    if not isinstance(initial_value, int):
        raise TypeError("Input 'initial_value' must be a valid integer")

    global GLOBAL_COUNTER
    original_global = GLOBAL_COUNTER
    GLOBAL_COUNTER += initial_value

    local_val = initial_value * 2
    enclosing_counter = 50

    def inner_accumulator(increment: int) -> int:
        nonlocal enclosing_counter
        enclosing_counter += increment
        return enclosing_counter

    accumulated_1 = inner_accumulator(10)
    accumulated_2 = inner_accumulator(20)

    def make_multiplier(factor: int) -> Callable[[int], int]:
        def multiplier(number: int) -> int:
            return number * factor
        return multiplier

    double = make_multiplier(2)
    triple = make_multiplier(3)

    return {
        "original_global": original_global,
        "modified_global": GLOBAL_COUNTER,
        "local_shadow_val": local_val,
        "enclosing_first_step": accumulated_1,
        "enclosing_second_step": accumulated_2,
        "closure_double_val": double(local_val),
        "closure_triple_val": triple(local_val),
    }

def functional_utilities_and_dispatch(
    items: List[int], op_name: str = "square"
) -> Dict[str, Any]:
    """Lambdas, filter(), reduce(), higher-order functions, and dictionary dispatch tables."""
    if not isinstance(items, list):
        raise TypeError("Input 'items' must be a valid Python list")

    square_lambda: Callable[[int], int] = lambda x: x ** 2
    squared_list: List[int] = [square_lambda(x) for x in items]
    even_items: List[int] = list(filter(lambda x: x % 2 == 0, items))
    product_reduction: int = functools.reduce(lambda x, y: x * y, items, 1)

    dispatch_table: Dict[str, Callable[[List[int]], int]] = {
        "sum": sum,
        "max": max,
        "min": min,
        "product": lambda lst: functools.reduce(lambda a, b: a * b, lst, 1),
    }

    dispatch_result = dispatch_table.get(op_name, sum)(items)

    def apply_transform(data: List[int], func: Callable[[int], int]) -> List[int]:
        return [func(x) for x in data]

    cube_transform = apply_transform(items, lambda x: x ** 3)

    return {
        "squared_list": squared_list,
        "even_items": even_items,
        "product_reduction": product_reduction,
        "dispatch_operation": op_name,
        "dispatch_result": dispatch_result,
        "cube_transform": cube_transform,
    }

def recursion_mechanics(n: int, text: str) -> Dict[str, Any]:
    """Recursive factorial, character counting, and string deduplication."""
    if not isinstance(n, int) or n < 0:
        raise ValueError("Input 'n' must be a non-negative integer")
    if not isinstance(text, str):
        raise TypeError("Input 'text' must be a valid string")

    def recursive_factorial(val: int) -> int:
        if val <= 1:
            return 1
        return val * recursive_factorial(val - 1)

    def recursive_count_char(s: str, target: str) -> int:
        if not s:
            return 0
        match = 1 if s[0] == target else 0
        return match + recursive_count_char(s[1:], target)

    def recursive_deduplicate(s: str) -> str:
        if len(s) <= 1:
            return s
        if s[0] == s[1]:
            return recursive_deduplicate(s[1:])
        return s[0] + recursive_deduplicate(s[1:])

    return {
        "input_number": n,
        "factorial_result": recursive_factorial(n),
        "target_letter_count": recursive_count_char(text.lower(), "a"),
        "deduplicated_text": recursive_deduplicate(text),
    }

def legacy_python2_comparison_demo(point: Tuple[int, int], factor: int) -> Dict[str, Any]:
    """Python 2.7 legacy patterns vs Python 3 modern PEP 8 equivalents."""
    if not isinstance(point, tuple) or len(point) != 2:
        raise TypeError("Input 'point' must be a 2-element tuple")

    x, y = point
    scaled_point = (x * factor, y * factor)

    counter = 0
    def increment_counter() -> int:
        nonlocal counter
        counter += 1
        return counter

    increment_counter()
    final_count = increment_counter()

    def sample_func(a: int, b: int) -> int:
        return a + b

    dynamic_res = sample_func(*point)
    return {
        "scaled_point": scaled_point,
        "closure_state_counter": final_count,
        "dynamic_unpacking_result": dynamic_res,
        "dunder_name": sample_func.__name__,
        "dunder_code": str(sample_func.__code__),
    }

# =========================================================================
# RETURN STATEMENT MECHANICS & BEST PRACTICES TUTORIAL MODULE
# Sourced & Standardized from DilshadPython/Python/Return
# =========================================================================
import sys
from typing import Any, Callable, Dict, Generator, List, NoReturn, Optional, Tuple, Union

# 1. STARTER RETURN EXAMPLES & FUNDAMENTALS
def calculate_triangle_volume(base_area: float, height: float) -> None:
    # Implicit None return occurs at end of function execution
    _volume = (1 / 3) * base_area * height

def calculate_cube_volume(length: float, width: float, height: float) -> float:
    # Explicit value calculation return
    return float(length * width * height)

def explicit_none_return(condition: bool) -> Optional[str]:
    # Explicit None return for optional values
    if condition:
        return "Condition satisfied"
    return None

def get_coordinate_3d(x: float, y: float, z: float) -> Tuple[float, float, float]:
    # Comma-separated values auto-pack into a tuple
    return x, y, z

def check_even_odd(number: int) -> str:
    # Conditional early return branching
    if not isinstance(number, int):
        raise TypeError("Input 'number' must be an integer")
    if number % 2 == 0:
        return "Even"
    return "Odd"

# 2. ADVANCED RETURN MECHANICS & HIGHER-ORDER CLOSURES
def create_multiplier(factor: float) -> Callable[[float], float]:
    # Returning a closure function with outer scope binding
    def multiplier(number: float) -> float:
        return number * factor
    return multiplier

def execute_finally_return_demo(override: bool) -> str:
    # Return statement precedence inside try...finally blocks
    try:
        return "Return from try block"
    finally:
        if override:
            # WARNING: Returning from finally overrides try return values
            return "Return overridden by finally block"

def generator_with_return_value(limit: int) -> Generator[int, None, str]:
    # PEP 380 generator return value attached to StopIteration exception
    for i in range(limit):
        yield i
    return f"Completed generator iteration up to {limit}"

def consume_generator(limit: int) -> Tuple[List[int], str]:
    # Consume generator and extract StopIteration.value return payload
    gen = generator_with_return_value(limit)
    items: List[int] = []
    return_val = ""
    while True:
        try:
            items.append(next(gen))
        except StopIteration as exc:
            return_val = str(exc.value)
            break
    return items, return_val

def raise_fatal_error(message: str) -> NoReturn:
    # typing.NoReturn annotation for functions that never return control
    raise RuntimeError(f"Fatal error encountered: {message}")

# 3. GUARD CLAUSES & INTROSPECTION PATTERNS
def validate_and_process_user(data: Optional[Dict[str, Any]]) -> Dict[str, Any]:
    # Guard Clause Pattern (Early Return to avoid deep nesting)
    if data is None:
        return {"status": "error", "message": "Input data cannot be None"}
    if not isinstance(data, dict):
        return {"status": "error", "message": "Input data must be a dictionary"}
    if "username" not in data or not data["username"]:
        return {"status": "error", "message": "Missing required field: username"}
    
    age = data.get("age", 0)
    if not isinstance(age, (int, float)) or age < 18:
        return {"status": "error", "message": "User must be at least 18 years old"}

    # Unindented happy path execution
    normalized_username = str(data["username"]).strip().lower()
    return {
        "status": "success",
        "message": "User processed successfully",
        "processed_data": {
            "username": normalized_username,
            "age": int(age),
            "is_active": True,
        },
    }

def inspect_return_object(obj: Any) -> List[str]:
    # dir() introspection filtering private dunder attributes
    attributes = dir(obj)
    return sorted([attr for attr in attributes if not attr.startswith("__")])

# =========================================================================
# ADVANCED PYTHON FUNCTIONS, DECORATORS, GENERATORS & ASYNC
# Sourced & Standardized from DilshadPython/Python/Functions-Advanced
# =========================================================================
import asyncio
import functools
import inspect
import sys
import time
from typing import Any, AsyncGenerator, Callable, Dict, Generator, List, Optional, Tuple, Union

# 1. DECORATORS & METADATA PRESERVATION
def timer_decorator(func: Callable[..., Any]) -> Callable[..., Any]:
    """Decorator measuring function latency while preserving metadata via @functools.wraps."""
    @functools.wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Tuple[Any, float]:
        start_time = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start_time
        return result, round(elapsed, 6)
    return wrapper

def retry_decorator(retries: int = 3, delay: float = 0.01) -> Callable[..., Any]:
    """Parametrized decorator factory retrying execution on exceptions."""
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        @functools.wraps(func)
        def wrapper(*args: Any, **kwargs: Any) -> Dict[str, Any]:
            attempts = 0
            last_error = None
            for attempt in range(1, retries + 1):
                attempts = attempt
                try:
                    res = func(*args, **kwargs)
                    return {"success": True, "attempts": attempts, "result": res, "error": None}
                except Exception as err:
                    last_error = err
                    time.sleep(delay)
            return {"success": False, "attempts": attempts, "result": None, "error": str(last_error)}
        return wrapper
    return decorator

class ExecutionCounterDecorator:
    """Class-based decorator tracking invocation counts via __call__."""
    def __init__(self, func: Callable[..., Any]) -> None:
        self.func = func
        self.count = 0
        functools.update_wrapper(self, func)

    def __call__(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
        self.count += 1
        res = self.func(*args, **kwargs)
        return {"call_count": self.count, "output": res}

def decorator_patterns_and_wrappers(x: int, y: int) -> Dict[str, Any]:
    """Function decorators, parametrized decorators, class decorators, and metadata preservation."""
    if not isinstance(x, (int, float)) or not isinstance(y, (int, float)):
        raise TypeError("Inputs 'x' and 'y' must be valid numbers")

    @timer_decorator
    def sample_multiply(a: int, b: int) -> int:
        """Multiplies two numbers."""
        return a * b

    product_val, latency = sample_multiply(x, y)

    @retry_decorator(retries=2, delay=0.001)
    def flaky_divider(a: float, b: float) -> float:
        if b == 0:
            raise ZeroDivisionError("Division by zero in flaky_divider")
        return a / b

    retry_success = flaky_divider(x, y)
    retry_failure = flaky_divider(x, 0)

    @ExecutionCounterDecorator
    def adder(a: int, b: int) -> int:
        return a + b

    call_1 = adder(x, y)
    call_2 = adder(x, 10)

    return {
        "timer_result": product_val,
        "latency_measured": latency > 0,
        "wrapped_name": sample_multiply.__name__,
        "wrapped_doc": sample_multiply.__doc__,
        "has_wrapped_attr": hasattr(sample_multiply, "__wrapped__"),
        "retry_success": retry_success,
        "retry_failure": retry_failure,
        "class_decorator_call_1": call_1,
        "class_decorator_call_2": call_2,
    }

# 2. GENERATORS & BIDIRECTIONAL COROUTINES
def fibonacci_generator(limit: int) -> Generator[int, None, None]:
    a, b = 0, 1
    count = 0
    while count < limit:
        yield a
        a, b = b, a + b
        count += 1

def subgenerator_worker() -> Generator[str, None, str]:
    yield "Task Alpha"
    yield "Task Beta"
    return "Worker Complete"

def delegating_parent_generator() -> Generator[str, None, Dict[str, Any]]:
    yield "Header Start"
    worker_result = yield from subgenerator_worker()
    yield "Header End"
    return {"worker_summary": worker_result}

def interactive_accumulator() -> Generator[int, int, int]:
    total = 0
    while True:
        value = yield total
        if value is None:
            break
        total += value
    return total

def generator_mechanics_and_coroutines(limit: int = 5) -> Dict[str, Any]:
    """Yield, yield from subgenerator delegation, and bidirectional .send()."""
    if not isinstance(limit, int) or limit <= 0:
        raise ValueError("Input 'limit' must be a positive integer")

    fib_gen = fibonacci_generator(limit)
    fib_list = list(fib_gen)

    delegator = delegating_parent_generator()
    delegated_items: List[str] = []
    parent_summary = None
    while True:
        try:
            item = next(delegator)
            delegated_items.append(item)
        except StopIteration as stop_err:
            parent_summary = stop_err.value
            break

    accum = interactive_accumulator()
    next(accum)
    step1 = accum.send(10)
    step2 = accum.send(25)
    final_total = 0
    try:
        accum.send(None)
    except StopIteration as stop_err:
        final_total = stop_err.value

    gen_exp = (x ** 2 for x in range(1000))
    list_comp = [x ** 2 for x in range(1000)]

    return {
        "fibonacci_sequence": fib_list,
        "delegated_items": delegated_items,
        "parent_summary": parent_summary,
        "bidirectional_steps": [step1, step2],
        "final_accumulated_total": final_total,
        "gen_exp_size_bytes": sys.getsizeof(gen_exp),
        "list_comp_size_bytes": sys.getsizeof(list_comp),
    }

# 3. FUNCTOOLS: PARTIAL, LRU_CACHE & SINGLE DISPATCH
@functools.lru_cache(maxsize=128)
def cached_fibonacci(n: int) -> int:
    if n <= 1:
        return n
    return cached_fibonacci(n - 1) + cached_fibonacci(n - 2)

@functools.singledispatch
def process_data_payload(data: Any) -> str:
    return f"Generic payload handler: {type(data).__name__}"

@process_data_payload.register(int)
def _(data: int) -> str:
    return f"Integer payload handler: value={data * 2}"

@process_data_payload.register(list)
def _(data: list) -> str:
    return f"List payload handler: count={len(data)}, sum={sum(x for x in data if isinstance(x, (int, float)))}"

@process_data_payload.register(dict)
def _(data: dict) -> str:
    return f"Dict payload handler: keys={list(data.keys())}"

def functools_advanced_utilities(base_power: int = 2) -> Dict[str, Any]:
    """Functools.partial, lru_cache memoization, and singledispatch function overloading."""
    if not isinstance(base_power, int):
        raise TypeError("Input 'base_power' must be a valid integer")

    def power_calculator(base: int, exponent: int) -> int:
        return base ** exponent

    square_func = functools.partial(power_calculator, exponent=base_power)
    cube_func = functools.partial(power_calculator, exponent=3)

    sq_val = square_func(5)
    cb_val = cube_func(5)

    cached_fibonacci.cache_clear()
    fib_30 = cached_fibonacci(30)
    cache_stats = cached_fibonacci.cache_info()

    res_int = process_data_payload(42)
    res_list = process_data_payload([10, 20, 30])
    res_dict = process_data_payload({"name": "Dilshad", "role": "Engineer"})
    res_str = process_data_payload("Hello Python")

    return {
        "partial_square_5": sq_val,
        "partial_cube_5": cb_val,
        "partial_target_func": square_func.func.__name__,
        "partial_keywords": square_func.keywords,
        "cached_fib_30": fib_30,
        "cache_hits": cache_stats.hits,
        "cache_misses": cache_stats.misses,
        "cache_maxsize": cache_stats.maxsize,
        "singledispatch_int": res_int,
        "singledispatch_list": res_list,
        "singledispatch_dict": res_dict,
        "singledispatch_str": res_str,
    }

# 4. ASYNC COROUTINES & ASYNC GENERATORS
async def async_fetch_data(task_id: int, delay: float = 0.001) -> Dict[str, Any]:
    await asyncio.sleep(delay)
    return {"task_id": task_id, "status": "completed", "timestamp": time.time()}

async def async_stream_generator(count: int) -> AsyncGenerator[int, None]:
    for i in range(1, count + 1):
        await asyncio.sleep(0.001)
        yield i * 10

def async_coroutines_and_generators(task_count: int = 3) -> Dict[str, Any]:
    """Native async def / await coroutines and async stream generators via asyncio.run()."""
    if not isinstance(task_count, int) or task_count <= 0:
        raise ValueError("Input 'task_count' must be a positive integer")

    async def main_async_runner() -> Dict[str, Any]:
        tasks = [async_fetch_data(i) for i in range(1, task_count + 1)]
        coroutine_results = await asyncio.gather(*tasks)

        streamed_items: List[int] = []
        async for item in async_stream_generator(task_count):
            streamed_items.append(item)

        return {
            "coroutine_results": coroutine_results,
            "streamed_items": streamed_items,
        }

    return asyncio.run(main_async_runner())

# =========================================================================
# PYTHON METHODS BASICS & ADVANCED OBJECT METHOD PATTERNS
# Sourced & Standardized from DilshadPython/Python/Methods
# =========================================================================
import inspect
import sys
from typing import Any, Callable, Dict, List, Optional, Tuple, Union

class BankAccount:
    """Demonstrates instance method state encapsulation and defensive checks."""

    def __init__(self, account_holder: str, initial_balance: float = 0.0) -> None:
        if not isinstance(account_holder, str):
            raise TypeError("account_holder must be a valid string")
        if not isinstance(initial_balance, (int, float)):
            raise TypeError("initial_balance must be numeric")
        if initial_balance < 0:
            raise ValueError("initial_balance cannot be negative")

        self.account_holder: str = account_holder
        self._balance: float = float(initial_balance)
        self.transaction_history: List[str] = [f"Account opened with ${self._balance:.2f}"]

    def deposit(self, amount: float) -> float:
        """Instance method: Modifies instance state by adding funds."""
        if not isinstance(amount, (int, float)):
            raise TypeError("Deposit amount must be numeric")
        if amount <= 0:
            raise ValueError("Deposit amount must be greater than zero")

        self._balance += float(amount)
        self.transaction_history.append(f"Deposited ${amount:.2f}")
        return self._balance

    def withdraw(self, amount: float) -> float:
        """Instance method: Modifies instance state by withdrawing funds."""
        if not isinstance(amount, (int, float)):
            raise TypeError("Withdrawal amount must be numeric")
        if amount <= 0:
            raise ValueError("Withdrawal amount must be greater than zero")
        if amount > self._balance:
            raise ValueError(f"Insufficient funds: Balance is ${self._balance:.2f}")

        self._balance -= float(amount)
        self.transaction_history.append(f"Withdrew ${amount:.2f}")
        return self._balance

    def get_statement(self) -> Dict[str, Any]:
        """Instance method: Returns a structured summary of the account state."""
        return {
            "account_holder": self.account_holder,
            "current_balance": self._balance,
            "total_transactions": len(self.transaction_history),
            "recent_history": list(self.transaction_history),
        }

class UserProfile:
    """Demonstrates class methods (@classmethod) and static methods (@staticmethod)."""
    total_users_created: int = 0
    active_roles: List[str] = ["admin", "developer", "guest"]

    def __init__(self, username: str, role: str = "developer") -> None:
        self.username: str = username.strip()
        self.role: str = role.lower()
        UserProfile.total_users_created += 1

    @classmethod
    def from_csv_string(cls, csv_line: str) -> "UserProfile":
        """Class Method: Alternative constructor factory instantiating from CSV text."""
        parts = [p.strip() for p in csv_line.split(",")]
        username = parts[0]
        role = parts[1] if len(parts) > 1 else "developer"
        return cls(username=username, role=role)

    @classmethod
    def get_system_stats(cls) -> Dict[str, Any]:
        """Class Method: Accesses and reports class-level state."""
        return {
            "total_users": cls.total_users_created,
            "supported_roles": list(cls.active_roles),
            "class_name": cls.__name__,
        }

    @staticmethod
    def validate_username(username: str) -> bool:
        """Static Method: Utility function with no bound 'self' or 'cls' state."""
        if not isinstance(username, str):
            return False
        cleaned = username.strip()
        return len(cleaned) >= 3 and cleaned.replace("_", "").isalnum()

# =========================================================================
# PYTHON OBJECT-ORIENTED PROGRAMMING (OOP) BASICS & ARCHITECTURE
# Standardized from DilshadPython/Python/Object-Oriented
# =========================================================================
import abc
from typing import Any, Dict, List, Optional, Union

# 1. Class-and-Instance-Attribute
class CompanyEmployee:
    company_name: str = "TechCorp Solutions"
    total_employees: int = 0

    def __init__(self, emp_id: str, name: str, salary: float) -> None:
        self.emp_id = emp_id
        self.name = name
        self.salary = float(salary)
        CompanyEmployee.total_employees += 1

# 1B. Class-and-Instance-Data Reflection
class DataReflectionModel:
    data_version: str = "v2.4"
    instance_count: int = 0

    def __init__(self, record_id: str, payload: Dict[str, Any]) -> None:
        self.record_id = record_id
        self.payload = payload
        DataReflectionModel.instance_count += 1

    def inspect_public_attributes(self) -> List[str]:
        return [attr for attr in dir(self) if not attr.startswith("__")]

# 3. Encapsulation & Managed Properties
class BankAccountSecure:
    def __init__(self, owner: str, balance: float) -> None:
        self.owner = owner
        self._account_type = "Savings"
        self.__balance = 0.0
        self.balance = balance

    @property
    def balance(self) -> float:
        return self.__balance

    @balance.setter
    def balance(self, amount: float) -> None:
        if amount < 0:
            raise ValueError("Balance cannot be negative")
        self.__balance = float(amount)

# 5. MRO Multiple Inheritance
class SmartPhone(Camera, Phone):
    def turn_on(self) -> str:
        return f"SmartPhone Booting: [{super().turn_on()}]"