python函数类型注解怎么写int和str

Noah
Noah
发布时间:2026-11-20 | 10人浏览过
原创

详细介绍在Python函数中如何编写int和str类型注解,包含参数与返回值的基础语法、带默认值时的PEP 8空格规范、联合类型int|str及None可选值处理,并解析运行时行为与常见认知误区。

python函数类型注解怎么写int和str
图示:Python 函数类型注解概览(int 与 str)

在 Python 中为函数参数添加类型注解(Type Hints)时,直接在参数名后紧跟冒号和类型标识,例如 name: str 或 age: int;若要标注函数的返回值类型,则在参数括号与末尾冒号之间使用瘦箭头 -> 类型,例如 -> str 或 -> int。这是 Python 3.5(PEP 484)引入的标准特性,无需导入任何第三方库即可直接使用。

一、基础语法:参数与返回值的标准写法

Python 内置了 int(整数)与 str(字符串)两种核心类型。为函数的形参以及返回值添加注解时,基本结构非常固定:

  • 参数注解格式:参数名: 类型(例如 text: str、count: int)。
  • 返回值注解格式:在参数括号之后、代码块冒号之前写上 -> 返回类型(例如 -> str)。

下面是一个同时包含 str 和 int 参数,并返回 str 类型的完整函数示例:

def build_greeting(username: str, login_times: int) -> str:
    # 内部直接把整数与字符串拼接成结果字符串
    return f"欢迎用户 {username},这是您第 {login_times} 次登录系统。"

# 调用函数
message = build_greeting("张伟", 5)
print(message)
示例运行输出
欢迎用户 张伟,这是您第 5 次登录系统。

同样地,如果函数的逻辑是接收字符串并返回一个整数(例如统计非空字符数量或计算特定校验和),只需将返回值标注替换为 -> int:

def calculate_effective_length(raw_text: str) -> int:
    # 去除首尾空白后返回字符长度
    return len(raw_text.strip())

length = calculate_effective_length("  Python 教程  ")
print(f"有效字符长度为: {length}")
示例运行输出
有效字符长度为: 9
python函数类型注解怎么写int和str
图 1:Python 函数类型注解语法结构剖析

二、带默认值参数时的写法与 PEP 8 空格规范

当函数参数既有类型注解又有默认值时,初学者常常对冒号与等号的前后顺序以及空格留白产生困惑。正确的书写顺序为:先写类型注解,再写等号与默认值,即:

参数名: 类型 = 默认值

PEP 8 样式规范说明: 在没有类型注解时,函数形参的默认值等号两边不加空格(例如 count=1);但当同时存在类型注解时,PEP 8 明确推荐在等号两边各保留一个空格(例如 count: int = 1),而冒号依然遵循“紧贴变量名、后空一格”的规则。

观察以下包含带默认值参数的实用范例:

def format_notification(
    title: str,
    level: int = 1,
    prefix: str = "系统通知"
) -> str:
    return f"[{prefix} | 级别{level}] {title}"

# 仅传必填参数
print(format_notification("数据库备份完成"))

# 传递所有自定义参数
print(format_notification("磁盘空间不足", level=3, prefix="紧急警报"))
示例运行输出
[系统通知 | 级别1] 数据库备份完成
[紧急警报 | 级别3] 磁盘空间不足
python函数类型注解怎么写int和str
图 2:在函数中应用类型注解的标准编写步骤

三、复合场景:联合类型与可选空值(None)

在实际项目中,经常会遇到参数既可以接收整数又可以接收字符串的场景(例如订单号既可能是数字 100234 也可能是格式化字符串 "ORD-100234"),或者某个字符串参数允许为 None。

1. 联合类型(同时支持 int 与 str)

如果一个形参或返回值既可以是 int 也可以是 str:

  • Python 3.10 及以上版本:直接使用管道符号 |,写作 int | str。
  • Python 3.9 及更早版本:从 typing 模块导入 Union,写作 Union[int, str]。
# Python 3.10+ 原生管道语法:
def format_identifier(user_id: int | str) -> str:
    return f"UID_{user_id}"

print(format_identifier(8088))        # 传入 int
print(format_identifier("admin_99"))  # 传入 str
示例运行输出
UID_8088
UID_admin_99

2. 可选空值(允许传入 None)

若参数有默认值 None,或者可能为空,应当明确标注为可选类型,而不能单纯标注为 str:

  • Python 3.10+:写作 str | None = None。
  • Python 3.9-:从 typing 导入 Optional,写作 Optional[str] = None。
def query_account(account_id: int, remark: str | None = None) -> str:
    if remark:
        return f"账户 {account_id} (备注: {remark})"
    return f"账户 {account_id}"

print(query_account(1001))
print(query_account(1002, "VIP客户"))
示例运行输出
账户 1001
账户 1002 (备注: VIP客户)
python函数类型注解怎么写int和str
图 3:运行时行为与静态检查机制对比

四、核心原理与常见认知误区

在编写 Python 类型注解时,有两个最关键的认知盲区需要特别注意:

误区一:类型注解不是强制类型转换,也不会在运行时自动拦截非法输入。
Python 在运行时并不会因为参数标注了 age: int,就主动帮你把传入的 "20" 强转为整型 20;如果调用者传入了错误类型的实参(如字符串),解释器也不会仅因注解而抛出 TypeError。它依然保持动态类型的灵活性。如果业务上必须严格校验输入类型,需要编写显式的 isinstance() 检查或使用数据验证库(如 Pydantic)。

1. 查看运行时注解字典:__annotations__

类型注解并不是像注释那样被解释器忽略,而是会被编译并保存在函数对象的 __annotations__ 字典属性中,方便框架(例如 FastAPI、Typer)在启动或解析请求时进行反射检查:

def calculate_fee(days: int, plan_name: str) -> int:
    return days * 10

# 查看保存在函数对象中的注解元数据
print(calculate_fee.__annotations__)
示例运行输出
{'days': <class 'int'>, 'plan_name': <class 'str'>, 'return': <class 'int'>}

2. 如何让类型注解真正发挥静态检查威力

要让类型注解产生实实在在的质量保障,主要通过以下两套工具链:

  1. 现代 IDE 智能辅助:在 VSCode、PyCharm 等编辑器中,标注了 str 的参数输入时会自动弹出 .upper()、.replace() 等补全候选;一旦传入类型不一致的变量,编辑器会直接在代码下方标出黄色或红色波浪线提示。
  2. mypy 静态类型检查器:在项目部署或持续集成(CI)流程中,通过终端运行 mypy your_script.py,它会在不运行代码的情况下静态扫描所有调用点,提前揪出将 str 错传给 int 形参的潜在 Bug。
python函数类型注解怎么写int和str
图 4:Python int 与 str 类型注解速查全景总结

五、速查对照表

下表总结了日常开发中 int 与 str 类型注解最常用的各种组合形式,便于随时查阅参考:

场景类别 标准代码示例 关键规范与说明
单一参数注解 def func(x: int, msg: str): 冒号贴变量名,冒号后留一空格;内置类型首字母全部小写。
返回值注解 def func() -> str: 括号后加瘦箭头 ->,两侧各空一格,结尾紧接冒号。
带默认值 def func(limit: int = 10): 类型在等号前,等号两侧均保留一空格(符合 PEP 8 规范)。
整数或字符串二选一 def func(uid: int | str): Python 3.10+ 推荐管道符;旧版使用 Union[int, str]。
参数可为空 None def func(tag: str | None = None): 显式标注包含 None,避免 IDE 警告类型不匹配。
相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表