---
doc_type: short
full_text: sources/02_Logging.md
---

# 02_Logging 总结

## 核心主题

本文介绍 Python 标准库中的 `logging` 模块，说明如何用日志替代直接 `print()` 或静默忽略异常，从而让诊断信息的输出方式、详细程度和目的地变得可配置。相关主题可连接到 Python日志记录、[[concepts/异常处理]]、程序诊断。

## 为什么需要 logging

在解析文件或处理输入数据时，程序经常会遇到格式错误或类型转换失败。例如 `parse()` 或 `parse_csv()` 中可能捕获 `ValueError`。

传统处理方式有两个极端：

- 直接打印错误信息：适合调试或提醒用户，但不够灵活。
- 使用 `pass` 静默忽略：避免干扰用户，但可能掩盖问题。

这两种方式都不理想，因为真实程序往往需要根据运行环境选择不同策略：开发时希望看到详细原因，生产时可能只记录警告或只保留严重错误。`logging` 模块正是为这种可配置诊断而设计的。

## logging 的基本用法

模块通常先创建一个 logger：

```python
import logging
log = logging.getLogger(__name__)
```

使用 `__name__` 创建 logger 的好处是日志来源会自动对应当前模块名，例如 `fileparse`。这使得不同模块的日志可以被分别控制。

常用日志级别包括：

```python
log.critical(message, *args)
log.error(message, *args)
log.warning(message, *args)
log.info(message, *args)
log.debug(message, *args)
```

它们表示不同严重程度：

- `CRITICAL`：最严重的问题。
- `ERROR`：错误。
- `WARNING`：警告，默认通常会显示。
- `INFO`：普通运行信息。
- `DEBUG`：调试细节。

日志消息采用 `%` 风格格式化：

```python
log.warning("Couldn't parse : %s", line)
```

这比提前构造字符串更符合 logging 的使用习惯。

## 在异常处理中使用 logging

原来的异常处理可能是：

```python
except ValueError as e:
    print("Couldn't parse :", line)
    print("Reason :", e)
```

改成 logging 后：

```python
except ValueError as e:
    log.warning("Couldn't parse : %s", line)
    log.debug("Reason : %s", e)
```

这种写法把“发生了坏数据”作为 `warning`，把“具体异常原因”作为 `debug`。这样默认情况下用户可以看到主要问题，而开发者可以通过提高日志详细程度查看原因。

## logging 配置与调用分离

本文强调一个重要设计原则：产生日志的代码和配置日志行为的代码应当分离。

模块内部只负责发出日志：

```python
log.warning(...)
log.debug(...)
```

程序入口负责配置日志系统：

```python
import logging
logging.basicConfig(
    filename='app.log',
    level=logging.INFO,
)
```

这种分离让库代码不必关心日志写到哪里、格式是什么、显示哪些级别；这些都由主程序或运行环境决定。该思想与 关注点分离 有关。

## 练习 8.2：给模块添加日志

练习要求修改 `fileparse.py` 中的 `parse_csv()`，把类型转换失败时的 `print()` 替换为 `logging` 调用。

原代码中，当某一行转换失败时：

```python
print(f"Row {rowno}: Couldn't convert {row}")
print(f"Row {rowno}: Reason {e}")
```

修改后：

```python
log.warning("Row %d: Couldn't convert %s", rowno, row)
log.debug("Row %d: Reason %s", rowno, e)
```

这样做的效果是：

- 默认只看到 `WARNING` 及以上级别的信息。
- 如果配置 logger 为 `DEBUG`，可以看到更详细的异常原因。
- 如果设置为 `CRITICAL`，则普通警告和调试信息都会被关闭。

示例控制方式：

```python
logging.getLogger('fileparse').setLevel(logging.DEBUG)
```

或关闭大部分信息：

```python
logging.getLogger('fileparse').setLevel(logging.CRITICAL)
```

这说明 logger 可以按模块名独立控制，适合大型程序的诊断管理。

## 练习 8.3：给程序添加日志配置

要让整个应用使用 logging，需要在主程序启动阶段初始化日志系统。例如：

```python
import logging
logging.basicConfig(
    filename='app.log',
    filemode='w',
    level=logging.WARNING,
)
```

配置项含义：

- `filename`：日志输出文件；省略时通常输出到标准错误。
- `filemode`：写入模式，`w` 表示覆盖，`a` 表示追加。
- `level`：最低输出级别，如 `DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`。

本文提示应思考：在 `report.py` 这类主程序中，日志配置应放在程序启动入口，而不是放进通用工具模块。通常可放在 `if __name__ == '__main__':` 分支中。

## 关键收获

1. `logging` 比 `print()` 更适合程序诊断，因为它可配置、可分级、可按模块管理。
2. 日志级别允许区分警告、错误、调试细节等不同信息。
3. 库模块应只发出日志，不应决定日志写到哪里或显示多少。
4. 主程序负责一次性初始化 logging 配置。
5. 在异常处理中，可以用 `warning` 记录用户应知道的问题，用 `debug` 记录开发者需要的细节。

## 相关概念

- Python日志记录
- [[concepts/异常处理]]
- 程序诊断
- 关注点分离
- 模块化程序设计

## Related Concepts
- [[concepts/测试-日志与调试]]
- [[concepts/库接口设计]]
- [[concepts/main-函数与脚本结构]]
- [[concepts/CSV-数据处理]]
- [[concepts/文件读写]]
- [[concepts/模块与-import]]
- [[concepts/Python-输入输出]]