{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "e36c5842",
   "metadata": {},
   "source": [
    "# Tuples"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 128,
   "id": "7f2a0d34",
   "metadata": {
    "tags": [
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "# Course setup header — run this cell before the others\n",
    "\n",
    "import sys\n",
    "from pathlib import Path\n",
    "\n",
    "current = Path.cwd()\n",
    "for parent in [current, *current.parents]:\n",
    "    if (parent / '_config.yml').exists():\n",
    "        project_root = parent  # ← Add project root, not chapters\n",
    "        break\n",
    "else:\n",
    "    project_root = Path.cwd().parent.parent\n",
    "\n",
    "sys.path.insert(0, str(project_root))\n",
    "\n",
    "\n",
    "from shared import thinkpython, diagram, jupyturtle, download, structshape\n",
    "\n",
    "# Register as top-level modules so direct imports work in subsequent cells\n",
    "sys.modules['thinkpython'] = thinkpython\n",
    "sys.modules['diagram'] = diagram\n",
    "sys.modules['jupyturtle'] = jupyturtle\n",
    "sys.modules['download'] = download\n",
    "sys.modules['structshape'] = structshape\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d2434e1a",
   "metadata": {},
   "source": [
    "This chapter introduces tuples, a built-in **sequence** type, and shows how tuples work alongside lists and dictionaries.\n",
    "You will practice tuple assignment and the packing and unpacking operators used with variable-length argument lists.\n",
    "\n",
    "By the end of this chapter, you will be able to:\n",
    "\n",
    "1. Create tuples using literals, packing, and the tuple() constructor\n",
    "2. Unpack tuples (including starred unpacking) in assignments and loops\n",
    "3. Use zip(), enumerate(), divmod(), and other tuple-aware built-ins\n",
    "4. Choose between tuples and lists based on mutability needs\n",
    "5. Return multiple values from a function using tuples\n",
    "\n",
    "One note: There are two common pronunciations of \"tuple\".\n",
    "Some people say \"tuh-ple\" (rhymes with \"supple\").\n",
    "In programming, many people say \"too-ple\" (rhymes with \"quadruple\")."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "97514024",
   "metadata": {},
   "source": [
    "<h2>What is a Tuple?</h2>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e26428d",
   "metadata": {},
   "source": [
    "- A tuple is a **sequence** of values. \n",
    "- The values can be **any type**. \n",
    "- The values in a tuple are **indexed** by integers, so tuples feel a lot like lists.\n",
    "- When a **function** **returns** multiple values, it returns a tuple. \n",
    "- Tuples are **hashable** when all of their elements are hashable.\n",
    "\n",
    "Tuples are commonly used to group related values together. For example, a latitude and longitude pair naturally belongs together:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "2f0a602e",
   "metadata": {},
   "outputs": [],
   "source": [
    "location = (42.3601, -71.0589)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07a05aab",
   "metadata": {},
   "source": [
    "A tuple is a sequence, just like list. When the data belongs together and shouldn't change - like a coordinate, a date, or a name/age pair - use a tuple. If you need to add, remove, or modify items, use a list.\n",
    "| Feature    | Tuple          | List           |\n",
    "|------------|----------------|----------------|\n",
    "| Syntax     | `(1, 2, 3)`    | `[1, 2, 3]`    |\n",
    "| Mutable    | No             | Yes            |\n",
    "| Hashable   | Yes (conditional) | No          |\n",
    "| Methods    | 2 (`.count`, `.index`) | Many  |\n",
    "| Use case   | Fixed data, records | Collections that change |\n",
    "| Performance | Faster        | Slower         |"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf60e652",
   "metadata": {},
   "source": [
    "<h2>Immutability</h2>\n",
    "\n",
    "Tuples are **immutable**, which is the key characteristic of tuples. Once created, items cannot be added, removed, or changed within a tuple, but new tuples can be created as a result of operations. That's why tuples lack list methods that modify in place, like `append` and `remove`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b95bc71d",
   "metadata": {},
   "source": [
    "If you try to modify a tuple with indexing, Python raises a `TypeError`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ca1483cf",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%expect TypeError\n",
    "invoice_key = (\"INV-2026-0142\", \"ACME\", \"2026-02-28\")\n",
    "print(\"Invoice key[0]:\", invoice_key[0])\n",
    "\n",
    "invoice_key[0] = \"INV-2026-0143\" # Tuple does not support item assignment\n"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}