python函数类型注解怎么写int和str
详细介绍在Python函数中如何编写int和str类型注解,包含参数与返回值的基础语法、带默认值时的PEP 8空格规范、联合类型int|str及None可选值处理,并解析运行时行为与常见认知误区。
在 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)
同样地,如果函数的逻辑是接收字符串并返回一个整数(例如统计非空字符数量或计算特定校验和),只需将返回值标注替换为 -> int:
def calculate_effective_length(raw_text: str) -> int:
# 去除首尾空白后返回字符长度
return len(raw_text.strip())
length = calculate_effective_length(" Python 教程 ")
print(f"有效字符长度为: {length}")
二、带默认值参数时的写法与 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="紧急警报"))
[紧急警报 | 级别3] 磁盘空间不足
三、复合场景:联合类型与可选空值(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_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客户"))
账户 1002 (备注: VIP客户)
四、核心原理与常见认知误区
在编写 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__)
2. 如何让类型注解真正发挥静态检查威力
要让类型注解产生实实在在的质量保障,主要通过以下两套工具链:
- 现代 IDE 智能辅助:在 VSCode、PyCharm 等编辑器中,标注了
str的参数输入时会自动弹出.upper()、.replace()等补全候选;一旦传入类型不一致的变量,编辑器会直接在代码下方标出黄色或红色波浪线提示。 - mypy 静态类型检查器:在项目部署或持续集成(CI)流程中,通过终端运行
mypy your_script.py,它会在不运行代码的情况下静态扫描所有调用点,提前揪出将str错传给int形参的潜在 Bug。
五、速查对照表
下表总结了日常开发中 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 警告类型不匹配。 |
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













