Python标准库常用模块速查：os、sys与datetime核心用法

在编写 Python 实用脚本、自动化运维任务或后端服务时，绝大部分基础能力无需安装任何第三方库。Python 内置的 os、sys 与 datetime 构成了日常工程使用频率最高的基础三角：os 负责承接操作系统与文件系统交互，sys 掌管 Python 解释器运行时状态与进程出入口，datetime 则支撑起时间戳、日期解析和时间维度的业务计算。掌握这三者的核心用法与协同范式，能解决超过八成的数据存取、命令行控制与日志管理需求。

一、os 模块：操作系统环境与文件系统交互

os 模块的核心作用是充当 Python 与底层操作系统的桥梁。无论是在 macOS、Linux 还是 Windows 上运行，os 都能以统一的接口完成文件目录创建、遍历扫描、路径标准化以及环境变量管理。

1. 路径规范化与跨平台拼接

不同操作系统的文件路径分隔符不同（Windows 使用反斜杠 \，Linux 与 macOS 使用正斜杠 /）。手动拼写斜杠极易在多平台部署时崩溃。核心原则是始终使用 os.path.join() 拼接路径，并使用 os.path.abspath() 获取规范绝对路径：

import os

# 1. 跨平台安全拼接
base_dir = os.path.abspath(".")
target_file = os.path.join(base_dir, "logs", "app.log")
print(f"目标文件绝对路径: {target_file}")

# 2. 拆解路径成分
dir_name = os.path.dirname(target_file)       # 获取上级目录: .../logs
file_name = os.path.basename(target_file)     # 获取文件名: app.log
name, ext = os.path.splitext(file_name)       # 拆分主体与后缀: ('app', '.log')

# 3. 存在性与类型检查
if os.path.exists(target_file):
    is_f = os.path.isfile(target_file)
    is_d = os.path.isdir(target_file)
    print(f"是否存在: True, 是否文件: {is_f}, 是否目录: {is_d}")

2. 目录创建与防御性参数

创建目录时，传统的 os.mkdir() 只能创建单层目录，且在目录已存在时抛出 FileExistsError。在生产脚本中，应使用 os.makedirs() 并显式设置 exist_ok=True，它支持递归建立整条父级路径，且如果目录已存在不会报错：

# 递归建立多级目录，即使目录已存在也安全通过
output_dir = os.path.join(".", "data", "archive", "2026")
os.makedirs(output_dir, exist_ok=True)

3. 目录扫描：优先选用 os.scandir()

早期 Python 常用 os.listdir() 列举目录下所有文件名字，但如果随后需要判断是文件还是目录（os.path.isfile）或读取大小（os.path.getsize），每次都会触发一次系统 stat 调用。在处理上万级文件的目录时，性能损耗巨大。Python 3.5 起引入的 os.scandir() 返回迭代器，在系统底层枚举目录时直接缓存了文件类型和元数据，性能通常高出数倍：

# 推荐的扫描与遍历方式：使用上下文管理器
scan_path = "."
with os.scandir(scan_path) as entries:
    for entry in entries:
        if entry.is_file() and entry.name.endswith(".py"):
            stat_info = entry.stat()
            print(f"脚本文件: {entry.name}, 大小: {stat_info.st_size} 字节, 修改时间戳: {stat_info.st_mtime}")
        elif entry.is_dir():
            print(f"子目录: {entry.name}")

二、sys 模块：解释器交互与运行环境控制

如果说 os 面向的是操作系统，那么 sys 面向的则是 Python 解释器自身。sys 提供了对解释器内部变量、模块导入搜索路径、标准输入输出流以及脚本生命周期退出的完全控制能力。

1. 命令行参数解析 sys.argv

通过命令行调用脚本时（如 python script.py --env prod 8080），解释器会将所有入参打包为列表存入 sys.argv。其中：

• sys.argv[0]：始终是当前被执行脚本的文件名或相对路径。
• sys.argv[1:]：由用户传入的后续参数，元素类型全部为字符串 str。

import sys

def main():
    # 基础参数校验
    if len(sys.argv) < 2:
        print("错误: 缺少必要参数！用法: python script.py <action> [env]", file=sys.stderr)
        sys.exit(1)  # 非 0 退出码表示执行异常

    action = sys.argv[1]
    env = sys.argv[2] if len(sys.argv) > 2 else "development"
    print(f"执行任务: {action}, 目标环境: {env}")

if __name__ == "__main__":
    main()

2. 动态调整导包路径 sys.path

sys.path 是一个包含所有模块搜索路径的字符串列表。当执行 import something 时，Python 会依序遍历该列表寻找对应模块。在多目录项目架构中，如果需要从上级或同级兄弟目录引入公共模块，动态添加路径是最简单可靠的做法：

import sys
import os

# 获取当前脚本所在目录的上级目录，并插入到搜索路径最前端
current_dir = os.path.dirname(os.path.abspath(__file__))
parent_dir = os.path.abspath(os.path.join(current_dir, ".."))

if parent_dir not in sys.path:
    sys.path.insert(0, parent_dir)  # 使用 insert(0, ...) 确保最高优先级

3. 进程退出与状态码：sys.exit()

在编写自动化脚本时，脚本退出时向调用方返回的状态码（Exit Code）至关重要。CI/CD 流水线或 Shell 脚本通常依赖 $? 判断成功与否：

• sys.exit(0)：正常成功退出。
• sys.exit(1) 或其他非零正整数：异常退出，告知外界任务未按预期完成。

需要注意，sys.exit() 的本质是在底层抛出一个 SystemExit 异常。如果外层有不规范的 except Exception: 捕获，不会拦截 SystemExit；但若写了 except BaseException: 则会拦截退出流程。因此，如需做退出清理，应优先使用 try...finally 结构。

三、datetime 模块：时间对象、格式化与时间跨度运算

datetime 模块为日常时间处理提供了面向对象的完整支持。在实际项目中，我们主要使用该模块下的四个核心类：datetime（日期+时间）、date（纯日期）、time（纯时间）与 timedelta（时间间隔跨度）。

1. 当前时间与格式化字符串互转

业务中最常见的需求是在时间对象与字符串之间互相转换，核心为两个方法：

• strptime(date_string, format)：String Parse Time，把文本解析为时间对象。
• strftime(format)：String Format Time，把时间对象格式化为人类可读的字符串。

from datetime import datetime

# 1. 获取当前系统时间
now = datetime.now()
print(f"当前时间对象: {now}")

# 2. 格式化输出 (对象 -> 字符串)
formatted_str = now.strftime("%Y-%m-%d %H:%M:%S")
print(f"格式化输出: {formatted_str}")  # 示例: 2026-10-31 08:30:15

# 3. 解析文本 (字符串 -> 对象)
source_str = "2026-10-01 14:20:00"
dt_obj = datetime.strptime(source_str, "%Y-%m-%d %H:%M:%S")
print(f"解析后的年份: {dt_obj.year}, 月份: {dt_obj.month}, 小时: {dt_obj.hour}")

2. 时间跨度运算 timedelta

对时间做“加减法”必须借助 timedelta。它可以指定 days、seconds、microseconds、milliseconds、minutes、hours 与 weeks。不支持直接传入 months 或 years，因为月份与平闰年天数不固定。

from datetime import datetime, timedelta

current_time = datetime.now()

# 1. 顺延与回溯运算
three_days_ago = current_time - timedelta(days=3)
two_hours_later = current_time + timedelta(hours=2)

print(f"三天前: {three_days_ago.strftime('%Y-%m-%d %H:%M')}")
print(f"两小时后: {two_hours_later.strftime('%Y-%m-%d %H:%M')}")

# 2. 两个 datetime 相减计算时间差
start_time = datetime(2026, 10, 1, 9, 0, 0)
end_time = datetime(2026, 10, 5, 15, 30, 0)
duration = end_time - start_time  # 得到 timedelta 对象

print(f"间隔天数: {duration.days} 天")
print(f"总秒数: {duration.total_seconds()} 秒")

3. 时区感知（Aware）与朴素时间（Naive）

默认情况下，datetime.now() 返回的是没有时区信息的“朴素时间（Naive）”。在分布式系统或海外服务器部署时，极易因服务器本地时区不同导致日志时间错乱。Python 3.2+ 推荐引入 timezone.utc 处理标准 UTC 时间：

from datetime import datetime, timezone

# 获取带明确 UTC 时区感知的时间对象 (Aware)
utc_now = datetime.now(timezone.utc)
print(f"UTC Aware 时间: {utc_now}")

# 转换为本地当前时区
local_now = utc_now.astimezone()
print(f"本地转换后时间: {local_now}")

四、实战演练：三大模块协同的日志自动归档脚本

在实际生产中，这三个模块常常协同工作。下面展示一段结构严谨的运维脚本：从命令行接收目标目录与清理阈值（sys.argv），遍历目标路径下的日志文件（os.scandir），通过时间戳换算判断是否超过天数（datetime.fromtimestamp + timedelta），自动归档到对应月份文件夹（os.makedirs + os.replace），并在发生异常时通过 sys.exit(1) 返回错误状态码：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import os
import sys
from datetime import datetime, timedelta

def archive_old_logs(target_dir: str, days_threshold: int = 30):
    """
    归档超过指定天数未修改的 .log 文件到按月命名的归档子目录
    """
    if not os.path.exists(target_dir):
        print(f"[错误] 目标目录不存在: {target_dir}", file=sys.stderr)
        sys.exit(1)

    now = datetime.now()
    cutoff_time = now - timedelta(days=days_threshold)
    archived_count = 0

    print(f"[*] 扫描目录: {os.path.abspath(target_dir)}")
    print(f"[*] 清理截止时间点: {cutoff_time.strftime('%Y-%m-%d %H:%M:%S')} (阈值: {days_threshold} 天)")

    try:
        with os.scandir(target_dir) as entries:
            for entry in entries:
                # 仅处理根目录下的 .log 文件，忽略子文件夹
                if entry.is_file() and entry.name.endswith(".log"):
                    stat_info = entry.stat()
                    # 将系统时间戳转换为 datetime 对象
                    mtime = datetime.fromtimestamp(stat_info.st_mtime)

                    if mtime < cutoff_time:
                        # 生成按年月命名的归档路径，例如: target_dir/archive/2026-09
                        month_folder = mtime.strftime("%Y-%m")
                        dest_folder = os.path.join(target_dir, "archive", month_folder)
                        os.makedirs(dest_folder, exist_ok=True)

                        dest_file_path = os.path.join(dest_folder, entry.name)
                        # 安全移动文件 (跨平台原子重命名)
                        os.replace(entry.path, dest_file_path)
                        print(f"  [+] 已归档: {entry.name} -> archive/{month_folder}/")
                        archived_count += 1

        print(f"[完成] 归档任务结束，共处理 {archived_count} 个日志文件。")
        sys.exit(0)

    except PermissionError as e:
        print(f"[权限错误] 无法读写文件: {e}", file=sys.stderr)
        sys.exit(2)
    except Exception as e:
        print(f"[未知异常] 执行中断: {e}", file=sys.stderr)
        sys.exit(3)

if __name__ == "__main__":
    # 参数解析: python archive_tool.py <dir_path> [days]
    if len(sys.argv) < 2:
        print("用法: python archive_tool.py <日志目录路径> [归档天数阈值, 默认30]")
        sys.exit(1)

    dir_input = sys.argv[1]
    days_input = int(sys.argv[2]) if len(sys.argv) > 2 else 30
    archive_old_logs(dir_input, days_input)

五、三大模块核心用法速查总结矩阵

为了便于日常编码即查即用，下表总结了三大模块最常用的函数与核心应用要点：

熟练运用上述模式，在不需要庞大外部依赖的前提下，即可构建出性能优异、鲁棒性强且便于维护的工程脚本。