import、from … import 与 as#

模块是包含 Python 定义的 .py 文件；导入后，模块级名字通过 模块名.名字 访问。Modules 说明三种常用形式：

1
import math
2
print(math.sqrt(2))
3

4
from math import sqrt, pi
5
print(sqrt(2), pi)
6

7
import datetime as dt  # as 起短别名

import 会先查 sys.modules 缓存；未加载则执行模块顶层代码一次，再缓存。因此模块里的「副作用」（如打印、注册）只在首次导入时发生。

from module import name 把 name 绑定到当前命名空间；from module import * 会把 __all__ 列出的名字（若未定义 __all__ 则除以下划线开头外的名字）导入，不推荐在应用代码里使用——污染命名空间且难静态分析。

查看模块里有什么：dir(math)（Modules）。开发时热重载可用 importlib.reload(mod)，一般脚本用不到。

命令行参数在 sys.argv（官方 stdlib 导览）：

1
import sys
2
print(sys.argv)  # [脚本路径, 后续参数...]

相对导入（包内）：from . import sibling、from ..package import module，见 Intra-package References。仅在包内模块中使用，且模块作为包的一部分被导入时有效。

导入搜索路径由 sys.path 决定：脚本目录、PYTHONPATH、标准库、site-packages 等。不要依赖当前工作目录隐式导入同目录模块以外的路径，除非路径已加入 sys.path（更推荐安装包或正确布局项目）。

包与 init.py#

Packages：import pkg.mod 时，pkg 是包——含 __init__.py 的目录（常规包），或符合 namespace package 规则的目录（可无 __init__.py，见 PEP 420）。__init__.py 可以为空，也可执行包级初始化、定义 __all__。

1
sound/
2
    __init__.py
3
    effects/
4
        __init__.py
5
        echo.py

from sound.effects import echo 后使用 echo.surround()。包内子模块也是完整模块名：sound.effects.echo。

打包发布见 pyproject.toml，这里只记「目录 + __init__.py + 相对导入」。

if name == ‘main’#

脚本直接运行时，__name__ 为 '__main__'；被 import 时为模块名（如 'mymodule'）。惯用法：

1
def main():
2
    ...
3

4
if __name__ == "__main__":
5
    main()

这样 import mymodule 不会执行 main()，但可直接 python mymodule.py 启动。更大项目可以用 python -m pkg.module（-m 搜索）。

print 与 input：格式化复习#

Input and Output 涵盖字符串表示与格式化。

print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False) — 把对象转成字符串写出。多个参数默认空格分隔；end 改结尾；file 可写到文件或 StringIO。

input(prompt='') — 从 sys.stdin 读一行，返回 str（去掉末尾换行）。要做数值运算需自己 int() / float()。

格式化方式（官方均仍有效，日常优先 f-string）：

1
name, n = "Alice", 3
2
print(f"{name} has {n} apples")           # f-string（3.6+，推荐）
3
print("{} has {} apples".format(name, n)) # str.format
4
print("%s has %d apples" % (name, n))     # % 格式化（类似 C）
5
print(f"{1/3:.2%}")   # 33.33%
6
print(f"{255:#x}")    # 0xff

str.format 与 Format Specification Mini-Language 支持对齐、宽度、精度、进制等。f-string 在大括号内可写表达式：f"{obj!r}" 调 repr()。

调试可读输出：pprint 美化嵌套结构；json.dumps 适合 JSON 可序列化数据（第 8 篇下文标准库再提 json）。

open 读写与 with#

open(file, mode='r', encoding=None, ... ) 返回 text 或 binary 流。文本模式默认编码依平台，应显式传 encoding='utf-8'（UTF-8 模式 在 3.7+ 可通过 -X utf8 或 PYTHONUTF8 影响默认行为）。

常用模式：'r' 读、'w' 写（清空）、'a' 追加、'x' 独占创建、'r+' 读写；加 'b' 为二进制（encoding 无效）。

1
with open("notes.txt", "w", encoding="utf-8") as f:
2
    f.write("第一行\n")
3
    f.writelines(["第二行\n", "第三行\n"])
4

5
with open("notes.txt", "r", encoding="utf-8") as f:
6
    whole = f.read()       # 整个文件 str
7
    # 或 for line in f:   # 逐行，省内存
8
    # 或 lines = f.readlines()

文件对象实现上下文管理器，离开 with 会 close()。不用 with 时须自己 f.close()，且异常时可能泄漏句柄。

二进制示例：with open("img.bin", "rb") as f: data = f.read()。CSV、JSON 见 csv、json。

文本流常用方法见 io.IOBase（菜鸟 File 方法 有表，以官方为准）：

'w+' 写完后若要读回去，须先 seek(0)。

路径：pathlib 优先，兼提 os.path#

pathlib（3.4+）用面向对象路径替代字符串拼接。推荐新项目优先 Path：

1
from pathlib import Path
2

3
p = Path("data") / "logs" / "app.log"  # 跨平台拼接
4
p.parent.mkdir(parents=True, exist_ok=True)
5
p.write_text("hello\n", encoding="utf-8")
6
text = p.read_text(encoding="utf-8")
7
print(p.suffix, p.stem, p.resolve())

常用：exists()、is_file()、is_dir()、glob()、iterdir()、rename()、unlink()（删文件）。PurePath 不做 I/O，只算路径。

旧代码与 C 风格 API 仍常见 os.path：os.path.join、dirname、basename、abspath、splitext。二者可互转：Path(p)、str(path)。需要 stat、权限位时，Path.stat() 或 os.stat。

当前工作目录：Path.cwd()；改变用 os.chdir（改变进程全局状态，脚本里慎用）。

os 常用（一句一段）#

os 提供操作系统接口；与路径无关的常见调用：

• os.environ：环境变量映射，可读可写；取值也可用 os.getenv。
• os.listdir(path) / os.scandir(path)：列目录（后者更高效，可拿类型信息）。
• os.mkdir / os.makedirs：建目录；makedirs(..., exist_ok=True) 类似 Path.mkdir。
• os.walk(top)：递归遍历目录树（官方 os.walk）。
• os.replace：覆盖式重命名，跨平台比 rename 稳。
• os.getpid()、os.cpu_count()：进程 id、CPU 数。

跨平台脚本优先 pathlib + os.environ；子进程、权限、文件描述符再看 os 与 subprocess。

class：最简面向对象#

Classes：class 定义类型。实例属性通常挂在 self 上；方法是类命名空间里的函数，第一个参数 conventionally 叫 self（由调用机制自动传入）。

1
class Dog:
2
    kind = "canine"  # 类属性，共享
3

4
    def __init__(self, name):
5
        self.name = name  # 实例属性
6

7
    def bark(self):
8
        return f"{self.name}: woof!"
9

10
d = Dog("Rex")
11
print(d.bark(), Dog.kind)

__init__ 在实例创建后初始化，不是分配内存的构造器（那是 __new__，入门 Rarely 需要）。__repr__ / __str__ 控制 repr(obj) 与 str(obj) / print(obj)。

继承：

1
class Animal:
2
    def __init__(self, name):
3
        self.name = name
4

5
class Cat(Animal):
6
    def __init__(self, name, indoor=True):
7
        super().__init__(name)  # 调父类 __init__
8
        self.indoor = indoor

super() 在单继承里找父类实现；多继承按 MRO（方法解析顺序）线性化，入门先写单继承即可。

数据 vs 方法：Python 不强制访问控制；约定 _single 内部、__double 触发名称改写（name mangling）。菜鸟写的「私有属性类外无法访问」不完全准确：改写后仍可通过 _类名__属性 碰到，只是不鼓励。@property 把方法当属性读；@classmethod / @staticmethod 见官方教程 Class and Instance Variables。

Everything is object：类本身也是对象，可传参、可存于容器；这与 Java/C++ 静态类型习惯不同，见教程 Odds and Ends。

类型注解入门#

PEP 484 函数注解、PEP 526 变量注解、PEP 585 内置泛型 list[int]、PEP 604 的 X | Y（3.10+）。运行时默认不强制检查；要用静态检查可跑 mypy（菜鸟 类型注解 有示例）。

1
def greet(name: str, times: int = 1) -> str:
2
    return (name + "! ") * times
3

4
def sum_all(nums: list[float]) -> float:
5
    return sum(nums)
6

7
from typing import Optional
8

9
def find(items: list[str], key: str) -> Optional[str]:
10
    return key if key in items else None

常用 typing 名字：

• Optional[T] — 等价于 T | None（3.10+ 更常写 Union 或 |）。
• Union[A, B] / A | B — 多种类型之一。
• list[int]、dict[str, int] — 泛型容器（3.9+ 内置泛型；旧代码见 List、Dict from typing）。
• Callable[[int, str], bool] — 可调用签名。
• Iterable[T]、Sequence[T] — 只读迭代 / 序列抽象。
• TypedDict、Protocol、NamedTuple — 结构化数据（用到再查）。

变量也可注解：count: int = 0。类属性：class User: id: int; name: str。延迟解析字符串注解：from __future__ import annotations（3.7+；3.11+ 部分行为默认变化见 What’s New）。

typing.get_type_hints() 可在运行时取注解。学习阶段：先写能跑的代码，再逐步加注解；不要为注解牺牲清晰逻辑。

venv：虚拟环境#

venv 创建轻量隔离环境，各自拥有 python 与 pip（或 ensurepip 引导），包安装不污染系统 Python。

1
python -m venv .venv
2
# Windows PowerShell:
3
.\.venv\Scripts\Activate.ps1
4
# Unix / macOS:
5
source .venv/bin/activate

激活后 which python / where python 应指向 .venv。安装依赖：python -m pip install requests。冻结清单：python -m pip freeze > requirements.txt，再 python -m pip install -r requirements.txt。退出：deactivate。指定解释器版本：python3.12 -m venv .venv。

项目根常见 .venv/ 加入 .gitignore；依赖列表用 requirements.txt 或 pyproject.toml（Packaging User Guide 超出本札记）。不要把虚拟环境目录当源码提交。

virtualenv 是第三方替代；conda 是另一套生态。官方教程 Virtual Environments and Packages 与 venv 文档一致即可。

标准库地图（各一句）#

Brief Tour of the Standard Library 与 stdlib index 是总入口。常用模块各一句：

还常会用到：re、urllib / http、sqlite3、logging、unittest。

附录：import 形式速查#

附录：open 模式与 pathlib 对照#

附录：typing 常用符号（3.10+ 风格）#

运行时仍可能收到「不符合注解」的对象；类型检查交给静态工具，不要依赖注解做业务校验。

参考#

官方文档（中文版 可对照阅读）：

1. Modules — import、模块搜索路径、包、__init__.py、__name__
2. Input and Output — print、input、格式化、f-string、读写文件 intro
3. Classes — 属性、方法、继承、super、私有约定
4. Virtual Environments and Packages — venv 与 pip 工作流
5. Brief Tour of the Standard Library — 标准库导览
6. The import system — 导入语义、相对导入、namespace package
7. pathlib — Path / PurePath
8. os — 操作系统接口
9. os.path — 路径字符串函数
10. open() — 文件打开
11. io — 流基类
12. typing — 类型注解构造
13. venv — 创建虚拟环境
14. json — JSON
15. datetime — 日期时间
16. collections — 容器
17. itertools — 迭代工具
18. functools — 高阶函数工具
19. sys — 解释器
20. main — 主模块

PEP：

21. PEP 484 — Type Hints
22. PEP 526 — Syntax for Variable Annotations
23. PEP 585 — Type Hinting Generics In Standard Collections
24. PEP 604 — Allow writing union types as X | Y
25. PEP 420 — Implicit Namespace Packages
26. PEP 8 — Style Guide — import 顺序等

目录来源（骨架，不以它为准改语法）：

27. 菜鸟教程 · Python3 模块
28. 菜鸟教程 · Python3 输入和输出
29. 菜鸟教程 · Python3 文件方法
30. 菜鸟教程 · OS 文件/目录
31. 菜鸟教程 · Python3 面向对象
32. 菜鸟教程 · 虚拟环境
33. 菜鸟教程 · 类型注解
34. 菜鸟教程 · 标准库概览