Python 基础语法与工程目录规范学习总结

Python 基础语法与工程目录规范学习总结

一、类型注解相关知识点

1. 类方法标识 cls

使用 @classmethod 装饰的方法，第一个固定参数为 cls，代表当前类本身，对应实例方法的 self。

class Config:
    @classmethod
    def from_env(cls) -> "Config":
        return cls()

调用方式：Config.from_env()，方法内部可通过 cls 实例化当前类。

2. 返回值前向引用 "类名"

当类定义未完成，注解中直接使用类名会报未定义错误，将类名用引号包裹形成字符串，实现延迟解析，单引号、双引号效果完全一致。
Python3.7+ 文件头部添加 from __future__ import annotations，可省略引号直接书写类型。

3. Optional 类型

导入自 typing，Optional[T] 等价于 Union[T, None]，用于标记变量、参数、返回值可以是指定类型或 None。

• 旧写法：from typing import Optional; val: Optional["ToolRegistry"]
• 3.10+ 简化写法：val: "ToolRegistry" | None

区分两个概念：

1. 类型可选：Optional[int]，允许值为 None；
2. 参数可省略：def func(x: int = None)，函数调用时可不传该参数。
   二者常结合使用：def func(x: Optional[int] = None)。

二、字符串格式化：f-string 与静态模板

1. f-string 适用场景

f-string 会在字符串定义时立刻插值，要求当前作用域存在全部填充变量，适合一次性、即时拼接场景：

1. 打印日志、控制台输出；
2. 函数内部临时拼接短文本、报错信息；
3. 数值精度、进制、日期格式化；
4. 循环内批量生成短句；
5. 无需复用的单行短提示词。

2. 不适合使用 f-string 的场景

1. 全局常量模板：定义常量时无运行时变量，直接抛出 NameError；
2. 多文件复用的长文本模板（ReAct 提示词、邮件模板）；
3. 需要持久存储、读取后再填充的模板文本；
4. 多行系统提示词、Agent 工作流模板。

3. 静态模板标准写法

使用普通字符串保留 {变量名} 占位符，运行时通过 .format() 延迟填充：

PROMPT = """问题：{question}，工具列表：{tools}"""
filled_prompt = PROMPT.format(question="xxx", tools=[])

三、Python 包与目录区分（PyCharm 操作）

1. 两个目录类型本质区别

1. Directory（普通目录）
   仅创建空白文件夹，不生成 __init__.py，Python 不会识别为可导入包，不支持跨文件导入、相对导入。
   适用场景：存放日志、数据集、静态资源、运行产物、一次性脚本。

2. Python Package（Python 软件包）
   创建文件夹并自动生成 __init__.py，被 Python 识别为标准导入包，支持 import、相对导入。
   适用场景：存放业务模块、工具类、可被其他文件导入的 .py 代码。

2. __init__.py 文件作用

1. Python3.3 前必须存在，文件夹才可作为包导入；新版本支持无文件的命名空间包，但工程开发仍建议统一添加；
2. 控制包对外导出 API，简化外部导入语句；
3. 导入包时自动执行内部初始化代码，定义版本、全局配置；
4. 稳定适配类型检查工具、IDE 代码补全、打包发布流程。

3. 快速判断规则

• 文件夹内代码需要被其他文件 import → 新建 Python Package；
• 仅存放文件、数据、资源，无需导入代码 → 新建普通 Directory。

4. 目录转换小技巧

普通目录右键新建 Python Package，会自动补充 __init__.py；删除包内 __init__.py，包降级为普通目录。