Python 笔记：工程实践与常见陷阱

1
# uv init my_project（应用）
2
my_project/
3
├── .python-version
4
├── main.py
5
├── pyproject.toml
6
└── uv.lock
7

8
# uv init --package my_pkg（库，可被 import / 发布）
9
my_pkg/
10
├── pyproject.toml
11
├── uv.lock
12
└── src/
13
    └── my_pkg/
14
        └── __init__.py

1
.venv/
2
├── pyvenv.cfg        # 记录 Python 路径与版本
3
├── Scripts/          # Windows：可执行文件（python.exe、activate）
4
└── Lib/site-packages/  # 装好的第三方包

1
# /// script
2
# requires-python = ">=3.11"
3
# dependencies = [
4
#     "requests>=2.34.2",
5
# ]
6
# ///
7
import requests
8

9
print(requests.__version__)

1
project/
2
└── app/
3
    ├── __init__.py      # 有这个文件就是“包”
4
    ├── main.py          # 模块
5
    └── utils.py

1
ImportError: attempted relative import with no known parent package

1
def main() -> None:
2
    print("Hello from my-project")
3

4

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

1
from typing import TypeVar
2

3
T = TypeVar("T")
4

5
def first(items: list[T]) -> T | None:
6
    return items[0] if items else None

1
class Box[T]:
2
    def __init__(self, item: T):
3
        self.item = item

1
from typing import Protocol
2

3
class Reader(Protocol):
4
    def read(self) -> str: ...
5

6
class FileSource:
7
    def read(self) -> str:
8
        return "data"
9

10
def load(source: Reader) -> str:
11
    return source.read()
12

13
load(FileSource())   # 类型检查通过

1
from typing import TypedDict
2

3
class User(TypedDict):
4
    name: str
5
    age: int
6

7
user: User = {"name": "Mia", "age": 20}

1
from dataclasses import dataclass, field
2

3
@dataclass
4
class User:
5
    name: str
6
    age: int = 0
7
    tags: list[str] = field(default_factory=list)
8

9
u = User("Mia")
10
u.tags.append("admin")
11
print(u)   # User(name='Mia', age=0, tags=['admin'])

1
@dataclass(frozen=True, slots=True)
2
class Point:
3
    x: int
4
    y: int

1
class A:
2
    def hi(self): return "A"
3

4
class B(A):
5
    def hi(self): return "B" + super().hi()
6

7
class C(A):
8
    def hi(self): return "C" + super().hi()
9

10
class D(B, C):
11
    def hi(self): return "D" + super().hi()
12

13
print(D().hi())                          # DBCA
14
print([c.__name__ for c in D.__mro__])   # ['D', 'B', 'C', 'A', 'object']

1
from abc import ABC, abstractmethod
2

3
class Shape(ABC):
4
    @abstractmethod
5
    def area(self) -> float: ...
6

7
class Square(Shape):
8
    def __init__(self, side: float):
9
        self.side = side
10

11
    def area(self) -> float:
12
        return self.side ** 2

1
class Config:
2
    def __init__(self, data: dict):
3
        self.data = data
4

5
    @classmethod
6
    def from_file(cls, path: str) -> "Config":
7
        return cls({})            # 工厂方法，cls 是类本身
8

9
    @staticmethod
10
    def parse(text: str) -> dict:
11
        return {}                 # 不碰 self / cls，纯工具函数

1
class P:
2
    def __init__(self):
3
        self._x = 1      # 单下划线：约定私有，外部仍能访问
4
        self.__y = 2     # 双下划线：名字被改写
5

6
print(P().__dict__)   # {'_x': 1, '_P__y': 2}

1
from enum import Enum, auto
2

3
class Color(Enum):
4
    RED = auto()
5
    GREEN = auto()
6

7
print(Color.RED.name, Color.RED.value)   # RED 1
8
print(Color(1))                          # Color.RED

1
BaseException
2
├── SystemExit / KeyboardInterrupt
3
└── Exception
4
    ├── ValueError / TypeError / KeyError / IndexError
5
    ├── LookupError → KeyError, IndexError
6
    ├── OSError → FileNotFoundError, PermissionError
7
    └── RuntimeError ...

1
try:
2
    value = int(text)
3
except (TypeError, ValueError) as err:      # 可以一次捕多种
4
    print(type(err).__name__, err)
5
except KeyError:
6
    print("缺键")
7
else:
8
    print("没异常才执行", value)
9
finally:
10
    print("无论如何都执行")

1
class ConfigError(Exception):
2
    """配置错误"""
3

4

5
try:
6
    settings = {}
7
    settings["host"]
8
except KeyError as err:
9
    raise ConfigError("缺少 host 配置") from err

1
# finally 里的 return 会覆盖 try 里的 return
2
def f():
3
    try:
4
        return "try"
5
    finally:
6
        return "finally"
7

8
print(f())   # finally

1
# assert 会在 python -O 下被整体移除，不要拿它做参数校验
2
assert user_id > 0, "user_id 必须为正"

1
class AppError(Exception):
2
    """应用异常基类"""
3

4
class NotFoundError(AppError):
5
    pass
6

7
class PermissionDeniedError(AppError):
8
    pass

1
from pathlib import Path
2

3
p = Path("data") / "config.json"     # 用 / 拼路径，跨平台
4
print(p.exists(), p.suffix, p.stem, p.parent)
5
print(p.read_text(encoding="utf-8"))
6
p.write_text("内容", encoding="utf-8")
7

8
for f in Path("src").glob("**/*.py"):
9
    print(f)

1
import json
2

3
text = json.dumps({"name": "小明"}, ensure_ascii=False)
4
data = json.loads(text)
5

6
print(text)          # {"name": "小明"}
7
print(data["name"])  # 小明

1
from datetime import datetime, timedelta, timezone
2

3
now = datetime.now()                          # naive，没有时区信息
4
utc = datetime.now(timezone.utc)              # aware
5

6
print(now.isoformat(timespec="seconds"))
7
print((now + timedelta(days=1)).date())
8
print(datetime.fromtimestamp(1700000000, tz=timezone.utc).isoformat())

1
import re
2

3
m = re.match(r"(\d+)-(\d+)", "2026-11")
4
print(m.group(1), m.group(2))              # 2026 11
5

6
print(re.findall(r"\d+", "a1b22"))         # ['1', '22']
7
print(re.sub(r"\s+", " ", " a  b "))       #  a b

1
from collections import Counter, defaultdict, deque, namedtuple
2

3
dd = defaultdict(list)
4
dd["k"].append(1)                 # 不存在的键自动给默认值
5

6
print(Counter("hello").most_common(2))   # [('l', 2), ('h', 1)]
7

8
q = deque([1, 2])
9
q.popleft()                       # 两端操作都是 O(1)
10

11
Point = namedtuple("Point", "x y")
12
print(Point(1, 2)._asdict())      # {'x': 1, 'y': 2}

1
import itertools
2

3
print(list(itertools.chain([1], [2, 3])))                  # [1, 2, 3]
4
print(list(itertools.islice(itertools.count(0, 2), 5)))    # [0, 2, 4, 6, 8]
5
print(list(itertools.product("ab", repeat=2)))             # 笛卡尔积

1
import argparse
2

3
parser = argparse.ArgumentParser()
4
parser.add_argument("name")
5
parser.add_argument("--count", type=int, default=1)
6
args = parser.parse_args()
7

8
print(args.name, args.count)

1
import logging
2

3
logging.basicConfig(
4
    level=logging.INFO,
5
    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
6
)
7
logging.info("服务启动")

1
import hashlib, os, shutil, subprocess, tempfile
2
from pathlib import Path
3

4
hashlib.md5(b"abc").hexdigest()
5

6
os.getenv("MY_KEY", "default")            # 读环境变量
7
shutil.copy("a.txt", "b.txt")             # 复制文件
8
subprocess.run(["git", "status"], check=True)   # 执行外部命令
9

10
with tempfile.TemporaryDirectory() as tmp:
11
    print(tmp)                            # 用完自动清理

1
def f(a, /, b, *, c):
2
    return a, b, c
3

4
f(1, 2, c=3)        # ✅
5
f(a=1, b=2, c=3)    # ❌ a 是仅位置参数
6
f(1, 2, 3)          # ❌ c 是仅关键字参数

1
import time
2

3
def stamp(t=time.time()):
4
    return t
5

6
print(stamp() == stamp())   # True，两次是同一个时间

1
def add(item, items=None):
2
    if items is None:
3
        items = []
4
    items.append(item)
5
    return items

1
fns = [lambda: i for i in range(3)]
2
print([f() for f in fns])        # [2, 2, 2]
3

4
fns = [lambda i=i: i for i in range(3)]
5
print([f() for f in fns])        # [0, 1, 2]

1
import functools
2

3
def timed(fn):
4
    @functools.wraps(fn)
5
    def wrapper(*args, **kwargs):
6
        print("before", fn.__name__)
7
        return fn(*args, **kwargs)
8
    return wrapper
9

10
@timed
11
def add(a, b):
12
    return a + b
13

14
print(add(1, 2), add.__name__)   # before add / 3 add

1
def read_lines(path):
2
    with open(path, encoding="utf-8") as f:
3
        for line in f:
4
            yield line.rstrip()
5

6
for line in read_lines("big.log"):
7
    ...

1
gen = (x for x in [1, 2])
2
print(list(gen), list(gen))   # [1, 2] []

1
[tool.pytest.ini_options]
2
pythonpath = ["."]
3
testpaths = ["tests"]

1
[tool.ruff]
2
line-length = 100
3
target-version = "py314"
4

5
[tool.ruff.lint]
6
select = ["E", "F", "I"]     # pycodestyle / pyflakes / isort

1
breakpoint()        # 进入 pdb，比 console.log 好用