KuRRe8 · June 22, 2025 09:09 · KuRRe8 · May 8, 2025
diff --git a/_intro.md b/_intro.md
diff --git a/app_deploy_tutorial.ipynb b/app_deploy_tutorial.ipynb
diff --git a/asyncio_tutorial.ipynb b/asyncio_tutorial.ipynb
diff --git a/boosting_libs_tutorial.ipynb b/boosting_libs_tutorial.ipynb
diff --git a/c_extensions_tutorial.ipynb b/c_extensions_tutorial.ipynb
diff --git a/concurrency_tutorial.ipynb b/concurrency_tutorial.ipynb
diff --git a/context_managers_tutorial.ipynb b/context_managers_tutorial.ipynb
diff --git a/descriptor.md b/descriptor.md
diff --git a/design_patterns_tutorial.ipynb b/design_patterns_tutorial.ipynb
diff --git a/dunder_methods_tutorial.ipynb b/dunder_methods_tutorial.ipynb
diff --git a/experiment_tracking_tutorial.ipynb b/experiment_tracking_tutorial.ipynb
diff --git a/faiss_tutorial.ipynb b/faiss_tutorial.ipynb
diff --git a/generics_tutorial.ipynb b/generics_tutorial.ipynb
diff --git a/gymnasium_tutorial.ipynb b/gymnasium_tutorial.ipynb
diff --git a/hpo_tutorial.ipynb b/hpo_tutorial.ipynb
diff --git a/iterators_generators_tutorial.ipynb b/iterators_generators_tutorial.ipynb
diff --git a/langchain_tutorial.ipynb b/langchain_tutorial.ipynb
diff --git a/llamaindex_tutorial.ipynb b/llamaindex_tutorial.ipynb
diff --git a/matplotlib_tutorial.ipynb b/matplotlib_tutorial.ipynb
diff --git a/metaprogramming_tutorial.ipynb b/metaprogramming_tutorial.ipynb
diff --git a/numpy_tutorial.ipynb b/numpy_tutorial.ipynb
diff --git a/opencv_tutorial.ipynb b/opencv_tutorial.ipynb
diff --git a/pandas_tutorial.ipynb b/pandas_tutorial.ipynb
diff --git a/pattern_matching_tutorial.ipynb b/pattern_matching_tutorial.ipynb
 {
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python 结构化模式匹配 (PEP 634, 635, 636) - Python 3.10+ 教程\n",
    "\n",
    "欢迎来到 Python 3.10+ 中引入的强大特性——结构化模式匹配的教程！这个特性，通常简称为“模式匹配”，提供了一种更富有表现力、更简洁的方式来处理复杂的数据结构，可以替代一系列嵌套的 `if/elif/else` 语句或复杂的字典/列表解析。\n",
    "\n",
    "**核心语法：`match` 和 `case`**\n",
    "\n",
    "```python\n",
    "match subject:\n",
    "    case <pattern_1>:\n",
    "        # action_1\n",
    "    case <pattern_2>:\n",
    "        # action_2\n",
    "    case <pattern_3> if <guard_condition>:\n",
    "        # action_3 (if guard is true)\n",
    "    case _: # 通配符，匹配任何未被前面case捕获的内容 (可选)\n",
    "        # default_action\n",
    "```\n",
    "\n",
    "**关键点：**\n",
    "\n",
    "1.  **主题 (Subject)**：`match` 关键字后面的表达式，即我们要匹配的值。\n",
    "2.  **模式 (Pattern)**：`case` 关键字后面的部分。模式可以很简单（如字面量）也可以很复杂（如包含变量捕获、类型检查、结构解包等）。\n",
    "3.  **匹配过程**：Python 会按顺序尝试将 `subject` 与每个 `case` 的 `pattern` 进行匹配。第一个成功匹配的 `case` 块将被执行，然后 `match` 语句结束（没有像C语言 `switch` 那样的“fall-through”行为）。\n",
    "4.  **守卫 (Guard)**：`if <condition>` 子句，附加在 `case` 模式之后。只有当模式匹配成功 **并且** 守卫条件为真时，该 `case` 块才会执行。\n",
    "5.  **通配符 (`_`)**：一个特殊的模式，可以匹配任何东西，但不会绑定到任何名称。通常用作最后一个 `case` 来处理所有未匹配的情况。\n",
    "\n",
    "**本教程将涵盖各种模式类型：**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. 字面量模式 (Literal Patterns)\n",
    "\n",
    "匹配精确的字面量值，如数字、字符串、`True`, `False`, `None`。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def http_status_description(status_code):\n",
    "    match status_code:\n",
    "        case 200:\n",
    "            return \"OK\"\n",
    "        case 400:\n",
    "            return \"Bad Request\"\n",
    "        case 404:\n",
    "            return \"Not Found\"\n",
    "        case 500:\n",
    "            return \"Internal Server Error\"\n",
    "        case _:\n",
    "            return \"Unknown status code\"\n",
    "\n",
    "print(f\"200: {http_status_description(200)}\")\n",
    "print(f\"404: {http_status_description(404)}\")\n",
    "print(f\"301: {http_status_description(301)}\")\n",
    "\n",
    "def process_command(command):\n",
    "    match command:\n",
    "        case \"start\":\n",
    "            print(\"Starting process...\")\n",
    "        case \"stop\":\n",
    "            print(\"Stopping process...\")\n",
    "        case \"restart\":\n",
    "            print(\"Restarting process...\")\n",
    "        case _:\n",
    "            print(f\"Unknown command: {command}\")\n",
    "\n",
    "process_command(\"start\")\n",
    "process_command(\"pause\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. 捕获模式 (Capture Patterns) 和通配符模式 (Wildcard Pattern)\n",
    "\n",
    "*   **捕获模式 (变量名)**：如果一个模式是一个未加点的标识符（例如 `x`），它会匹配任何值，并将该值绑定到这个名称上。\n",
    "*   **通配符模式 (`_`)**：匹配任何值，但不绑定到任何名称。用于忽略某个部分。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def describe_value(value):\n",
    "    match value:\n",
    "        case 0:\n",
    "            print(\"Value is zero.\")\n",
    "        case x if isinstance(x, int) and x > 0:\n",
    "            print(f\"Value is a positive integer: {x}\") # x 被捕获\n",
    "        case y if isinstance(y, str):\n",
    "            print(f\"Value is a string: '{y}' of length {len(y)}\") # y 被捕获\n",
    "        case _:\n",
    "            print(f\"Value is something else: {value}\") # _ 匹配但不捕获\n",
    "\n",
    "describe_value(0)\n",
    "describe_value(42)\n",
    "describe_value(\"hello\")\n",
    "describe_value([1, 2, 3])\n",
    "\n",
    "point = (10, 20, 30)\n",
    "match point:\n",
    "    case (x, y, _): # 捕获 x 和 y，忽略第三个元素\n",
    "        print(f\"2D projection: x={x}, y={y}\")\n",
    "    case _:\n",
    "        print(\"Not a 3-tuple starting point or something else\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**注意：** 捕获模式的名称不能是 `_` 或其他关键字。如果模式是 `some.attribute`，它被视为值模式 (Value Pattern)，而不是捕获模式。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. 值模式 (Value Patterns) 或 点号查找 (Dotted Lookups)\n",
    "\n",
    "匹配一个具名常量或枚举成员的值。模式看起来像一个点号路径，如 `Color.RED` 或 `math.pi`。\n",
    "Python 会计算这个表达式的值，并尝试将 `subject` 与该计算结果进行比较。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from enum import Enum\n",
    "import math\n",
    "\n",
    "class Color(Enum):\n",
    "    RED = 1\n",
    "    GREEN = 2\n",
    "    BLUE = 3\n",
    "\n",
    "def get_color_meaning(color: Color):\n",
    "    match color:\n",
    "        case Color.RED: # 值模式\n",
    "            return \"Passion, Danger\"\n",
    "        case Color.GREEN:\n",
    "            return \"Nature, Growth\"\n",
    "        case Color.BLUE:\n",
    "            return \"Calm, Sky\"\n",
    "        case _:\n",
    "            return \"Unknown color\"\n",
    "\n",
    "print(f\"Meaning of RED: {get_color_meaning(Color.RED)}\")\n",
    "print(f\"Meaning of BLUE: {get_color_meaning(Color.BLUE)}\")\n",
    "\n",
    "MY_CONSTANT = \"special_value\"\n",
    "\n",
    "def check_constant(val):\n",
    "    match val:\n",
    "        case MY_CONSTANT: # 必须是点号查找或已定义的常量名\n",
    "            print(f\"'{val}' matches MY_CONSTANT\")\n",
    "        # case my_constant: # 这会是捕获模式，而不是值模式！\n",
    "        # print(f\"'{val}' captured by my_constant (value: {my_constant})\")\n",
    "        case _:\n",
    "            print(f\"'{val}' does not match MY_CONSTANT\")\n",
    "\n",
    "check_constant(\"special_value\")\n",
    "check_constant(\"other_value\")\n",
    "\n",
    "class Constants:\n",
    "    PI_APPROX = 3.14\n",
    "\n",
    "def check_pi(val):\n",
    "    match val:\n",
    "        case Constants.PI_APPROX:\n",
    "            print(f\"{val} is approximately pi.\")\n",
    "        case math.pi:\n",
    "            print(f\"{val} is math.pi.\") # 也可以匹配模块级常量\n",
    "        case _:\n",
    "            print(f\"{val} is not a known pi value.\")\n",
    "\n",
    "check_pi(3.14)\n",
    "check_pi(math.pi)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**重要区分**：\n",
    "*   `case x:` - `x` 是一个捕获变量，它会匹配并绑定 `subject` 的值。\n",
    "*   `case some.name:` 或 `case QUALIFIED.NAME:` - 这是一个值模式，它会获取 `some.name` 的值，并用该值与 `subject` 进行比较。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. 序列模式 (Sequence Patterns)\n",
    "\n",
    "匹配序列类型（如 `list`, `tuple`）。可以匹配固定长度、可变长度，并捕获元素。\n",
    "*   `[p1, p2, ..., pN]`：匹配一个长度为 N 的序列，并将每个元素与对应的子模式 `pi` 匹配。\n",
    "*   `[p1, p2, *rest]`：匹配一个长度至少为 2 的序列，前两个元素与 `p1`, `p2` 匹配，剩余部分（一个列表）被捕获到 `rest`。\n",
    "*   `[p1, p2, *_]`：类似上面，但忽略剩余部分。\n",
    "*   `*` 只能出现一次。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def process_list(data_list):\n",
    "    match data_list:\n",
    "        case []:\n",
    "            print(\"Empty list\")\n",
    "        case [item1]:\n",
    "            print(f\"List with one item: {item1}\")\n",
    "        case [\"start\", command, count]:\n",
    "            print(f\"Start command: {command} with count: {count}\")\n",
    "        case [x, y, z]:\n",
    "            print(f\"List of three items: {x}, {y}, {z}\")\n",
    "        case [\"log\", *messages]: # 星号捕获剩余部分为一个列表\n",
    "            print(f\"Log messages: {messages}\")\n",
    "        case [first, second, *_]: # 星号通配符忽略剩余部分\n",
    "            print(f\"List starts with {first}, {second}, and has more elements.\")\n",
    "        case _:\n",
    "            print(f\"Unmatched list structure: {data_list}\")\n",
    "\n",
    "process_list([])\n",
    "process_list([100])\n",
    "process_list([\"start\", \"process_A\", 5])\n",
    "process_list([1, 2, 3])\n",
    "process_list([\"log\", \"Error 1\", \"Warning 2\", \"Info 3\"])\n",
    "process_list([\"user\", \"Alice\", 30, \"admin\"])\n",
    "process_list((1,2)) # 也适用于元组，因为元组是序列"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. 映射模式 (Mapping Patterns)\n",
    "\n",
    "匹配映射类型（如 `dict`）。可以匹配特定的键，捕获对应的值，并用 `**rest` 捕获剩余的键值对。\n",
    "*   `{\"key1\": p1, \"key2\": p2}`：匹配一个至少包含 \"key1\" 和 \"key2\" 的字典，它们的值分别与 `p1` 和 `p2` 匹配。\n",
    "*   `{\"key1\": val1, \"key2\": val2, **rest}`：`val1` 和 `val2` 是捕获变量，`rest` 捕获剩余的键值对（一个字典）。\n",
    "*   `**_` 可以用来表示字典可以有其他键，但我们不关心它们。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def process_dict(data_dict):\n",
    "    match data_dict:\n",
    "        case {\"name\": str(name), \"age\": int(age)} if age >= 18:\n",
    "            print(f\"Adult: {name}, Age: {age}\")\n",
    "        case {\"name\": str(name), \"age\": int(age)}:\n",
    "            print(f\"Minor: {name}, Age: {age}\")\n",
    "        case {\"city\": city, \"country\": \"USA\", **other_details}:\n",
    "            print(f\"Location in USA: {city}. Other details: {other_details}\")\n",
    "        case {\"error_code\": code, \"message\": msg, **_}: # 忽略其他键\n",
    "            print(f\"Error {code}: {msg}\")\n",
    "        case {}:\n",
    "            print(\"Empty dictionary\")\n",
    "        case _:\n",
    "            print(f\"Unmatched dictionary structure: {data_dict}\")\n",
    "\n",
    "process_dict({\"name\": \"Alice\", \"age\": 30})\n",
    "process_dict({\"name\": \"Bob\", \"age\": 15})\n",
    "process_dict({\"city\": \"New York\", \"country\": \"USA\", \"zip\": \"10001\"})\n",
    "process_dict({\"error_code\": 404, \"message\": \"Resource not found\", \"timestamp\": 12345})\n",
    "process_dict({})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. 类模式 (Class Patterns)\n",
    "\n",
    "匹配特定类的实例，并可以解构其属性。\n",
    "*   `ClassName()`：匹配 `ClassName` 的任何实例。\n",
    "*   `ClassName(attr1=p1, attr2=p2)`：匹配 `ClassName` 的实例，并且其 `attr1` 属性与 `p1` 匹配，`attr2` 属性与 `p2` 匹配。\n",
    "*   `ClassName(pos_arg1, pos_arg2, attr1=p1)`：如果类定义了 `__match_args__` 来指定位置参数的顺序，则可以按位置匹配。\n",
    "\n",
    "**`__match_args__`**：一个类属性（通常是元组或列表），列出在类模式中可以用作位置参数的实例属性的名称和顺序。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Point:\n",
    "    # __match_args__ 告诉模式匹配如何按位置解释参数\n",
    "    __match_args__ = (\"x\", \"y\") \n",
    "\n",
    "    def __init__(self, x, y, label=None):\n",
    "        self.x = x\n",
    "        self.y = y\n",
    "        self.label = label\n",
    "\n",
    "    def __repr__(self):\n",
    "        return f\"Point({self.x}, {self.y}, label='{self.label}')\"\n",
    "\n",
    "class Circle:\n",
    "    __match_args__ = (\"center\", \"radius\")\n",
    "    def __init__(self, center: Point, radius: float):\n",
    "        self.center = center\n",
    "        self.radius = radius\n",
    "\n",
    "    def __repr__(self):\n",
    "        return f\"Circle(center={self.center!r}, radius={self.radius})\"\n",
    "\n",
    "def describe_shape(shape):\n",
    "    match shape:\n",
    "        case Point(x=0, y=0, label=lbl): # 匹配关键字参数\n",
    "            print(f\"Origin Point with label: '{lbl}'\")\n",
    "        case Point(0, 0): # 使用 __match_args__ 进行位置匹配 (x=0, y=0)\n",
    "            print(\"Origin Point (no label or label ignored)\")\n",
    "        case Point(x_coord, y_coord): # 位置捕获\n",
    "            print(f\"Point at ({x_coord}, {y_coord})\")\n",
    "        case Circle(Point(cx, cy), r) if r > 0: # 嵌套模式和守卫\n",
    "            print(f\"Circle centered at ({cx}, {cy}) with radius {r}\")\n",
    "        case Circle(center=_, radius=0):\n",
    "            print(f\"Degenerate circle (point) at {shape.center}\")\n",
    "        case Point(): # 匹配任何 Point 实例\n",
    "            print(\"Some other Point instance\")\n",
    "        case _: \n",
    "            print(\"Unknown shape\")\n",
    "\n",
    "describe_shape(Point(0, 0, label=\"Origin\"))\n",
    "describe_shape(Point(0, 0))\n",
    "describe_shape(Point(10, 20))\n",
    "describe_shape(Point(5, 8, label=\"P1\"))\n",
    "describe_shape(Circle(Point(5,5), 10))\n",
    "describe_shape(Circle(Point(1,1), 0))\n",
    "describe_shape(\"Not a shape\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. OR 模式 (OR Patterns)\n",
    "\n",
    "使用 `|` (管道符号) 连接多个模式。如果 `subject` 匹配 `|` 左边或右边的任何一个模式，则整个 OR 模式匹配成功。\n",
    "**限制**：OR 模式中的所有子模式必须绑定相同的变量名集合。如果一个子模式绑定了 `x`，那么其他所有子模式也必须绑定 `x` (或者不绑定任何变量)。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def process_media_command(command):\n",
    "    match command:\n",
    "        case \"play\" | \"start\" | \"resume\":\n",
    "            print(\"Playing media...\")\n",
    "        case \"pause\" | \"hold\":\n",
    "            print(\"Pausing media...\")\n",
    "        case \"stop\" | \"end\" | \"quit\":\n",
    "            print(\"Stopping media...\")\n",
    "        case (\"set_volume\", int(level)) | (\"volume\", int(level)) if 0 <= level <= 100:\n",
    "            print(f\"Setting volume to {level}\")\n",
    "        case (\"set_volume\", _) | (\"volume\", _):\n",
    "            print(\"Invalid volume level.\")\n",
    "        case _:\n",
    "            print(f\"Unknown media command: {command}\")\n",
    "\n",
    "process_media_command(\"play\")\n",
    "process_media_command(\"hold\")\n",
    "process_media_command(\"quit\")\n",
    "process_media_command((\"set_volume\", 75))\n",
    "process_media_command((\"volume\", 120))\n",
    "process_media_command((\"volume\", \"high\")) # 会匹配第二个 volume case"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 8. AS 模式 (AS Patterns) - 命名子模式\n",
    "\n",
    "使用 `pattern as name`。如果 `pattern` 匹配成功，那么匹配到的 `subject` (或其一部分，取决于 `pattern`) 会被绑定到 `name`。\n",
    "这对于在复杂模式匹配成功后，仍然需要引用匹配到的整个对象或子对象非常有用。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def process_complex_data(data):\n",
    "    match data:\n",
    "        case [x, y] as pair: # 匹配列表 [x, y]，并将整个列表绑定到 pair\n",
    "            print(f\"Pair: {pair}, sum: {x + y}\")\n",
    "        case {\"coord\": (int(a), int(b)) as point, \"value\": val}:\n",
    "            print(f\"Data point {point} at ({a},{b}) has value {val}\")\n",
    "        case str() as text if len(text) > 10:\n",
    "            print(f\"Long string: {text[:10]}... (Full: {text})\")\n",
    "        case (first, *_, last) as sequence if len(sequence) >=3:\n",
    "            print(f\"Sequence: {sequence}, first={first}, last={last}\")\n",
    "        case _:\n",
    "            print(f\"Other data: {data}\")\n",
    "\n",
    "process_complex_data([10, 20])\n",
    "process_complex_data({\"coord\": (5, 3), \"value\": 100, \"meta\": \"info\"})\n",
    "process_complex_data(\"This is a very long string example.\")\n",
    "process_complex_data((1,2,3,4,5))\n",
    "process_complex_data(42)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 9. 守卫 (Guards)\n",
    "\n",
    "如前所述，`if <condition>` 子句可以加在 `case` 模式之后。只有当模式匹配并且守卫条件为真时，`case` 块才会执行。\n",
    "守卫中可以使用模式中捕获的变量。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def process_number_with_guard(num):\n",
    "    match num:\n",
    "        case int(x) if x > 0 and x % 2 == 0:\n",
    "            print(f\"{x} is a positive even integer.\")\n",
    "        case int(x) if x > 0:\n",
    "            print(f\"{x} is a positive odd integer.\")\n",
    "        case int(x) if x == 0:\n",
    "            print(f\"{x} is zero.\")\n",
    "        case int(x):\n",
    "            print(f\"{x} is a negative integer.\")\n",
    "        case float(y) if y > 0.0:\n",
    "            print(f\"{y} is a positive float.\")\n",
    "        case _:\n",
    "            print(f\"{num} is not a recognized number type or condition.\")\n",
    "\n",
    "process_number_with_guard(10)\n",
    "process_number_with_guard(7)\n",
    "process_number_with_guard(0)\n",
    "process_number_with_guard(-5)\n",
    "process_number_with_guard(3.14)\n",
    "process_number_with_guard(\"text\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 总结与最佳实践\n",
    "\n",
    "结构化模式匹配是 Python 3.10+ 中一个非常强大的工具，它可以使处理复杂数据结构的代码更加清晰、简洁和易于维护。\n",
    "\n",
    "**优点：**\n",
    "*   **可读性**：对于分支逻辑复杂的场景，`match/case` 通常比一长串 `if/elif/else` 更易读。\n",
    "*   **解构赋值**：自然地从数据结构中提取值并赋给变量。\n",
    "*   **详尽性检查的潜力**：虽然 Python 的 `match` 本身不像某些静态语言那样强制进行详尽性检查，但它鼓励思考所有可能的情况（尤其是配合 `_` 通配符）。静态分析工具（如 MyPy）未来可能会在这方面提供更多支持。\n",
    "*   **减少样板代码**：例如，在解析 JSON 数据或处理不同类型的事件时。\n",
    "\n",
    "**使用建议：**\n",
    "*   **不要滥用**：对于简单的条件分支，传统的 `if/else` 可能仍然更清晰。\n",
    "*   **优先考虑可读性**：选择最能表达你意图的方式。\n",
    "*   **注意模式的顺序**：更具体的模式应该放在更通用的模式之前，因为 `match` 会在第一个匹配成功后停止。\n",
    "*   **利用守卫**：当模式本身不足以表达条件时，守卫非常有用。\n",
    "*   **善用 `__match_args__`**：对于自定义类，定义 `__match_args__` 可以使类模式更简洁易用。\n",
    "*   **结合类型提示**：模式匹配与类型提示可以很好地协同工作，提高代码的健壮性。\n",
    "\n",
    "结构化模式匹配为 Python 开发者提供了一个强大的新工具。通过实践和熟悉各种模式类型，你可以有效地利用它来编写更优雅的 Python 代码。"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
 }
diff --git a/python_internals_performance_tutorial.ipynb b/python_internals_performance_tutorial.ipynb
diff --git a/pytorch_tutorial.ipynb b/pytorch_tutorial.ipynb
diff --git a/scikit_learn_tutorial.ipynb b/scikit_learn_tutorial.ipynb
diff --git a/seaborn_tutorial.ipynb b/seaborn_tutorial.ipynb
diff --git a/shap_tutorial.ipynb b/shap_tutorial.ipynb
diff --git a/sigh.md b/sigh.md
diff --git a/stable_baselines3_tutorial.ipynb b/stable_baselines3_tutorial.ipynb
diff --git a/standard_library_tutorial.ipynb b/standard_library_tutorial.ipynb
diff --git a/transformers_tutorial.ipynb b/transformers_tutorial.ipynb
	{
	"cells": [
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"# Python 结构化模式匹配 (PEP 634, 635, 636) - Python 3.10+ 教程\n",
	"\n",
	"欢迎来到 Python 3.10+ 中引入的强大特性——结构化模式匹配的教程！这个特性，通常简称为“模式匹配”，提供了一种更富有表现力、更简洁的方式来处理复杂的数据结构，可以替代一系列嵌套的 `if/elif/else` 语句或复杂的字典/列表解析。\n",
	"\n",
	"核心语法：`match` 和 `case`\n",
	"\n",
	"```python\n",
	"match subject:\n",
	" case <pattern_1>:\n",
	" # action_1\n",
	" case <pattern_2>:\n",
	" # action_2\n",
	" case <pattern_3> if <guard_condition>:\n",
	" # action_3 (if guard is true)\n",
	" case _: # 通配符，匹配任何未被前面case捕获的内容 (可选)\n",
	" # default_action\n",
	"```\n",
	"\n",
	"关键点：\n",
	"\n",
	"1. 主题 (Subject)：`match` 关键字后面的表达式，即我们要匹配的值。\n",
	"2. 模式 (Pattern)：`case` 关键字后面的部分。模式可以很简单（如字面量）也可以很复杂（如包含变量捕获、类型检查、结构解包等）。\n",
	"3. 匹配过程：Python 会按顺序尝试将 `subject` 与每个 `case` 的 `pattern` 进行匹配。第一个成功匹配的 `case` 块将被执行，然后 `match` 语句结束（没有像C语言 `switch` 那样的“fall-through”行为）。\n",
	"4. 守卫 (Guard)：`if <condition>` 子句，附加在 `case` 模式之后。只有当模式匹配成功并且守卫条件为真时，该 `case` 块才会执行。\n",
	"5. 通配符 (`_`)：一个特殊的模式，可以匹配任何东西，但不会绑定到任何名称。通常用作最后一个 `case` 来处理所有未匹配的情况。\n",
	"\n",
	"本教程将涵盖各种模式类型："
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 1. 字面量模式 (Literal Patterns)\n",
	"\n",
	"匹配精确的字面量值，如数字、字符串、`True`, `False`, `None`。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"def http_status_description(status_code):\n",
	" match status_code:\n",
	" case 200:\n",
	" return \"OK\"\n",
	" case 400:\n",
	" return \"Bad Request\"\n",
	" case 404:\n",
	" return \"Not Found\"\n",
	" case 500:\n",
	" return \"Internal Server Error\"\n",
	" case _:\n",
	" return \"Unknown status code\"\n",
	"\n",
	"print(f\"200: {http_status_description(200)}\")\n",
	"print(f\"404: {http_status_description(404)}\")\n",
	"print(f\"301: {http_status_description(301)}\")\n",
	"\n",
	"def process_command(command):\n",
	" match command:\n",
	" case \"start\":\n",
	" print(\"Starting process...\")\n",
	" case \"stop\":\n",
	" print(\"Stopping process...\")\n",
	" case \"restart\":\n",
	" print(\"Restarting process...\")\n",
	" case _:\n",
	" print(f\"Unknown command: {command}\")\n",
	"\n",
	"process_command(\"start\")\n",
	"process_command(\"pause\")"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 2. 捕获模式 (Capture Patterns) 和通配符模式 (Wildcard Pattern)\n",
	"\n",
	"* 捕获模式 (变量名)：如果一个模式是一个未加点的标识符（例如 `x`），它会匹配任何值，并将该值绑定到这个名称上。\n",
	"* 通配符模式 (`_`)：匹配任何值，但不绑定到任何名称。用于忽略某个部分。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"def describe_value(value):\n",
	" match value:\n",
	" case 0:\n",
	" print(\"Value is zero.\")\n",
	" case x if isinstance(x, int) and x > 0:\n",
	" print(f\"Value is a positive integer: {x}\") # x 被捕获\n",
	" case y if isinstance(y, str):\n",
	" print(f\"Value is a string: '{y}' of length {len(y)}\") # y 被捕获\n",
	" case _:\n",
	" print(f\"Value is something else: {value}\") # _ 匹配但不捕获\n",
	"\n",
	"describe_value(0)\n",
	"describe_value(42)\n",
	"describe_value(\"hello\")\n",
	"describe_value([1, 2, 3])\n",
	"\n",
	"point = (10, 20, 30)\n",
	"match point:\n",
	" case (x, y, _): # 捕获 x 和 y，忽略第三个元素\n",
	" print(f\"2D projection: x={x}, y={y}\")\n",
	" case _:\n",
	" print(\"Not a 3-tuple starting point or something else\")\n"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"注意：捕获模式的名称不能是 `_` 或其他关键字。如果模式是 `some.attribute`，它被视为值模式 (Value Pattern)，而不是捕获模式。"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 3. 值模式 (Value Patterns) 或点号查找 (Dotted Lookups)\n",
	"\n",
	"匹配一个具名常量或枚举成员的值。模式看起来像一个点号路径，如 `Color.RED` 或 `math.pi`。\n",
	"Python 会计算这个表达式的值，并尝试将 `subject` 与该计算结果进行比较。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"from enum import Enum\n",
	"import math\n",
	"\n",
	"class Color(Enum):\n",
	" RED = 1\n",
	" GREEN = 2\n",
	" BLUE = 3\n",
	"\n",
	"def get_color_meaning(color: Color):\n",
	" match color:\n",
	" case Color.RED: # 值模式\n",
	" return \"Passion, Danger\"\n",
	" case Color.GREEN:\n",
	" return \"Nature, Growth\"\n",
	" case Color.BLUE:\n",
	" return \"Calm, Sky\"\n",
	" case _:\n",
	" return \"Unknown color\"\n",
	"\n",
	"print(f\"Meaning of RED: {get_color_meaning(Color.RED)}\")\n",
	"print(f\"Meaning of BLUE: {get_color_meaning(Color.BLUE)}\")\n",
	"\n",
	"MY_CONSTANT = \"special_value\"\n",
	"\n",
	"def check_constant(val):\n",
	" match val:\n",
	" case MY_CONSTANT: # 必须是点号查找或已定义的常量名\n",
	" print(f\"'{val}' matches MY_CONSTANT\")\n",
	" # case my_constant: # 这会是捕获模式，而不是值模式！\n",
	" # print(f\"'{val}' captured by my_constant (value: {my_constant})\")\n",
	" case _:\n",
	" print(f\"'{val}' does not match MY_CONSTANT\")\n",
	"\n",
	"check_constant(\"special_value\")\n",
	"check_constant(\"other_value\")\n",
	"\n",
	"class Constants:\n",
	" PI_APPROX = 3.14\n",
	"\n",
	"def check_pi(val):\n",
	" match val:\n",
	" case Constants.PI_APPROX:\n",
	" print(f\"{val} is approximately pi.\")\n",
	" case math.pi:\n",
	" print(f\"{val} is math.pi.\") # 也可以匹配模块级常量\n",
	" case _:\n",
	" print(f\"{val} is not a known pi value.\")\n",
	"\n",
	"check_pi(3.14)\n",
	"check_pi(math.pi)"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"重要区分：\n",
	"* `case x:` - `x` 是一个捕获变量，它会匹配并绑定 `subject` 的值。\n",
	"* `case some.name:` 或 `case QUALIFIED.NAME:` - 这是一个值模式，它会获取 `some.name` 的值，并用该值与 `subject` 进行比较。"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 4. 序列模式 (Sequence Patterns)\n",
	"\n",
	"匹配序列类型（如 `list`, `tuple`）。可以匹配固定长度、可变长度，并捕获元素。\n",
	"* `[p1, p2, ..., pN]`：匹配一个长度为 N 的序列，并将每个元素与对应的子模式 `pi` 匹配。\n",
	"* `[p1, p2, *rest]`：匹配一个长度至少为 2 的序列，前两个元素与 `p1`, `p2` 匹配，剩余部分（一个列表）被捕获到 `rest`。\n",
	"* `[p1, p2, *_]`：类似上面，但忽略剩余部分。\n",
	"* `*` 只能出现一次。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"def process_list(data_list):\n",
	" match data_list:\n",
	" case []:\n",
	" print(\"Empty list\")\n",
	" case [item1]:\n",
	" print(f\"List with one item: {item1}\")\n",
	" case [\"start\", command, count]:\n",
	" print(f\"Start command: {command} with count: {count}\")\n",
	" case [x, y, z]:\n",
	" print(f\"List of three items: {x}, {y}, {z}\")\n",
	" case [\"log\", *messages]: # 星号捕获剩余部分为一个列表\n",
	" print(f\"Log messages: {messages}\")\n",
	" case [first, second, *_]: # 星号通配符忽略剩余部分\n",
	" print(f\"List starts with {first}, {second}, and has more elements.\")\n",
	" case _:\n",
	" print(f\"Unmatched list structure: {data_list}\")\n",
	"\n",
	"process_list([])\n",
	"process_list([100])\n",
	"process_list([\"start\", \"process_A\", 5])\n",
	"process_list([1, 2, 3])\n",
	"process_list([\"log\", \"Error 1\", \"Warning 2\", \"Info 3\"])\n",
	"process_list([\"user\", \"Alice\", 30, \"admin\"])\n",
	"process_list((1,2)) # 也适用于元组，因为元组是序列"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 5. 映射模式 (Mapping Patterns)\n",
	"\n",
	"匹配映射类型（如 `dict`）。可以匹配特定的键，捕获对应的值，并用 `**rest` 捕获剩余的键值对。\n",
	"* `{\"key1\": p1, \"key2\": p2}`：匹配一个至少包含 \"key1\" 和 \"key2\" 的字典，它们的值分别与 `p1` 和 `p2` 匹配。\n",
	"* `{\"key1\": val1, \"key2\": val2, **rest}`：`val1` 和 `val2` 是捕获变量，`rest` 捕获剩余的键值对（一个字典）。\n",
	"* `**_` 可以用来表示字典可以有其他键，但我们不关心它们。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"def process_dict(data_dict):\n",
	" match data_dict:\n",
	" case {\"name\": str(name), \"age\": int(age)} if age >= 18:\n",
	" print(f\"Adult: {name}, Age: {age}\")\n",
	" case {\"name\": str(name), \"age\": int(age)}:\n",
	" print(f\"Minor: {name}, Age: {age}\")\n",
	" case {\"city\": city, \"country\": \"USA\", **other_details}:\n",
	" print(f\"Location in USA: {city}. Other details: {other_details}\")\n",
	" case {\"error_code\": code, \"message\": msg, **_}: # 忽略其他键\n",
	" print(f\"Error {code}: {msg}\")\n",
	" case {}:\n",
	" print(\"Empty dictionary\")\n",
	" case _:\n",
	" print(f\"Unmatched dictionary structure: {data_dict}\")\n",
	"\n",
	"process_dict({\"name\": \"Alice\", \"age\": 30})\n",
	"process_dict({\"name\": \"Bob\", \"age\": 15})\n",
	"process_dict({\"city\": \"New York\", \"country\": \"USA\", \"zip\": \"10001\"})\n",
	"process_dict({\"error_code\": 404, \"message\": \"Resource not found\", \"timestamp\": 12345})\n",
	"process_dict({})"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 6. 类模式 (Class Patterns)\n",
	"\n",
	"匹配特定类的实例，并可以解构其属性。\n",
	"* `ClassName()`：匹配 `ClassName` 的任何实例。\n",
	"* `ClassName(attr1=p1, attr2=p2)`：匹配 `ClassName` 的实例，并且其 `attr1` 属性与 `p1` 匹配，`attr2` 属性与 `p2` 匹配。\n",
	"* `ClassName(pos_arg1, pos_arg2, attr1=p1)`：如果类定义了 `__match_args__` 来指定位置参数的顺序，则可以按位置匹配。\n",
	"\n",
	"`__match_args__`：一个类属性（通常是元组或列表），列出在类模式中可以用作位置参数的实例属性的名称和顺序。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"class Point:\n",
	" # __match_args__ 告诉模式匹配如何按位置解释参数\n",
	" __match_args__ = (\"x\", \"y\") \n",
	"\n",
	" def __init__(self, x, y, label=None):\n",
	" self.x = x\n",
	" self.y = y\n",
	" self.label = label\n",
	"\n",
	" def __repr__(self):\n",
	" return f\"Point({self.x}, {self.y}, label='{self.label}')\"\n",
	"\n",
	"class Circle:\n",
	" __match_args__ = (\"center\", \"radius\")\n",
	" def __init__(self, center: Point, radius: float):\n",
	" self.center = center\n",
	" self.radius = radius\n",
	"\n",
	" def __repr__(self):\n",
	" return f\"Circle(center={self.center!r}, radius={self.radius})\"\n",
	"\n",
	"def describe_shape(shape):\n",
	" match shape:\n",
	" case Point(x=0, y=0, label=lbl): # 匹配关键字参数\n",
	" print(f\"Origin Point with label: '{lbl}'\")\n",
	" case Point(0, 0): # 使用 __match_args__ 进行位置匹配 (x=0, y=0)\n",
	" print(\"Origin Point (no label or label ignored)\")\n",
	" case Point(x_coord, y_coord): # 位置捕获\n",
	" print(f\"Point at ({x_coord}, {y_coord})\")\n",
	" case Circle(Point(cx, cy), r) if r > 0: # 嵌套模式和守卫\n",
	" print(f\"Circle centered at ({cx}, {cy}) with radius {r}\")\n",
	" case Circle(center=_, radius=0):\n",
	" print(f\"Degenerate circle (point) at {shape.center}\")\n",
	" case Point(): # 匹配任何 Point 实例\n",
	" print(\"Some other Point instance\")\n",
	" case _: \n",
	" print(\"Unknown shape\")\n",
	"\n",
	"describe_shape(Point(0, 0, label=\"Origin\"))\n",
	"describe_shape(Point(0, 0))\n",
	"describe_shape(Point(10, 20))\n",
	"describe_shape(Point(5, 8, label=\"P1\"))\n",
	"describe_shape(Circle(Point(5,5), 10))\n",
	"describe_shape(Circle(Point(1,1), 0))\n",
	"describe_shape(\"Not a shape\")"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 7. OR 模式 (OR Patterns)\n",
	"\n",
	"使用 `\|` (管道符号) 连接多个模式。如果 `subject` 匹配 `\|` 左边或右边的任何一个模式，则整个 OR 模式匹配成功。\n",
	"限制：OR 模式中的所有子模式必须绑定相同的变量名集合。如果一个子模式绑定了 `x`，那么其他所有子模式也必须绑定 `x` (或者不绑定任何变量)。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"def process_media_command(command):\n",
	" match command:\n",
	" case \"play\" \| \"start\" \| \"resume\":\n",
	" print(\"Playing media...\")\n",
	" case \"pause\" \| \"hold\":\n",
	" print(\"Pausing media...\")\n",
	" case \"stop\" \| \"end\" \| \"quit\":\n",
	" print(\"Stopping media...\")\n",
	" case (\"set_volume\", int(level)) \| (\"volume\", int(level)) if 0 <= level <= 100:\n",
	" print(f\"Setting volume to {level}\")\n",
	" case (\"set_volume\", _) \| (\"volume\", _):\n",
	" print(\"Invalid volume level.\")\n",
	" case _:\n",
	" print(f\"Unknown media command: {command}\")\n",
	"\n",
	"process_media_command(\"play\")\n",
	"process_media_command(\"hold\")\n",
	"process_media_command(\"quit\")\n",
	"process_media_command((\"set_volume\", 75))\n",
	"process_media_command((\"volume\", 120))\n",
	"process_media_command((\"volume\", \"high\")) # 会匹配第二个 volume case"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 8. AS 模式 (AS Patterns) - 命名子模式\n",
	"\n",
	"使用 `pattern as name`。如果 `pattern` 匹配成功，那么匹配到的 `subject` (或其一部分，取决于 `pattern`) 会被绑定到 `name`。\n",
	"这对于在复杂模式匹配成功后，仍然需要引用匹配到的整个对象或子对象非常有用。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"def process_complex_data(data):\n",
	" match data:\n",
	" case [x, y] as pair: # 匹配列表 [x, y]，并将整个列表绑定到 pair\n",
	" print(f\"Pair: {pair}, sum: {x + y}\")\n",
	" case {\"coord\": (int(a), int(b)) as point, \"value\": val}:\n",
	" print(f\"Data point {point} at ({a},{b}) has value {val}\")\n",
	" case str() as text if len(text) > 10:\n",
	" print(f\"Long string: {text[:10]}... (Full: {text})\")\n",
	" case (first, *_, last) as sequence if len(sequence) >=3:\n",
	" print(f\"Sequence: {sequence}, first={first}, last={last}\")\n",
	" case _:\n",
	" print(f\"Other data: {data}\")\n",
	"\n",
	"process_complex_data([10, 20])\n",
	"process_complex_data({\"coord\": (5, 3), \"value\": 100, \"meta\": \"info\"})\n",
	"process_complex_data(\"This is a very long string example.\")\n",
	"process_complex_data((1,2,3,4,5))\n",
	"process_complex_data(42)"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 9. 守卫 (Guards)\n",
	"\n",
	"如前所述，`if <condition>` 子句可以加在 `case` 模式之后。只有当模式匹配并且守卫条件为真时，`case` 块才会执行。\n",
	"守卫中可以使用模式中捕获的变量。"
	]
	},
	{
	"cell_type": "code",
	"execution_count": null,
	"metadata": {},
	"outputs": [],
	"source": [
	"def process_number_with_guard(num):\n",
	" match num:\n",
	" case int(x) if x > 0 and x % 2 == 0:\n",
	" print(f\"{x} is a positive even integer.\")\n",
	" case int(x) if x > 0:\n",
	" print(f\"{x} is a positive odd integer.\")\n",
	" case int(x) if x == 0:\n",
	" print(f\"{x} is zero.\")\n",
	" case int(x):\n",
	" print(f\"{x} is a negative integer.\")\n",
	" case float(y) if y > 0.0:\n",
	" print(f\"{y} is a positive float.\")\n",
	" case _:\n",
	" print(f\"{num} is not a recognized number type or condition.\")\n",
	"\n",
	"process_number_with_guard(10)\n",
	"process_number_with_guard(7)\n",
	"process_number_with_guard(0)\n",
	"process_number_with_guard(-5)\n",
	"process_number_with_guard(3.14)\n",
	"process_number_with_guard(\"text\")"
	]
	},
	{
	"cell_type": "markdown",
	"metadata": {},
	"source": [
	"## 总结与最佳实践\n",
	"\n",
	"结构化模式匹配是 Python 3.10+ 中一个非常强大的工具，它可以使处理复杂数据结构的代码更加清晰、简洁和易于维护。\n",
	"\n",
	"优点：\n",
	"* 可读性：对于分支逻辑复杂的场景，`match/case` 通常比一长串 `if/elif/else` 更易读。\n",
	"* 解构赋值：自然地从数据结构中提取值并赋给变量。\n",
	"* 详尽性检查的潜力：虽然 Python 的 `match` 本身不像某些静态语言那样强制进行详尽性检查，但它鼓励思考所有可能的情况（尤其是配合 `_` 通配符）。静态分析工具（如 MyPy）未来可能会在这方面提供更多支持。\n",
	"* 减少样板代码：例如，在解析 JSON 数据或处理不同类型的事件时。\n",
	"\n",
	"使用建议：\n",
	"* 不要滥用：对于简单的条件分支，传统的 `if/else` 可能仍然更清晰。\n",
	"* 优先考虑可读性：选择最能表达你意图的方式。\n",
	"* 注意模式的顺序：更具体的模式应该放在更通用的模式之前，因为 `match` 会在第一个匹配成功后停止。\n",
	"* 利用守卫：当模式本身不足以表达条件时，守卫非常有用。\n",
	"* 善用 `__match_args__`：对于自定义类，定义 `__match_args__` 可以使类模式更简洁易用。\n",
	"* 结合类型提示：模式匹配与类型提示可以很好地协同工作，提高代码的健壮性。\n",
	"\n",
	"结构化模式匹配为 Python 开发者提供了一个强大的新工具。通过实践和熟悉各种模式类型，你可以有效地利用它来编写更优雅的 Python 代码。"
	]
	}
	],
	"metadata": {
	"kernelspec": {
	"display_name": "Python 3 (ipykernel)",
	"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.10.0"
	}
	},
	"nbformat": 4,
	"nbformat_minor": 5
	}
No results found