{ "cells": [ { "cell_type": "markdown", "id": "0", "metadata": {}, "source": [ "---\n", "title: \"Chapter 3: Functions\"\n", "---" ] }, { "cell_type": "markdown", "id": "1", "metadata": {}, "source": [ "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/sambaiga/ds-mlops-path/blob/main/tutorials/01-python-basics/03-functions.ipynb) [![Download Notebook](https://img.shields.io/badge/Download-Notebook-blue.svg?logo=jupyter&logoColor=white)](https://raw.githubusercontent.com/sambaiga/ds-mlops-path/main/tutorials/01-python-basics/03-functions.ipynb)" ] }, { "cell_type": "markdown", "id": "2", "metadata": {}, "source": [ "Your grade-analysis pipeline normalises exam scores, flags outliers, and computes pass rates. The normalisation formula appears in three places in the same file. A month later you discover the threshold was wrong. You fix it in two places. The third copy, buried in the export section, stays wrong. The report ships with incorrect numbers.\n", "\n", "A function solves this. You write the logic once, give it a name, and call it from anywhere. Chapter 2 put your programs in motion with decisions and loops; this chapter adds naming so that motion can be reused. The energy theft detector you are building by Chapter 27 will need dozens of these named calculations: parse a meter reading, flag a threshold breach, compute a rolling mean. This chapter is where you learn to write them.\n", "\n", "By the end you will write functions that accept any number of arguments, use standard library modules, and return structured results. Chapter 4 (`04-classes.ipynb`) takes this further: it shows how to bundle functions and the data they operate on into a single named object, called a class." ] }, { "cell_type": "markdown", "id": "3", "metadata": {}, "source": [ "::: {.callout-note collapse=\"true\" icon=false}\n", "## Learning objectives\n", "\n", "By the end of Chapter 3 you will be able to:\n", "\n", "| # | Skill | Covered in |\n", "|---|---|---|\n", "| 1 | Define functions with positional, default, and keyword-only parameters | Sec. 1 |\n", "| 2 | Write Google-style docstrings | Sec. 1 |\n", "| 3 | Use lambda expressions as sort keys and with `map()` / `filter()` | Sec. 2 |\n", "| 4 | Accept variable arguments with `*args` and `**kwargs` | Sec. 3 |\n", "| 5 | Use `math`, `json`, and `datetime` from the standard library | Sec. 4 |\n", ":::" ] }, { "cell_type": "markdown", "id": "4", "metadata": {}, "source": [ "## 1. Functions\n", "\n", "You need to compute a weighted grade. You could write the arithmetic inline every time you need it, but the day the weighting changes you have to find and update every copy.\n", "\n", "A function wraps that arithmetic under a name. Write it once; call it anywhere.\n", "\n", "![The anatomy of a Python function definition: keyword, name, typed parameters, defaults, and return type.](figs/function-anatomy.svg){fig-alt=\"Labeled diagram of a def statement showing the def keyword, function name, parameters with type hints, a default value, and the return type annotation.\"}" ] }, { "cell_type": "markdown", "id": "5", "metadata": {}, "source": [ "
\n", " Key Concept: function anatomy

\n", "def name(param: type, param2: type = default) -> return_type:

\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "6", "metadata": {}, "source": [ "Start with the simplest possible function: one input, one output, nothing else:" ] }, { "cell_type": "code", "execution_count": null, "id": "7", "metadata": {}, "outputs": [], "source": [ "def greet(name: str) -> str:\n", " return f\"Hello, {name}!\"\n", "\n", "\n", "print(greet(\"Alice\"))\n", "print(greet(\"Dr. Mwangi\"))" ] }, { "cell_type": "markdown", "id": "8", "metadata": {}, "source": [ "Add a second parameter. A caller who provides both gets the explicit greeting; a caller who provides only the name gets a sensible default:" ] }, { "cell_type": "code", "execution_count": null, "id": "9", "metadata": {}, "outputs": [], "source": [ "def greet(name: str, greeting: str = \"Hello\") -> str:\n", " return f\"{greeting}, {name}!\"\n", "\n", "\n", "print(greet(\"Alice\"))\n", "print(greet(\"Dr. Mwangi\", greeting=\"Good morning\"))" ] }, { "cell_type": "markdown", "id": "10", "metadata": {}, "source": [ "### Docstrings\n", "\n", "A **docstring** is a string literal placed as the first statement of a function. It explains what the function does, what its inputs mean, and what it returns. IDEs, the built-in `help()`, and documentation generators all read it automatically." ] }, { "cell_type": "markdown", "id": "11", "metadata": {}, "source": [ "
\n", " Key Concept: Google-style docstrings

\n", "The Google style is the most readable for short functions:

\n", "
def fn(x: float, y: float) -> float:\n",
    "    \"\"\"One-sentence summary.\n",
    "\n",
    "    Args:\n",
    "        x: What x means.\n",
    "        y: What y means.\n",
    "\n",
    "    Returns:\n",
    "        What the function produces.\n",
    "    \"\"\"\n",
    "    ...
\n", "
" ] }, { "cell_type": "markdown", "id": "12", "metadata": {}, "source": [ "Now build a real function using all four elements: multiple typed parameters, a default value, a docstring, and a return type.\n", "\n", "This function calculates a weighted grade. The weights default to a 30/50/20 split but any caller can override them:" ] }, { "cell_type": "code", "execution_count": null, "id": "13", "metadata": {}, "outputs": [], "source": [ "def weighted_grade(\n", " midterm: float,\n", " final: float,\n", " project: float,\n", " weights: tuple[float, float, float] = (0.30, 0.50, 0.20),\n", ") -> float:\n", " \"\"\"Return the weighted average of three assessment scores.\n", "\n", " Args:\n", " midterm: Midterm exam score (0-100).\n", " final: Final exam score (0-100).\n", " project: Project score (0-100).\n", " weights: Three weights summing to 1.0.\n", "\n", " Returns:\n", " Weighted average rounded to two decimal places, or 0.0 for invalid weights.\n", " \"\"\"\n", " if abs(sum(weights) - 1.0) > 0.001:\n", " return 0.0\n", " return round(midterm * weights[0] + final * weights[1] + project * weights[2], 2)" ] }, { "cell_type": "markdown", "id": "14", "metadata": {}, "source": [ "Call with default weights, then override them. Keyword arguments make each call self-documenting:" ] }, { "cell_type": "code", "execution_count": null, "id": "15", "metadata": {}, "outputs": [], "source": [ "grade_default = weighted_grade(midterm=82.0, final=91.0, project=88.0)\n", "grade_custom = weighted_grade(\n", " midterm=82.0,\n", " final=91.0,\n", " project=88.0,\n", " weights=(0.25, 0.50, 0.25),\n", ")\n", "\n", "print(f\"Default weights : {grade_default}\")\n", "print(f\"Custom weights : {grade_custom}\")" ] }, { "cell_type": "markdown", "id": "16", "metadata": {}, "source": [ "### Multiple return values\n", "\n", "A function can return more than one value by packing them into a tuple. The caller unpacks them in one line:" ] }, { "cell_type": "code", "execution_count": null, "id": "17", "metadata": {}, "outputs": [], "source": [ "def score_summary(scores: list[float]) -> tuple[float, float, float, float]:\n", " \"\"\"Return (mean, min, max, std) for a list of scores.\n", "\n", " Args:\n", " scores: List of numeric scores.\n", "\n", " Returns:\n", " Tuple of (mean, minimum, maximum, standard deviation).\n", " Returns four zeros for an empty list.\n", " \"\"\"\n", " if not scores:\n", " return (0.0, 0.0, 0.0, 0.0)\n", " n = len(scores)\n", " mean = sum(scores) / n\n", " lo = min(scores)\n", " hi = max(scores)\n", " std = (sum((x - mean) ** 2 for x in scores) / n) ** 0.5\n", " return (mean, lo, hi, std)" ] }, { "cell_type": "markdown", "id": "18", "metadata": {}, "source": [ "Unpack the four return values into named variables in one assignment:" ] }, { "cell_type": "code", "execution_count": null, "id": "19", "metadata": {}, "outputs": [], "source": [ "exam_scores: list[float] = [78.0, 85.5, 92.0, 88.5, 95.0, 67.0, 81.0]\n", "mean, lo, hi, std = score_summary(exam_scores)\n", "\n", "print(f\"Mean : {mean:.1f}\")\n", "print(f\"Range : {lo:.1f} to {hi:.1f}\")\n", "print(f\"Std : {std:.2f}\")" ] }, { "cell_type": "markdown", "id": "20", "metadata": {}, "source": [ "### Normalisation\n", "\n", "Z-score normalisation rescales each score by how many standard deviations it sits from the mean. The result is 0.0 for an exactly average score, positive above the mean, negative below." ] }, { "cell_type": "code", "execution_count": null, "id": "21", "metadata": {}, "outputs": [], "source": [ "def normalize(value: float, mean: float, std: float) -> float:\n", " \"\"\"Return the z-score of value given distribution parameters.\n", "\n", " Args:\n", " value: The raw score to normalise.\n", " mean: Distribution mean.\n", " std: Distribution standard deviation.\n", "\n", " Returns:\n", " Z-score, or 0.0 if std is zero.\n", " \"\"\"\n", " if std == 0.0:\n", " return 0.0\n", " return (value - mean) / std" ] }, { "cell_type": "markdown", "id": "22", "metadata": {}, "source": [ "Compute the distribution parameters inline, then apply normalisation to every score:" ] }, { "cell_type": "code", "execution_count": null, "id": "23", "metadata": {}, "outputs": [], "source": [ "exam_scores: list[float] = [72.0, 85.0, 91.0, 68.0, 88.0, 77.0, 94.0, 63.0]\n", "\n", "n = len(exam_scores)\n", "mu = sum(exam_scores) / n\n", "sig = (sum((x - mu) ** 2 for x in exam_scores) / n) ** 0.5\n", "\n", "normalised = [normalize(s, mu, sig) for s in exam_scores]\n", "\n", "for raw, z in zip(exam_scores, normalised, strict=False):\n", " bar = \"#\" * max(0, round((z + 3) * 5))\n", " print(f\" {raw:5.1f} z={z:+.2f} {bar}\")" ] }, { "cell_type": "markdown", "id": "24", "metadata": {}, "source": [ "
\n", " Common Mistake: mutable default arguments

\n", "Never use a list, dict, or any other mutable object as a default parameter value. Python creates the default object once when the function is defined, not each time it is called. Every call that uses the default shares the same object.

\n", "Wrong: def add_score(score, history=[]):
\n", "Right: use None as the sentinel and create the list inside the function body when history is None.\n", "
" ] }, { "cell_type": "markdown", "id": "25", "metadata": {}, "source": [ "This is the bug in action: two independent calls share the same default list:" ] }, { "cell_type": "code", "execution_count": null, "id": "26", "metadata": {}, "outputs": [], "source": [ "def add_score_bad(score: float, history: list[float] = []) -> list[float]: # noqa: B006\n", " history.append(score)\n", " return history\n", "\n", "\n", "# These look independent but share the same default list\n", "first = add_score_bad(88.0)\n", "second = add_score_bad(91.0)\n", "\n", "print(f\"first : {first}\") # [88.0, 91.0], not [88.0]\n", "print(f\"second : {second}\") # [88.0, 91.0], not [91.0]" ] }, { "cell_type": "markdown", "id": "27", "metadata": {}, "source": [ "Fix it by using `None` as the sentinel and creating a fresh list inside the function:" ] }, { "cell_type": "code", "execution_count": null, "id": "28", "metadata": {}, "outputs": [], "source": [ "def add_score(score: float, history: list[float] | None = None) -> list[float]:\n", " if history is None:\n", " history = []\n", " history.append(score)\n", " return history\n", "\n", "\n", "first = add_score(88.0)\n", "second = add_score(91.0)\n", "\n", "print(f\"first : {first}\") # [88.0]\n", "print(f\"second : {second}\") # [91.0]" ] }, { "cell_type": "markdown", "id": "29", "metadata": {}, "source": [ "
\n", " Activity: grade_letter

\n", "Complete grade_letter: it takes a numeric score and returns the letter grade.

\n", "Letter grades: A = 90+, B = 80-89, C = 70-79, D = 60-69, F = below 60.\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "30", "metadata": {}, "outputs": [], "source": [ "def grade_letter(score: float) -> str:\n", " \"\"\"Return the letter grade for a numeric score.\"\"\"\n", " return ... # TODO: implement\n", "\n", "\n", "print(grade_letter(92.0)) # expected: A\n", "print(grade_letter(75.0)) # expected: C" ] }, { "cell_type": "markdown", "id": "31", "metadata": {}, "source": [ "
\n", " Activity: classify_cohort

\n", "Complete classify_cohort: it takes a list of scores and returns a Counter mapping each letter grade to the number of students who earned it. Use grade_letter from the cell above.\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "32", "metadata": {}, "outputs": [], "source": [ "from collections import Counter\n", "\n", "\n", "def classify_cohort(scores: list[float]) -> Counter[str]:\n", " \"\"\"Return a Counter mapping letter grades to student counts.\"\"\"\n", " return ... # TODO: implement\n", "\n", "\n", "cohort = [88.0, 73.5, 55.0, 91.0, 67.0, 82.0, 95.5, 78.0, 61.0, 84.0]\n", "distribution = classify_cohort(cohort)\n", "if distribution is not ...:\n", " for grade in \"ABCDF\":\n", " print(f\"{grade}: {distribution.get(grade, 0)}\")" ] }, { "cell_type": "markdown", "id": "33", "metadata": {}, "source": [ "
\n", " Activity: accept_login

\n", "Complete accept_login: it checks a username and password against a dict of approved users and returns True if both match, False otherwise.\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "34", "metadata": {}, "outputs": [], "source": [ "def accept_login(users: dict[str, str], username: str, password: str) -> bool:\n", " \"\"\"Return True if username exists and password matches.\n", "\n", " Args:\n", " users: Mapping of username to hashed password.\n", " username: The submitted username.\n", " password: The submitted password.\n", "\n", " Returns:\n", " True on success, False on any mismatch.\n", " \"\"\"\n", " return ... # TODO: implement\n", "\n", "\n", "approved: dict[str, str] = {\"alice\": \"s3cr3t\", \"bob\": \"pa$$w0rd\"}\n", "\n", "if accept_login(approved, \"alice\", \"s3cr3t\") is not ...:\n", " print(accept_login(approved, \"alice\", \"s3cr3t\")) # True\n", " print(accept_login(approved, \"alice\", \"wrong\")) # False\n", " print(accept_login(approved, \"carol\", \"s3cr3t\")) # False" ] }, { "cell_type": "markdown", "id": "35", "metadata": {}, "source": [ "## 2. Lambda functions\n", "\n", "A **lambda** is an anonymous function defined in a single expression. It takes inputs on the left of `:` and produces a result on the right." ] }, { "cell_type": "markdown", "id": "36", "metadata": {}, "source": [ "
\n", " Key Concept: when to use a lambda

\n", "Use a lambda when you need a throwaway function in one place: a sort key, a map() transform, or a filter() predicate. If the logic is more than one expression, or if you need it in more than one place, write a named function instead.\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "37", "metadata": {}, "outputs": [], "source": [ "# Lambda syntax: lambda params: expression\n", "square = lambda x: x**2 # noqa: E731\n", "print(f\"square(5) = {square(5)}\")" ] }, { "cell_type": "markdown", "id": "38", "metadata": {}, "source": [ "A lambda can take multiple parameters and include logic. `clamp` restricts a value to a range using `max` and `min`:" ] }, { "cell_type": "code", "execution_count": null, "id": "39", "metadata": {}, "outputs": [], "source": [ "clamp = lambda x, lo, hi: max(lo, min(x, hi)) # noqa: E731\n", "print(f\"clamp(115, 0, 100) = {clamp(115, 0, 100)}\")" ] }, { "cell_type": "markdown", "id": "40", "metadata": {}, "source": [ "The most common use for lambdas is as a **sort key**: a function that extracts the comparison value from each element:" ] }, { "cell_type": "code", "execution_count": null, "id": "41", "metadata": {}, "outputs": [], "source": [ "students: list[dict[str, object]] = [\n", " {\"name\": \"Alice\", \"gpa\": 3.95, \"major\": \"CS\"},\n", " {\"name\": \"Bob\", \"gpa\": 2.80, \"major\": \"Math\"},\n", " {\"name\": \"Carol\", \"gpa\": 3.40, \"major\": \"Physics\"},\n", " {\"name\": \"Dan\", \"gpa\": 3.70, \"major\": \"CS\"},\n", "]\n", "\n", "# Sort by GPA descending\n", "by_gpa = sorted(students, key=lambda s: s[\"gpa\"], reverse=True)\n", "\n", "for s in by_gpa:\n", " print(f\"{s['name']:<8} GPA={s['gpa']}\")" ] }, { "cell_type": "markdown", "id": "42", "metadata": {}, "source": [ "### map() and filter()\n", "\n", "`map(func, iterable)` applies `func` to every element and returns a lazy iterator. Wrap with `list()` to materialise the result:" ] }, { "cell_type": "code", "execution_count": null, "id": "43", "metadata": {}, "outputs": [], "source": [ "raw_scores: list[str] = [\"78.5\", \"85.0\", \"92.3\", \"61.0\", \"88.7\"]\n", "\n", "# Convert strings to floats\n", "scores: list[float] = list(map(float, raw_scores))\n", "print(f\"Parsed: {scores}\")" ] }, { "cell_type": "markdown", "id": "44", "metadata": {}, "source": [ "`filter(func, iterable)` keeps only elements where `func` returns `True`. Equivalent to a comprehension with an `if` clause, but more expressive with a named predicate:" ] }, { "cell_type": "code", "execution_count": null, "id": "45", "metadata": {}, "outputs": [], "source": [ "# Keep only passing scores (>= 70)\n", "passing: list[float] = list(filter(lambda s: s >= 70, scores))\n", "print(f\"Passing: {passing}\")\n", "\n", "# Same result as a comprehension\n", "passing_comp = [s for s in scores if s >= 70]\n", "print(f\"Match: {passing == passing_comp}\")" ] }, { "cell_type": "markdown", "id": "46", "metadata": {}, "source": [ "
\n", " Activity: top students by GPA

\n", "Using filter and sorted, write a one-liner that returns the names of students with GPA >= 3.5, sorted by GPA descending.\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "47", "metadata": {}, "outputs": [], "source": [ "students: list[dict[str, object]] = [\n", " {\"name\": \"Alice\", \"gpa\": 3.95, \"major\": \"CS\"},\n", " {\"name\": \"Bob\", \"gpa\": 2.80, \"major\": \"Math\"},\n", " {\"name\": \"Carol\", \"gpa\": 3.40, \"major\": \"Physics\"},\n", " {\"name\": \"Dan\", \"gpa\": 3.70, \"major\": \"CS\"},\n", "]\n", "\n", "# TODO: one expression using filter + sorted\n", "top: list[str] = ...\n", "\n", "if top is not ...:\n", " print(top) # ['Alice', 'Dan']" ] }, { "cell_type": "markdown", "id": "48", "metadata": {}, "source": [ "## 3. *args and **kwargs\n", "\n", "A fixed signature only works when you know the number of arguments in advance. Sometimes the caller decides how many score lists to aggregate, or which attributes to attach to a student profile." ] }, { "cell_type": "markdown", "id": "49", "metadata": {}, "source": [ "
\n", " Key Concept: *args and **kwargs

\n", "*args collects any number of positional arguments into a tuple.
\n", "**kwargs collects any number of keyword arguments into a dict.

\n", "Neither name is magic: *scores or **attrs work equally well. The * and ** are what matter.\n", "
" ] }, { "cell_type": "markdown", "id": "50", "metadata": {}, "source": [ "`*args` lets callers pass one list, three lists, or unpack a list of lists without changing the function signature:" ] }, { "cell_type": "code", "execution_count": null, "id": "51", "metadata": {}, "outputs": [], "source": [ "def aggregate_scores(*score_lists: list[float]) -> float:\n", " \"\"\"Return the mean of all scores across any number of lists.\n", "\n", " Args:\n", " *score_lists: One or more lists of numeric scores.\n", "\n", " Returns:\n", " Overall mean, or 0.0 if no scores were provided.\n", " \"\"\"\n", " all_scores = [s for lst in score_lists for s in lst]\n", " if not all_scores:\n", " return 0.0\n", " return round(sum(all_scores) / len(all_scores), 2)" ] }, { "cell_type": "markdown", "id": "52", "metadata": {}, "source": [ "Call with one list, multiple lists, or unpack with `*`. The function handles all three cases the same way:" ] }, { "cell_type": "code", "execution_count": null, "id": "53", "metadata": {}, "outputs": [], "source": [ "midterms: list[float] = [78.0, 85.0, 91.0]\n", "finals: list[float] = [82.0, 88.0, 94.0]\n", "projects: list[float] = [90.0, 87.0, 92.0]\n", "\n", "print(aggregate_scores(midterms))\n", "print(aggregate_scores(midterms, finals))\n", "print(aggregate_scores(midterms, finals, projects))" ] }, { "cell_type": "markdown", "id": "54", "metadata": {}, "source": [ "`**kwargs` collects any number of keyword arguments into a dict. It is useful when you want to build a record from whatever attributes the caller provides:" ] }, { "cell_type": "code", "execution_count": null, "id": "55", "metadata": {}, "outputs": [], "source": [ "def build_student_profile(student_id: str, **attributes: object) -> dict[str, object]:\n", " \"\"\"Build a student profile dict from keyword attributes.\n", "\n", " Args:\n", " student_id: Unique student identifier.\n", " **attributes: Any additional fields to attach.\n", "\n", " Returns:\n", " Dict with student_id plus all provided attributes.\n", " \"\"\"\n", " return {\"student_id\": student_id, **attributes}" ] }, { "cell_type": "markdown", "id": "56", "metadata": {}, "source": [ "Pass any combination of keyword arguments. `**` also unpacks a dict at the call site:" ] }, { "cell_type": "code", "execution_count": null, "id": "57", "metadata": {}, "outputs": [], "source": [ "p1 = build_student_profile(\"S1042\", name=\"Alice\", gpa=3.95, major=\"CS\")\n", "p2 = build_student_profile(\"S1043\", name=\"Bob\", gpa=2.80)\n", "\n", "extra = {\"program\": \"exchange\", \"cohort\": 2024}\n", "p3 = build_student_profile(\"S1044\", name=\"Carol\", **extra)\n", "\n", "for p in (p1, p2, p3):\n", " print(p)" ] }, { "cell_type": "markdown", "id": "58", "metadata": {}, "source": [ "You can combine all four argument forms in one signature: fixed positional, `*args`, keyword-only (must be named at the call site), and `**kwargs`:" ] }, { "cell_type": "code", "execution_count": null, "id": "59", "metadata": {}, "outputs": [], "source": [ "def log_cohort_stats(\n", " semester: str,\n", " *courses: str,\n", " verbose: bool = False,\n", " **metrics: float,\n", ") -> dict[str, object]:\n", " \"\"\"Log and return stats for a semester cohort.\n", "\n", " Args:\n", " semester: Semester label, e.g. \"2024-S1\".\n", " *courses: Course codes included in this run.\n", " verbose: If True, print each metric.\n", " **metrics: Named statistics to record.\n", "\n", " Returns:\n", " Dict with semester, courses, and metrics.\n", " \"\"\"\n", " record: dict[str, object] = {\n", " \"semester\": semester,\n", " \"courses\": list(courses),\n", " \"metrics\": metrics,\n", " }\n", " if verbose:\n", " for key, val in metrics.items():\n", " print(f\" {key}: {val:.3f}\")\n", " return record" ] }, { "cell_type": "markdown", "id": "60", "metadata": {}, "source": [ "`verbose` is keyword-only: it cannot be passed positionally because `*courses` comes before it in the signature:" ] }, { "cell_type": "code", "execution_count": null, "id": "61", "metadata": {}, "outputs": [], "source": [ "result = log_cohort_stats(\n", " \"2024-S1\",\n", " \"CS101\",\n", " \"MATH201\",\n", " verbose=True,\n", " pass_rate=0.821,\n", " mean_gpa=3.12,\n", " median_score=74.5,\n", ")\n", "print(result)" ] }, { "cell_type": "markdown", "id": "62", "metadata": {}, "source": [ "
\n", " Activity: add a timestamp

\n", "Extend log_cohort_stats to also include a timestamp key in the returned dict. Use datetime.now(tz=UTC) from the datetime module and format it with .isoformat().\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "63", "metadata": {}, "outputs": [], "source": [ "from datetime import UTC, datetime\n", "\n", "\n", "def log_cohort_stats_v2(\n", " semester: str,\n", " *courses: str,\n", " verbose: bool = False,\n", " **metrics: float,\n", ") -> dict[str, object]:\n", " \"\"\"Extended version: adds a UTC timestamp to the returned record.\"\"\"\n", " return ... # TODO: reuse log_cohort_stats logic and add timestamp\n", "\n", "\n", "result = log_cohort_stats_v2(\"2024-S1\", \"CS101\", pass_rate=0.821)\n", "if result is not ...:\n", " print(result.get(\"timestamp\", \"missing\"))" ] }, { "cell_type": "markdown", "id": "64", "metadata": {}, "source": [ "## 4. Modules and the standard library\n", "\n", "A **module** is a Python file. When you write `import math`, Python loads `math.py` from the standard library and makes its contents available. No installation needed: these modules ship with every Python installation." ] }, { "cell_type": "markdown", "id": "65", "metadata": {}, "source": [ "
\n", " Key Concept: importing from a module

\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "66", "metadata": {}, "source": [ "The `math` module provides precise arithmetic for single numeric values:" ] }, { "cell_type": "code", "execution_count": null, "id": "67", "metadata": {}, "outputs": [], "source": [ "import math\n", "\n", "print(f\"pi = {math.pi:.6f}\")\n", "print(f\"e = {math.e:.6f}\")\n", "print(f\"sqrt(2) = {math.sqrt(2):.6f}\")\n", "print(f\"log10(1000) = {math.log10(1000)}\")\n", "print(f\"ceil(4.2) = {math.ceil(4.2)}\")\n", "print(f\"floor(4.8) = {math.floor(4.8)}\")\n", "print(f\"isnan(0.0) = {math.isnan(0.0)}\")\n", "print(f\"isinf(1e400) = {math.isinf(1e400)}\")" ] }, { "cell_type": "markdown", "id": "68", "metadata": {}, "source": [ "`json` converts Python dicts, lists, and primitives to JSON strings and back. It is the standard format for saving run configs and logging result metadata:" ] }, { "cell_type": "code", "execution_count": null, "id": "69", "metadata": {}, "outputs": [], "source": [ "import json\n", "\n", "run_result: dict[str, object] = {\n", " \"run_id\": \"2024-S1-001\",\n", " \"course\": \"CS101\",\n", " \"pass_rate\": 0.821,\n", " \"mean_score\": 74.5,\n", " \"flags\": [\"regrade\", \"audit\"],\n", "}\n", "\n", "serialised = json.dumps(run_result, indent=2)\n", "print(serialised)" ] }, { "cell_type": "markdown", "id": "70", "metadata": {}, "source": [ "`json.loads` reverses the operation: it parses a JSON string back into a Python dict:" ] }, { "cell_type": "code", "execution_count": null, "id": "71", "metadata": {}, "outputs": [], "source": [ "# JSON string back to Python dict\n", "loaded: dict[str, object] = json.loads(serialised)\n", "print(f\"pass_rate : {loaded['pass_rate']}\")\n", "print(f\"flags : {loaded['flags']}\")" ] }, { "cell_type": "markdown", "id": "72", "metadata": {}, "source": [ "`datetime` represents a point in time. Always attach `timezone.utc` to avoid ambiguous naive datetime objects that can silently shift across time zones:" ] }, { "cell_type": "code", "execution_count": null, "id": "73", "metadata": {}, "outputs": [], "source": [ "now = datetime.now(tz=UTC)\n", "print(f\"Timestamp : {now.isoformat()}\")\n", "print(f\"Date part : {now.strftime('%Y-%m-%d')}\")\n", "print(f\"Year : {now.year}\")\n", "print(f\"Unix epoch : {now.timestamp():.0f}\")" ] }, { "cell_type": "markdown", "id": "74", "metadata": {}, "source": [ "## Capstone exercises\n", "\n", "These exercises use everything from sections 1-4. Each is self-contained." ] }, { "cell_type": "markdown", "id": "75", "metadata": {}, "source": [ "
\n", " Activity: student record processor

\n", "Write a function process_records(rows) that takes a list of raw row dicts (each has name, scores as a list of floats, and major) and returns a list of summary dicts with keys: name, major, mean, grade.

\n", "Use score_summary from Section 1 to get the mean, and grade_letter from Activity 1 to get the grade.\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "76", "metadata": {}, "outputs": [], "source": [ "def process_records(\n", " rows: list[dict[str, object]],\n", ") -> list[dict[str, object]]:\n", " \"\"\"Summarise a list of raw student rows.\n", "\n", " Args:\n", " rows: Each dict has \"name\", \"scores\", and \"major\".\n", "\n", " Returns:\n", " List of summary dicts with name, major, mean, grade.\n", " \"\"\"\n", " return ... # TODO: implement\n", "\n", "\n", "students: list[dict[str, object]] = [\n", " {\"name\": \"Alice\", \"scores\": [88.0, 92.0, 85.0], \"major\": \"CS\"},\n", " {\"name\": \"Bob\", \"scores\": [62.0, 70.0, 58.0], \"major\": \"Math\"},\n", " {\"name\": \"Carol\", \"scores\": [91.0, 94.0, 89.0], \"major\": \"Physics\"},\n", " {\"name\": \"Dan\", \"scores\": [74.0, 68.0, 71.0], \"major\": \"CS\"},\n", "]\n", "\n", "result = process_records(students)\n", "if result is not ...:\n", " for r in result:\n", " print(f\"{r['name']:<8} {r['major']:<10} mean={r['mean']:.1f} {r['grade']}\")" ] }, { "cell_type": "markdown", "id": "77", "metadata": {}, "source": [ "
\n", " Activity: moving window average

\n", "Complete moving_window_average: it replaces each value with the mean of the values within n_neighbors positions on each side. Edge values use whatever neighbors are available.\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "78", "metadata": {}, "outputs": [], "source": [ "def moving_window_average(x: list[float], n_neighbors: int = 1) -> list[float]:\n", " \"\"\"Replace each value with the mean of its n_neighbors on each side.\n", "\n", " Args:\n", " x: Input list of numeric values.\n", " n_neighbors: Window half-width.\n", "\n", " Returns:\n", " Smoothed list of the same length as x.\n", " \"\"\"\n", " return ... # TODO: implement\n", "\n", "\n", "readings: list[float] = [36.5, 36.7, 36.8, 36.6, 36.9, 39.5, 36.7, 36.8]\n", "smoothed = moving_window_average(readings, n_neighbors=2)\n", "if smoothed is not ...:\n", " for raw, sm in zip(readings, smoothed, strict=False):\n", " print(f\"{raw:.1f} -> {sm:.2f}\")" ] }, { "cell_type": "markdown", "id": "79", "metadata": {}, "source": [ "## Further reading\n", "\n", "| Resource | Why it matters |\n", "|---|---|\n", "| [PEP 484: Type Hints](https://peps.python.org/pep-0484/) | The original proposal; reading it explains why certain annotation rules exist |\n", "| [PEP 257: Docstring Conventions](https://peps.python.org/pep-0257/) | The standard for what goes in a docstring |\n", "| [Google Python Style Guide: Functions](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods) | The docstring format used throughout this book |\n", "| [Real Python: Lambda Functions](https://realpython.com/python-lambda/) | Covers every edge case, including when NOT to use lambdas |\n", "| [Python `functools` docs](https://docs.python.org/3/library/functools.html) | `partial`, `lru_cache`, `reduce`: the tools that build on what this chapter covers |" ] }, { "cell_type": "markdown", "id": "80", "metadata": {}, "source": [ "## Summary\n", "\n", "| Concept | Key rule |\n", "|---|---|\n", "| Functions | Annotate all params and return types; use Google-style docstrings |\n", "| Defaults | Never use a mutable object as a default; use `None` and create inside |\n", "| Multiple returns | Pack into a tuple; unpack with `a, b = fn()` |\n", "| Lambda | One expression, one place; write a named function for anything more |\n", "| `*args` | Collects positional arguments into a tuple |\n", "| `**kwargs` | Collects keyword arguments into a dict |\n", "| Standard library | `math` for precise arithmetic; `json` for serialisation; `datetime` for timestamps |\n", "\n", "**Next:** [Chapter 4: Classes and patterns](04-classes.ipynb): how to bundle functions and the data they operate on into a single named object." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python", "version": "3.12.0" } }, "nbformat": 4, "nbformat_minor": 5 }