和Python使用有关的一些教程，按类别分为不同文件

_intro.md

Python教程

Python是一个新手友好的语言，并且现在机器学习社区深度依赖于Python，C++, Cuda C, R等语言，使得Python的热度稳居第一。本Gist提供Python相关的一些教程，可以直接在Jupyter Notebook中运行。

1. 语言级教程，一般不涉及初级主题；
2. 标准库教程，最常见的标准库基本用法；
3. 第三方库教程，主要是常见的库如numpy，pytorch诸如此类，只涉及基本用法，不考虑新特性

其他内容就不往这个Gist里放了，注意Gist依旧由git进行版本控制，所以可以git clone 到本地，或者直接Google Colab\ Kaggle打开相应的ipynb文件

直接在网页浏览时，由于没有文件列表，可以按Ctrl + F来检索相应的目录，或者点击下面的超链接。

想要参与贡献的直接在评论区留言，有什么问题的也在评论区说 ^.^

目录-语言部分

• asyncio_tutorial.ipynb 协程
• c_extensions_tutorial.ipynb C语言扩展
• concurrency_tutorial.ipynb 并发
• context_managers_tutorial.ipynb 上下文管理器
• design_patterns_tutorial.ipynb 设计模式
• dunder_methods_tutorial.ipynb 内置方法（双下划线方法）
• generics_tutorial.ipynb 泛型和类型注解
• iterators_generators_tutorial.ipynb 生成器与迭代器
• metaprogramming_tutorial.ipynb 元编程
• pattern_matching_tutorial.ipynb 模式匹配
• python_internals_performance_tutorial.ipynb 性能分析
• snippets外链 个人日常开发中有用的一些代码片段

目录-库部分

• standard_library_tutorial.ipynb 标准库简易教程
• numpy_tutorial.ipynb 数学运算基石numpy
• pandas_tutorial.ipynb 结构化数据处理pandas
• matplotlib_tutorial.ipynb 绘图库matplotlib
• seaborn_tutorial.ipynb 绘图库seaborn

目录-具体业务库部分-本教程更多关注机器学习深度学习内容

• scikit_learn_tutorial.ipynb 机器学习库scikit_learn
• boosting_libs_tutorial.ipynb 梯度提升库XGBoost LightGBM CatBoost
• pytorch_tutorial.ipynb 深度学习库pytorch
• gymnasium_tutorial.ipynb 强化学习环境gymnasium
• stable_baselines3_tutorial.ipynb 强化学习算法实现SB3
• transformers_tutorial.ipynb 便利的预训练模型库Transformers
• opencv_tutorial.ipynb 经典的计算机视觉库opencv
• experiment_tracking_tutorial.ipynb 实验跟踪与可视化TensorBoard, WanDB, MLfow
• hpo_tutorial.ipynb 超参调优Optuna Raytune
• app_deploy_tutorial.ipynb 便捷的部署框架FastAPI Gradio Streamlit
• shap_tutorial.ipynb 模型可解释性SHAP
• langchain_tutorial.ipynb 构建完整AI应用LangChain
• llamaindex_tutorial.ipynb 另一个强大工具LlamaIndex
• faiss_tutorial.ipynb 向量数据库faiss
• MCP外链 MCP协议的使用

目录-附录

• sigh.md个人对于Python动态语言的看法
• descriptor.md描述符协议

app_deploy_tutorial.ipynb

asyncio_tutorial.ipynb

boosting_libs_tutorial.ipynb

c_extensions_tutorial.ipynb

concurrency_tutorial.ipynb

context_managers_tutorial.ipynb

descriptor.md

Python 描述符

描述符是实现了__get__ __set__ __delete__其中任一方法的类型对象，根据是否有__set__区别是否为数据描述符。

class DataDesc:
    def __get__(self, obj, objtype=None):
        return 'data'
    def __set__(self, obj, value):
        pass

class NonDataDesc:
    def __get__(self, obj, objtype=None):
        return 'nondata'

class C:
    a = DataDesc()
    b = NonDataDesc()
    c = 42
    d = NonDataDesc()

obj = C()
obj.a = 'inst_a'
obj.b = 'inst_b'
obj.c = 'inst_c'
# d 没有实例属性，直接访问

print(obj.a)  # 'data'（数据描述符优先）
print(obj.b)  # 'inst_b'（实例属性优先）
print(obj.c)  # 'inst_c'（实例属性优先）
print(obj.d)  # 'nondata'（非数据描述符被触发）

由此，我们有以下总结：

1. 描述符必须是type类型的成员，也就是class定义的内部成员(或者通过type(,,)动态定义的类型)
2. 通过类名可访问描述符C.a，也可以通过实例对象访问obj.a，而实例对象访问时候会有以下查找顺序：
   1. 无论obj.__dict__中是否有a，优先查找C.__dict__中的数据描述符。
   2. 如果没有1那么回退到访问obj.dict__该名称a的普通对象(当obj只有__slot__时候转而查找__slot)
   3. 如果没有2则查找C.__dict__的非数据描述符
   4. 如果没有3则返回C.__dict__中名为a的普通对象
   5. 如果没有4则报错
3. 注意上述数据中的第三条，平时在class中使用def定义的都是function类型的实例，其实现了__get__方法，所以在obj调用实例方法obj.foo时候（此时obj.__dict__自然没有覆盖obj.foo的项），会访问function的描述符协议，导致其访问内容变为bound method而不是function。这也是为什么直接通过类名和实例名访问函数时候的行为不一样。 特别的，内建的staticmethod和classmethod都是实现了__get__的装饰器，所以访问这些方法时候都会按描述符协议去访问。

design_patterns_tutorial.ipynb

dunder_methods_tutorial.ipynb

experiment_tracking_tutorial.ipynb

faiss_tutorial.ipynb

generics_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python 泛型与类型注解教程\n",
    "\n",
    "欢迎来到 Python 泛型与类型注解的详细教程！本教程将引导你了解 Python 中类型提示的基础知识，并深入探讨泛型、抽象基类（ABC）以及协议（Protocol）在类型系统中的应用。\n",
    "\n",
    "**为什么需要类型注解？**\n",
    "\n",
    "1.  **可读性与可维护性**：明确函数参数和返回值的期望类型，使代码更易于理解。\n",
    "2.  **早期错误检测**：配合静态类型检查工具（如 MyPy, Pyright/Pylance），可以在运行前发现类型不匹配的错误。\n",
    "3.  **更好的IDE支持**：IDE 可以根据类型注解提供更精确的代码补全、重构和错误提示。\n",
    "4.  **设计工具**：类型注解帮助思考和设计清晰的API接口。\n",
    "\n",
    "**注意**：Python 本质上是动态类型语言，类型注解本身在运行时**不会**强制执行类型检查（除非使用特殊库如 Pydantic），它们主要服务于静态分析和开发者。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. 基础类型注解\n",
    "\n",
    "Python 3.5+ 引入了类型提示的语法（PEP 484）。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 变量注解\n",
    "age: int = 30\n",
    "name: str = \"Alice\"\n",
    "pi: float = 3.14159\n",
    "is_student: bool = True\n",
    "\n",
    "# 函数注解\n",
    "def greet(person_name: str) -> str:\n",
    "    return f\"Hello, {person_name}!\"\n",
    "\n",
    "def add(a: int, b: int) -> int:\n",
    "    return a + b\n",
    "\n",
    "print(greet(\"Bob\"))\n",
    "print(add(5, 3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.1 集合类型的注解\n",
    "\n",
    "对于内置的集合类型，如列表、字典、元组、集合：\n",
    "- Python 3.9+：可以直接使用 `list[type]`, `dict[key_type, value_type]` 等。\n",
    "- Python < 3.9：需要从 `typing` 模块导入 `List`, `Dict`, `Tuple`, `Set`。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import List, Dict, Tuple, Set, Optional, Any, Union # 导入以备旧版本或特殊情况使用\n",
    "\n",
    "# Python 3.9+ 风格 (推荐)\n",
    "numbers: list[int] = [1, 2, 3]\n",
    "scores: dict[str, float] = {\"math\": 90.5, \"science\": 88.0}\n",
    "coordinates: tuple[int, int, str] = (10, 20, \"Point A\")\n",
    "unique_names: set[str] = {\"Alice\", \"Bob\"}\n",
    "\n",
    "# Python < 3.9 风格 (如果需要在旧版本运行)\n",
    "# from typing import List, Dict, Tuple, Set\n",
    "# numbers_old: List[int] = [1, 2, 3]\n",
    "# scores_old: Dict[str, float] = {\"math\": 90.5, \"science\": 88.0}\n",
    "# coordinates_old: Tuple[int, int, str] = (10, 20, \"Point A\")\n",
    "# unique_names_old: Set[str] = {\"Alice\", \"Bob\"}\n",
    "\n",
    "def process_numbers(data: list[int]) -> int:\n",
    "    return sum(data)\n",
    "\n",
    "print(process_numbers(numbers))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.2 特殊类型提示\n",
    "\n",
    "- `Optional[X]`：表示一个值可以是 `X` 类型，也可以是 `None`。等价于 `Union[X, None]` 或 Python 3.10+ 的 `X | None`。\n",
    "- `Union[X, Y]`：表示一个值可以是 `X` 类型，也可以是 `Y` 类型。Python 3.10+ 可以用 `X | Y`。\n",
    "- `Any`：表示一个值可以是任何类型。应谨慎使用，因为它会削弱类型检查。\n",
    "- `Callable`：用于注解可调用对象（如函数）。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Callable\n",
    "\n",
    "def find_user(user_id: int) -> Optional[str]: # 或 str | None (Python 3.10+)\n",
    "    if user_id == 1:\n",
    "        return \"Alice\"\n",
    "    return None\n",
    "\n",
    "user = find_user(1)\n",
    "if user:\n",
    "    print(user.upper())\n",
    "\n",
    "user_none = find_user(2)\n",
    "print(user_none)\n",
    "\n",
    "def process_item(item: Union[int, str]) -> str: # 或 int | str (Python 3.10+)\n",
    "    if isinstance(item, int):\n",
    "        return f\"Integer: {item}\"\n",
    "    else:\n",
    "        return f\"String: {item.upper()}\"\n",
    "\n",
    "print(process_item(100))\n",
    "print(process_item(\"hello\"))\n",
    "\n",
    "def log_message(message: Any) -> None:\n",
    "    print(f\"LOG: {message}\")\n",
    "\n",
    "log_message(\"System started\")\n",
    "log_message([1,2,3])\n",
    "\n",
    "# Callable[[Arg1Type, Arg2Type], ReturnType]\n",
    "def apply_operation(x: int, y: int, operation: Callable[[int, int], int]) -> int:\n",
    "    return operation(x, y)\n",
    "\n",
    "def multiply(a: int, b: int) -> int:\n",
    "    return a * b\n",
    "\n",
    "result = apply_operation(5, 3, add)       # add 函数在前面定义过\n",
    "result_multiply = apply_operation(5, 3, multiply)\n",
    "print(f\"Add result: {result}\")\n",
    "print(f\"Multiply result: {result_multiply}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.3 类型别名 (Type Aliases)\n",
    "\n",
    "当类型注解变得复杂时，可以使用类型别名来简化它们。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Vector = list[float]\n",
    "Point = tuple[float, float]\n",
    "UserScores = dict[str, list[int]]\n",
    "\n",
    "def scale_vector(vector: Vector, scalar: float) -> Vector:\n",
    "    return [x * scalar for x in vector]\n",
    "\n",
    "my_vector: Vector = [1.0, 2.0, 3.0]\n",
    "scaled_vector = scale_vector(my_vector, 2.5)\n",
    "print(scaled_vector)\n",
    "\n",
    "def get_user_average_score(scores: UserScores, user_name: str) -> Optional[float]:\n",
    "    if user_name in scores and scores[user_name]:\n",
    "        user_scores = scores[user_name]\n",
    "        return sum(user_scores) / len(user_scores)\n",
    "    return None\n",
    "\n",
    "all_scores: UserScores = {\n",
    "    \"Alice\": [80, 90, 85],\n",
    "    \"Bob\": [70, 75]\n",
    "}\n",
    "print(get_user_average_score(all_scores, \"Alice\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. 泛型 (Generics)\n",
    "\n",
    "泛型允许我们编写可以操作多种类型的函数或类，同时保持类型安全。\n",
    "关键是 `typing.TypeVar`。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1 `TypeVar`\n",
    "\n",
    "`TypeVar` 用于声明一个类型变量。这个变量可以代表任何类型，或者在特定约束下的某些类型。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import TypeVar\n",
    "\n",
    "# 创建一个类型变量 T。它可以是任何类型。\n",
    "T = TypeVar('T')\n",
    "\n",
    "# 泛型函数：输入类型和输出类型相同\n",
    "def identity(item: T) -> T:\n",
    "    return item\n",
    "\n",
    "int_val = identity(10)        # T 被推断为 int\n",
    "str_val = identity(\"hello\")   # T 被推断为 str\n",
    "list_val = identity([1,2,3]) # T 被推断为 list[int]\n",
    "\n",
    "print(f\"Type of int_val: {type(int_val)}, value: {int_val}\")\n",
    "print(f\"Type of str_val: {type(str_val)}, value: {str_val}\")\n",
    "print(f\"Type of list_val: {type(list_val)}, value: {list_val}\")\n",
    "\n",
    "# 另一个泛型函数示例\n",
    "def get_first(container: list[T]) -> Optional[T]: # 或 T | None\n",
    "    if container:\n",
    "        return container[0]\n",
    "    return None\n",
    "\n",
    "first_num = get_first([1, 2, 3])      # T is int, returns Optional[int]\n",
    "first_str = get_first([\"a\", \"b\"])    # T is str, returns Optional[str]\n",
    "first_empty = get_first([])         # T is ?, returns Optional[Any] if not specified, but often inferred\n",
    "\n",
    "print(f\"First num: {first_num}\")\n",
    "print(f\"First str: {first_str}\")\n",
    "print(f\"First empty: {first_empty}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2 泛型类\n",
    "\n",
    "要创建泛型类，需要继承自 `typing.Generic`。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Generic\n",
    "\n",
    "T_co = TypeVar('T_co', covariant=True) # 协变类型变量, 常用于只读容器\n",
    "T_contra = TypeVar('T_contra', contravariant=True) # 逆变类型变量，常用于只写容器或参数\n",
    "# 如果不指定协变或逆变，默认为不变 (invariant)\n",
    "\n",
    "class Box(Generic[T]): # T 是不变的\n",
    "    def __init__(self, item: T):\n",
    "        self._item = item\n",
    "\n",
    "    def get_item(self) -> T:\n",
    "        return self._item\n",
    "\n",
    "    def set_item(self, item: T) -> None:\n",
    "        self._item = item\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        return f\"Box({self._item!r})\"\n",
    "\n",
    "# 使用泛型类\n",
    "int_box = Box[int](123)\n",
    "print(int_box)\n",
    "print(int_box.get_item())\n",
    "\n",
    "str_box = Box[str](\"Python\")\n",
    "print(str_box)\n",
    "print(str_box.get_item())\n",
    "\n",
    "# int_box.set_item(\"text\") # Mypy会报错: Argument 1 to \"set_item\" of \"Box\" has incompatible type \"str\"; expected \"int\"\n",
    "str_box.set_item(\"Generics\")\n",
    "print(str_box)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 关于协变 (Covariance) 和逆变 (Contravariance)\n",
    "\n",
    "这是一个高级主题，简要说明：\n",
    "\n",
    "- **不变 (Invariance, 默认)**: `Box[Dog]` 不是 `Box[Animal]` 的子类型，`Box[Animal]` 也不是 `Box[Dog]` 的子类型（假设 `Dog` 是 `Animal` 的子类）。\n",
    "  对于可读写的容器，不变性通常是安全的。 `list[Dog]` 不是 `list[Animal]`，因为你可以向 `list[Animal]` 添加 `Cat`，但不能向 `list[Dog]` 添加 `Cat`。\n",
    "\n",
    "- **协变 (Covariance, `covariant=True`)**: 如果 `Dog` 是 `Animal` 的子类型，那么 `Producer[Dog]` 是 `Producer[Animal]` 的子类型。这通常用于只返回 `T` 类型（生产者）的泛型。\n",
    "  例如, `Sequence[Dog]` 是 `Sequence[Animal]` 的子类型，因为 `Sequence` 是只读的。\n",
    "\n",
    "- **逆变 (Contravariance, `contravariant=True`)**: 如果 `Dog` 是 `Animal` 的子类型，那么 `Consumer[Animal]` 是 `Consumer[Dog]` 的子类型（方向相反）。这通常用于只接受 `T` 类型作为参数（消费者）的泛型。\n",
    "  例如，一个函数 `Callable[[Animal], None]` 可以接受 `Dog`，所以它可以被用在期望 `Callable[[Dog], None]` 的地方。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.3 约束类型变量 (Constrained TypeVar)\n",
    "\n",
    "可以限制 `TypeVar` 只能是某些特定类型中的一个。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "S = TypeVar('S', str, bytes) # S 只能是 str 或 bytes\n",
    "\n",
    "def combine(a: S, b: S) -> S:\n",
    "    return a + b\n",
    "\n",
    "str_result = combine(\"hello\", \" world\") # S is str\n",
    "bytes_result = combine(b\"hello\", b\" world\") # S is bytes\n",
    "\n",
    "print(str_result)\n",
    "print(bytes_result)\n",
    "\n",
    "# combine(1, 2) # Mypy会报错: Value of type variable \"S\" of \"combine\" cannot be \"int\"\n",
    "# combine(\"hello\", b\"world\") # Mypy会报错: Type variable \"S\" is ambiguous"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.4 边界类型变量 (Bounded TypeVar)\n",
    "\n",
    "可以限制 `TypeVar` 必须是某个类型的子类（或该类型本身）。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numbers import Number # Number 是 int, float, complex等的抽象基类\n",
    "\n",
    "N = TypeVar('N', bound=Number) # N 必须是 Number 或其子类\n",
    "\n",
    "def add_numbers(a: N, b: N) -> N:\n",
    "    # 类型检查器知道 a 和 b 都是 Number 的子类，所以它们支持 + 操作\n",
    "    return a + b\n",
    "\n",
    "print(add_numbers(1, 2))         # N is int\n",
    "print(add_numbers(1.5, 2.5))     # N is float\n",
    "print(add_numbers(1, 2.5))       # N 会被推断为 float (更通用的类型)\n",
    "\n",
    "# add_numbers(\"a\", \"b\") # Mypy会报错: Value of type variable \"N\" of \"add_numbers\" cannot be \"str\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. 抽象基类 (Abstract Base Classes - ABCs) 与类型提示\n",
    "\n",
    "ABCs (来自 `abc` 模块) 用于定义类接口。它们经常与类型提示一起使用，以指定函数期望接收实现了特定接口的对象。\n",
    "`collections.abc` 模块包含许多有用的 ABCs，如 `Iterable`, `Sequence`, `Mapping`等。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abc import ABC, abstractmethod\n",
    "from collections.abc import Sequence # 注意是 collections.abc 不是 typing\n",
    "\n",
    "class MediaStream(ABC):\n",
    "    @abstractmethod\n",
    "    def play(self) -> None:\n",
    "        pass\n",
    "\n",
    "    @abstractmethod\n",
    "    def stop(self) -> None:\n",
    "        pass\n",
    "\n",
    "class AudioStream(MediaStream):\n",
    "    def play(self) -> None:\n",
    "        print(\"Playing audio...\")\n",
    "    \n",
    "    def stop(self) -> None:\n",
    "        print(\"Stopping audio.\")\n",
    "\n",
    "class VideoStream(MediaStream):\n",
    "    def play(self) -> None:\n",
    "        print(\"Playing video...\")\n",
    "\n",
    "    def stop(self) -> None:\n",
    "        print(\"Stopping video.\")\n",
    "\n",
    "def control_stream(stream: MediaStream) -> None:\n",
    "    print(f\"Controlling stream of type: {type(stream).__name__}\")\n",
    "    stream.play()\n",
    "    stream.stop()\n",
    "\n",
    "audio = AudioStream()\n",
    "video = VideoStream()\n",
    "\n",
    "control_stream(audio)\n",
    "control_stream(video)\n",
    "\n",
    "# 使用 collections.abc.Sequence\n",
    "def print_sequence_elements(seq: Sequence[Any]) -> None:\n",
    "    for i, element in enumerate(seq):\n",
    "        print(f\"Element {i}: {element}\")\n",
    "\n",
    "my_list = [10, 20, 30]       # list is a Sequence\n",
    "my_tuple = ('a', 'b', 'c')  # tuple is a Sequence\n",
    "my_string = \"hello\"         # str is a Sequence\n",
    "\n",
    "print_sequence_elements(my_list)\n",
    "print_sequence_elements(my_tuple)\n",
    "print_sequence_elements(my_string)\n",
    "\n",
    "# print_sequence_elements({1, 2}) # Mypy会报错, set 不是 Sequence (它没有顺序，不能通过索引访问)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. 协议 (Protocols) - 结构化子类型 (Structural Subtyping)\n",
    "\n",
    "Python 是一种“鸭子类型”语言 (\"If it walks like a duck and quacks like a duck, then it must be a duck.\")。\n",
    "`typing.Protocol` (PEP 544, Python 3.8+) 允许我们形式化这种鸭子类型，实现结构化子类型。\n",
    "\n",
    "一个类不需要显式继承自一个 Protocol 就能被认为是该 Protocol 的一个实现，只要它具有 Protocol 中定义的所有方法和属性（具有兼容的签名）。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Protocol, runtime_checkable\n",
    "\n",
    "# 定义一个协议\n",
    "@runtime_checkable # 允许在运行时使用 isinstance() 检查 (可选)\n",
    "class SupportsQuack(Protocol):\n",
    "    def quack(self) -> str:\n",
    "        ...\n",
    "\n",
    "@runtime_checkable\n",
    "class SupportsFly(Protocol):\n",
    "    def fly(self) -> None:\n",
    "        ...\n",
    "\n",
    "# 实现协议的类 (注意：不需要显式继承)\n",
    "class Duck:\n",
    "    def quack(self) -> str:\n",
    "        return \"Quack!\"\n",
    "    \n",
    "    def fly(self) -> None:\n",
    "        print(\"Duck flying\")\n",
    "\n",
    "class Goose:\n",
    "    def quack(self) -> str:\n",
    "        return \"Honk!\"\n",
    "    \n",
    "    def fly(self) -> None:\n",
    "        print(\"Goose flying high\")\n",
    "\n",
    "class Person:\n",
    "    def speak(self) -> str:\n",
    "        return \"Hello!\"\n",
    "\n",
    "# 使用协议进行类型提示\n",
    "def make_it_quack(obj: SupportsQuack) -> None:\n",
    "    print(obj.quack())\n",
    "\n",
    "def make_it_fly(obj: SupportsFly) -> None:\n",
    "    obj.fly()\n",
    "\n",
    "duck = Duck()\n",
    "goose = Goose()\n",
    "person = Person()\n",
    "\n",
    "print(\"--- Making them quack ---\")\n",
    "make_it_quack(duck)   # Duck 实现了 SupportsQuack\n",
    "make_it_quack(goose)  # Goose 也实现了 SupportsQuack\n",
    "# make_it_quack(person) # Mypy会报错: Person does not have 'quack' method\n",
    "\n",
    "print(\"--- Making them fly ---\")\n",
    "make_it_fly(duck)\n",
    "make_it_fly(goose)\n",
    "# make_it_fly(person) # Mypy会报错\n",
    "\n",
    "# 运行时检查 (因为用了 @runtime_checkable)\n",
    "print(f\"\\nIs duck a SupportsQuack? {isinstance(duck, SupportsQuack)}\") # True\n",
    "print(f\"Is goose a SupportsQuack? {isinstance(goose, SupportsQuack)}\") # True\n",
    "print(f\"Is person a SupportsQuack? {isinstance(person, SupportsQuack)}\") # False\n",
    "\n",
    "print(f\"Is duck a SupportsFly? {isinstance(duck, SupportsFly)}\") # True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.1 泛型协议\n",
    "\n",
    "协议也可以是泛型的。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "T_item = TypeVar('T_item')\n",
    "\n",
    "@runtime_checkable\n",
    "class SupportsGetItem(Protocol[T_item]):\n",
    "    def __getitem__(self, key: int) -> T_item:\n",
    "        ...\n",
    "\n",
    "def get_element_at_index_zero(container: SupportsGetItem[T_item]) -> T_item:\n",
    "    return container[0]\n",
    "\n",
    "my_list_of_strs: list[str] = [\"apple\", \"banana\"]\n",
    "my_tuple_of_ints: tuple[int, ...] = (10, 20, 30)\n",
    "\n",
    "first_str = get_element_at_index_zero(my_list_of_strs) # T_item is str\n",
    "print(f\"First string: {first_str}\")\n",
    "\n",
    "first_int = get_element_at_index_zero(my_tuple_of_ints) # T_item is int\n",
    "print(f\"First int: {first_int}\")\n",
    "\n",
    "# 运行时检查 (需要 Python 3.8+ 和 @runtime_checkable)\n",
    "print(f\"Is list[str] a SupportsGetItem? {isinstance(my_list_of_strs, SupportsGetItem)}\") # True\n",
    "\n",
    "# 注意：对于泛型协议，isinstance 可能不总是能精确推断泛型参数。\n",
    "# Mypy 静态检查是更可靠的。 "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. 静态类型检查工具\n",
    "\n",
    "如前所述，Python 本身不强制执行类型注解。你需要使用静态类型检查工具来利用它们。\n",
    "\n",
    "- **MyPy**: 最流行的 Python 静态类型检查器。\n",
    "  ```bash\n",
    "  pip install mypy\n",
    "  mypy your_script.py\n",
    "  ```\n",
    "- **Pyright** (由微软开发，Pylance VS Code 插件的基础): 另一个快速且功能强大的类型检查器。\n",
    "- **Pytype** (由谷歌开发)。\n",
    "\n",
    "这些工具会读取你的类型注解，并报告任何不一致之处。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 总结\n",
    "\n",
    "类型注解和泛型是现代 Python 开发中强大的工具：\n",
    "- **提高了代码质量和可维护性**：通过明确的类型声明。\n",
    "- **增强了开发体验**：通过更好的 IDE 支持和早期错误检测。\n",
    "- **`TypeVar`** 允许创建灵活的泛型函数和类。\n",
    "- **`Generic`** 是创建泛型类的基石。\n",
    "- **`ABC`** (抽象基类) 用于定义基于继承的接口（名义子类型）。\n",
    "- **`Protocol`** 用于定义基于结构的接口（结构化子类型或鸭子类型），更符合 Python 的动态特性。\n",
    "\n",
    "熟练运用这些特性，可以帮助你编写出更健壮、更易于理解和协作的 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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}

gymnasium_tutorial.ipynb

hpo_tutorial.ipynb

iterators_generators_tutorial.ipynb

langchain_tutorial.ipynb

llamaindex_tutorial.ipynb

matplotlib_tutorial.ipynb

metaprogramming_tutorial.ipynb

numpy_tutorial.ipynb

opencv_tutorial.ipynb

pandas_tutorial.ipynb

pattern_matching_tutorial.ipynb

python_internals_performance_tutorial.ipynb

pytorch_tutorial.ipynb

scikit_learn_tutorial.ipynb

seaborn_tutorial.ipynb

shap_tutorial.ipynb

sigh.md

对动态语言Python的一些感慨

众所周知Python是完全动态的语言，体现在

1. 类型动态绑定
2. 运行时检查
3. 对象结构内容可动态修改（而不仅仅是值）
4. 反射
5. 一切皆对象（instance, class, method）
6. 可动态执行代码(eval, exec)
7. 鸭子类型支持

动态语言的约束更少，对使用者来说更易于入门，但相应的也会有代价就是运行时开销很大，和底层汇编执行逻辑完全解耦不知道代码到底是怎么执行的。

而且还有几点是我认为较为严重的缺陷。下面进行梳理。

破坏了OOP的语义

较为流行的编程语言大多支持OOP编程范式。即继承和多态。同样，Python在执行简单任务时候可以纯命令式(Imperative Programming)，也可以使用复杂的面向对象OOP。

但是，其动态特性破环了OOP的结构：

1. 类型模糊：任何类型实例，都可以在运行时添加或者删除属性或者方法（相比之下静态语言只能在运行时修改它们的值）。经此修改的实例，按理说不再属于原来的类型，毕竟和原类型已经有了明显的区别。但是该实例的内建__class__属性依旧会指向原类型，这会给类型的认知造成困惑。符合一个class不应该只是名义上符合，而是内容上也应该符合。
2. 破坏继承：体现在以下两个方面
   1. 大部分实践没有虚接口继承。abc模块提供了虚接口的基类ABC，经典的做法是让自己的抽象类继承自ABC，然后具体类继承自自己的抽象类，然后去实现抽象方法。但PEP提案认为Pythonic的做法是用typing.Protocol来取代ABC，具体类完全不继承任何虚类，只要实现相应的方法，那么就可以被静态检查器认为是符合Protocol的。
   2. 不需要继承自具体父类。和上一条一样，即使一个类没有任何父类（除了object类），它依旧可以生成同名的方法，以实现和父类方法相同的调用接口。这样在语义逻辑上，类的定义完全看不出和其他类有何种关系。完全可以是一种松散的组织结构，任何两个类之间都没继承关系。
3. 破坏多态：任何一个入参出参，天然不限制类型。这使得要求父类型的参数处，传入子类型显得没有意义，依旧是因为任何类型都能动态修改满足要求。

破坏了设计模式

经典的模式诸如工厂模式，抽象工厂，访问者模式，都严重依赖于继承和多态的性质。但是在python的设计中，其动态能力使得设计模式形同虚设。 大家常见的库中使用设计模式的有transformers库，其中的from_pretrained系列则是工厂模式，通过字符串名称确定了具体的构造器得到具体的子类。而工厂构造器的输出类型是一个所有模型的基类。

安全性问题

Python在代码层面一般不直接管理指针，所以指针越界，野指针，悬空指针等问题一般不存在。而gc机制也能自动处理垃圾回收使得编码过程不必关注这类安全性问题。但与之相对的，Python也有自己的安全性问题。以往非托管形式的代码的攻击难度较大，注入代码想要稳定执行需要避免破坏原来的结构导致程序直接崩溃（段错误）。 Python却可以直接注入任何代码修改原本的逻辑，并且由于不是在code段固定的内容，攻击时候也无需有额外考虑。运行时可以手动修改globals() locals()内容，亦有一定风险。 另一个危险则是类型不匹配导致的代码执行问题，因为只有在运行时才确定类型，无法提前做出保证，可能会产生类型错误的异常，造成程序崩溃。

总结

我出身于C++。但是近年来一直在用python编程。而且python的市场占有率已经多年第一，且遥遥领先。这和其灵活性分不开关系。对于一个面向大众的编程语言，这样的特性是必要的。即使以上说了诸多python的不严谨之处，但是对于程序员依旧可以选择严谨的面向对象写法。所以，程序的优劣不在于语言怎么样，而在于程序员本身。程序员有责任写出易于维护，清晰，规范的代码~

stable_baselines3_tutorial.ipynb

standard_library_tutorial.ipynb

transformers_tutorial.ipynb

返回顶部

有见解，有问题，或者单纯想盖楼灌水，都可以在这里发表！

因为文档比较多，有时候渲染不出来ipynb是浏览器性能的问题，刷新即可

或者git clone到本地来阅读