Shutil 標準庫： Python 文件操作的萬用刀

作者：piperliu 2024-12-23 07:35:00

今天來聊一個被低估的 Python 標準庫 - shutil 。工作中我們用 Python （尤其是寫一些短小輕快的腳本）雖然經常和文件打交道，卻很少用到 shutil 。但實際上， shutil 提供了比 os 模塊更高級的文件操作接口，能讓我們寫出更 Pythonic 的代碼。

從一個真實場景說起

最近在整理項目代碼時，需要將散落在各處的配置文件歸類到統一目錄。按以往的習慣，我會這樣寫：

import os

# 創建目標目錄
if not os.path.exists("configs"):
    os.makedirs("configs")

# 移動文件
for root, dirs, files in os.walk("."):
    for file in files:
        if file.endswith(".conf"):
            src = os.path.join(root, file)
            dst = os.path.join("configs", file)
            os.rename(src, dst)

這段代碼能完成任務，但存在幾個問題：

如果目標路徑已存在同名文件會報錯
不支持跨設備移動
沒有保留文件的元數據(權限、時間戳等)

用 shutil 可以優雅地解決這些問題：

import shutil
import os

os.makedirs("configs", exist_ok=True)
for root, dirs, files in os.walk("."):
    for file in files:
        if file.endswith(".conf"):
            src = os.path.join(root, file)
            dst = os.path.join("configs", file)
            shutil.move(src, dst)

看起來差別不大，但 shutil.move() 會：

當目標路徑已存在同名文件時, shutil.move() 的行為取決于操作系統

Windows：如果目標文件存在且正在使用，會拋出 PermissionError ；否則會靜默覆蓋目標文件
Unix/Linux：會遵循操作系統的規則。如果用戶有權限，會覆蓋目標文件；否則拋出 PermissionError

支持跨設備移動

"跨設備"指的是在不同的文件系統或存儲設備之間移動文件,比如從 C 盤移動到 D 盤、從本地磁盤移動到網絡驅動器、從固態硬盤移動到 U 盤。

shutil.move() 會首先嘗試使用 os.rename() ，如果失敗且錯誤是跨設備錯誤 errno.EXDEV ，則復制文件到目標位置，驗證復制成功，最后刪除源文件。

保留源文件的所有元數據。

shutil 常用操作詳解

1. 復制文件和目錄

# 復制文件
shutil.copy("source.txt", "dest.txt")      # 復制文件內容
shutil.copy2("source.txt", "dest.txt")     # 復制文件內容和元數據

# 復制目錄
shutil.copytree("src_dir", "dst_dir")      # 遞歸復制整個目錄樹

copy2() 比 copy() 多了preserving metadata 的功能，在需要保留文件屬性時很有用。

2. 刪除目錄

# 刪除目錄樹
shutil.rmtree("dir_to_remove")             # 遞歸刪除目錄及其內容

比 os.rmdir() 強大，后者只能刪除空目錄。

3. 磁盤使用統計

total, used, free = shutil.disk_usage(".")
print(f"總空間: {total // (2**30)} GiB")
print(f"已使用: {used // (2**30)} GiB")
print(f"可用: {free // (2**30)} GiB")

直觀地獲取磁盤使用情況，免去了手動計算的麻煩。

4. 文件打包與壓縮

# 創建壓縮包
shutil.make_archive("backup", "zip", "source_dir")   # 支持zip、tar等格式

# 解壓縮
shutil.unpack_archive("backup.zip", "extract_dir")

實用腳本示例

1. 項目備份工具

import shutil
from datetime import datetime
import os

def backup_project(project_path, backup_dir="backups"):
    # 創建以時間戳命名的備份文件
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    backup_name = f"backup_{timestamp}"
    
    # 確保備份目錄存在
    os.makedirs(backup_dir, exist_ok=True)
    
    # 創建壓縮包
    archive_path = shutil.make_archive(
        os.path.join(backup_dir, backup_name),
        "zip",
        project_path
    )
    
    print(f"備份完成: {archive_path}")

2. 大文件搬運工具

import shutil
import os
from pathlib import Path

def move_large_files(src_dir, dst_dir, min_size_mb=100):
    """移動大于指定大小的文件到目標目錄"""
    dst_path = Path(dst_dir)
    dst_path.mkdir(exist_ok=True)
    
    for root, _, files in os.walk(src_dir):
        for file in files:
            file_path = Path(root) / file
            if file_path.stat().st_size > min_size_mb * 1024 * 1024:
                try:
                    shutil.move(str(file_path), dst_path / file)
                    print(f"已移動: {file}")
                except Exception as e:
                    print(f"移動失敗 {file}: {e}")

3. 智能文件分類器

import shutil
from pathlib import Path
import mimetypes

def organize_files(directory):
    """根據文件類型自動分類文件"""
    directory = Path(directory)
    
    # 遍歷所有文件
    for file_path in directory.rglob("*"):
        if file_path.is_file():
            # 獲取文件類型
            mime_type, _ = mimetypes.guess_type(str(file_path))
            if mime_type:
                category = mime_type.split("/")[0]
                
                # 創建分類目錄
                dest_dir = directory / category
                dest_dir.mkdir(exist_ok=True)
                
                # 移動文件
                try:
                    shutil.move(str(file_path), str(dest_dir / file_path.name))
                except Exception as e:
                    print(f"處理{file_path}時出錯: {e}")

性能提示

對于大文件操作，shutil 提供了 copyfileobj() 方法，支持設置緩沖區大小：

with open("source.dat", "rb") as fsrc:
    with open("dest.dat", "wb") as fdst:
        shutil.copyfileobj(fsrc, fdst, length=1024*1024)  # 1MB buffer

copytree() 支持多進程并行復制：

from multiprocessing import Pool

def copy_with_progress(src, dst):
    shutil.copy2(src, dst)
    return dst

with Pool(processes=4) as pool:
    shutil.copytree("src_dir", "dst_dir", copy_function=pool.map)

文件屬性操作

1. 權限和所有權

import shutil
import os

def mirror_permissions(src, dst):
    # 復制權限位
    shutil.copymode(src, dst)
    
    # 復制所有權(需要root權限)
    try:
        shutil.chown(dst, 
                     user=os.stat(src).st_uid,
                     group=os.stat(src).st_gid)
    except PermissionError:
        print("需要管理員權限來修改所有權")

2. 元數據復制

import shutil
import os
from datetime import datetime

def show_metadata(path):
    stat = os.stat(path)
    print(f"訪問時間: {datetime.fromtimestamp(stat.st_atime)}")
    print(f"修改時間: {datetime.fromtimestamp(stat.st_mtime)}")
    print(f"創建時間: {datetime.fromtimestamp(stat.st_ctime)}")
    print(f"權限: {oct(stat.st_mode)[-3:]}")
    print(f"大小: {stat.st_size} bytes")

# 復制文件并保留所有元數據
src = "source.txt"
dst = "dest.txt"
shutil.copy2(src, dst)

print("源文件元數據:")
show_metadata(src)
print("\n目標文件元數據:")
show_metadata(dst)

總結

shutil 是一個設計優雅的文件操作庫：

提供了比 os 模塊更高級的接口
自動處理各種邊界情況
保持了 Python "batteries included" 的理念

下次遇到文件操作需求，不妨先看看 shutil 是否已經提供了合適的工具。畢竟，"不要重復發明輪子"也是 Python 的哲學之一。

責任編輯：姜華來源： Piper蛋窩