python

关注公众号 jb51net

关闭
首页 > 脚本专栏 > python > Python 类型注解

Python 类型注解核心用法指南

作者：勇往直前plus

本文主要介绍了Python中的类型注解功能,它可以帮助提高代码的可读性与维护性,类型注解可以应用于变量、函数和类,分别提供类型提示而不会强制类型校验,文章同时也介绍了不同类型注解的用法及存储机制,并强调了使用注解时需要注意的一些事项

一、前言

  1. 在 Python 开发中，类型注解是提升代码可读性、降低维护成本的低成本手段——它不影响程序运行，却能让 IDE 实现智能补全、让同事快速理解代码逻辑，更是 dataclass、Pydantic 等常用框架的核心依赖。
  2. Python 作为动态类型语言，变量、函数参数的类型全靠“猜测”，这会带来三个核心问题：
    • 阅读成本高：需反复追溯变量用途，才能理解代码逻辑；
    • 调试成本高：传参类型错误仅在运行时暴露，排查耗时；
    • 开发效率低：IDE 无法提供精准补全，写代码全靠记忆。

而类型注解的核心价值，就是给代码“打标签”——仅做类型提示，不强制校验，却能解决上述问题。

二、类型注解核心用法

按使用场景可以划分为变量的类型注解、函数类型注解、类的类型注解

2.1 变量类型注解

这是最基础的用法，覆盖全局变量、函数内局部变量，语法统一且简单，重点区分“有无默认值”的差异。

  1. 无默认值的注解（如 age: int）仅存元数据，不会创建变量，未赋值直接使用会报错；
  2. 有默认值的注解，同时完成“类型标记”和“变量赋值”，变量可正常使用；
  3. 注解不强制类型匹配（如 age: int = “20” 可运行），仅起提示作用。
# 无默认值（仅标记类型，不创建变量）
变量名: 类型
# 有默认值（标记类型+赋值，注解与变量共存）
变量名: 类型 = 默认值
age:int = 19
# 合法：只声明类型，不赋值
name: str
# 此时变量还不存在，直接用会报错
# print(name)  # NameError
# 赋值后，变量才真正存在
name = "张三"
print(name)  # 正常运行

2.2 函数类型注解

重点标注「参数类型」和「返回值类型」，让函数用途、输入输出一目了然，减少沟通成本

  1. 无返回值最好写 -> None，省略会导致 IDE 提示异常；
  2. *args 注解标注“元素类型”（如 *args: int 表示所有可变位置参数都是整数）；
  3. **kwargs 注解标注“值的类型”（如 **kwargs: str 表示所有关键字参数的值为字符串）；
# 仅参数注解
def 函数名(参数1: 类型, 参数2: 类型 = 默认值):
    pass
# 参数+返回值注解（-> 标识返回类型）
def 函数名(参数1: 类型, 参数2: 类型) -> 返回值类型:
    pass
def add(a: int, b: int) -> int:
    return a + b
# 无返回值（必须写 -> None，不可省略）
def log(msg: str) -> None:
    print(f"日志：{msg}")
# 可变参数注解（指定内部元素类型）
def sum_numbers(*args: int, **kwargs: str) -> list[int]:
    return list(args)

2.3 类的类型注解（dataclass 依赖）

专门用于标记「实例属性」类型，分三种形态，核心区分“注解”与“类属性”的关系，是 dataclass 框架的核心依赖。

  1. 纯注解（如 name: str）不生成类属性，仅存入 __annotations__，用于标记未来实例的属性类型；
  2. 注解+默认值（如 email: str | None = None），一行完成“类型标记+类属性赋值”；
  3. dataclass 正是通过读取 __annotations__，自动生成 __init__、__repr__ 等方法，无需手动编写；
  4. 实例化后，注解标记的属性会成为实例属性，优先覆盖同名类属性。
class 类名:
    # 1. 纯注解（仅标记实例属性类型，无类属性）
    属性名1: 类型
    # 2. 注解+默认值（标记类型+创建类属性，供实例继承默认值）
    属性名2: 类型 = 默认值
    # 3. 普通类属性（无注解，不进入__annotations__）
    属性名3 = 默认值
class User:
    # 纯注解：仅标记实例属性类型，无类属性
    name: str
    age: int
    # 注解+默认值：有类型标记，同时创建类属性（默认值）
    email: str | None = None  # 实例可覆盖该默认值
    gender: str = "未知"
    # 普通类属性：无注解，不进入__annotations__，所有实例共享
    address = "北京"
# 验证注解存储（仅包含带注解的属性）
print(User.__annotations__)
# 输出：{'name': str, 'age': int, 'email': str | None, 'gender': str}

三、类型注解元数据的存储机制

Python 会自动将所有类型注解收集到特殊的 __annotations__ 字典中，本质是一个普通字典，键为注解标记的对象名称（变量名、函数参数名、类属性名等），值为对应的类型（如 str、int、list[int] 等），供框架、工具读取使用。

3.1 不同场景下的元数据存储

注解元数据的存储位置，随注解场景（变量、函数、类）不同而有所差异

模块级变量注解存储

全局（模块级）变量的注解，会存储在当前模块对象的 annotations 字典中

# 模块级变量注解
name: str = "张三"
age: int = 20
score: float | None = 95.5
# 查看模块级注解元数据
print(__annotations__)
# 输出：{'name': str, 'age': int, 'score': float | None}

函数注解存储

函数的注解（参数注解、返回值注解），会存储在函数对象的 annotations 字典中，同时返回值注解会单独对应键 “return”，参数注解对应各自的参数名

def add(a: int, b: int) -> int:
    return a + b
# 查看函数注解元数据
print(add.__annotations__)
# 输出：{'a': int, 'b': int, 'return': int}
# 可变参数注解的存储
def sum_numbers(*args: int, **kwargs: str) -> list[int]:
    return list(args)
print(sum_numbers.__annotations__)
# 输出：{'args': int, 'kwargs': str, 'return': list[int]}

类注解存储

类内的属性注解（纯注解、注解+默认值），会存储在类对象的 annotations 字典中（普通类属性无注解，不存入）；实例对象本身没有 annotations，其注解信息继承自所属类。

class User:
    name: str  # 纯注解
    age: int   # 纯注解
    email: str | None = None  # 注解+默认值
    gender: str = "未知"       # 注解+默认值
    address = "北京"          # 无注解，不存入
# 查看类的注解元数据
print(User.__annotations__)
# 输出：{'name': str, 'age': int, 'email': str | None, 'gender': str}
# 实例无__annotations__，继承类的注解信息
u = User()
print(hasattr(u, "__annotations__"))  # 输出：False

3.2 关键注意点

四、常用类型简写

类型场景注解写法（3.10+）说明
基础类型int/str/bool/float/None最常用、最基础的类型
联合类型str | int、str | None多类型二选一（3.10+ 语法）
容器类型list[int]、dict[str, int]列表（整数元素）、字典（字符串键+整数值）
任意类型Any（需导入 from typing import Any）不限制类型，尽量少用，避免失去注解意义
元组类型tuple[int, str]固定长度、固定元素类型的元组（如 (1, “a”)）

到此这篇关于Python 类型注解核心指南的文章就介绍到这了,更多相关Python 类型注解内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:
阅读全文