shutil — 高階檔案操作

原始碼: Lib/shutil.py

---

shutil 模組提供了許多關於檔案和檔案集合的高階操作。特別是，提供了支援檔案複製和刪除的函式。有關對單個檔案的操作，另請參閱 os 模組。

警告

即使是更高階的檔案複製函式 (shutil.copy(), shutil.copy2()) 也無法複製所有檔案元資料。

在 POSIX 平臺上，這意味著檔案所有者和組以及 ACL 會丟失。在 Mac OS 上，資源 fork 和其他元資料不會被使用。這意味著資源將會丟失，並且檔案型別和建立者程式碼將不正確。在 Windows 上，檔案所有者、ACL 和備用資料流不會被複制。

目錄和檔案操作

shutil.copyfileobj(fsrc, fdst[, length])

將 類檔案物件 fsrc 的內容複製到類檔案物件 fdst。如果給定整數 length，則它是緩衝區大小。特別是，負數 length 值表示在不迴圈遍歷源資料塊的情況下複製資料；預設情況下，資料以塊的形式讀取，以避免不受控制的記憶體消耗。請注意，如果 fsrc 物件的當前檔案位置不是 0，則只會複製從當前檔案位置到檔案末尾的內容。

shutil.copyfile(src, dst, *, follow_symlinks=True)

將名為 src 的檔案的內容（無元資料）複製到名為 dst 的檔案，並以儘可能高效的方式返回 dst。src 和 dst 是路徑類物件或以字串形式給出的路徑名。

dst 必須是完整的目標檔名；請檢視 copy()，它接受目標目錄路徑進行復制。如果 src 和 dst 指定相同的檔案，則會引發 SameFileError。

目標位置必須可寫；否則，將引發 OSError 異常。如果 dst 已經存在，它將被替換。不能使用此函式複製字元或塊裝置和管道等特殊檔案。

如果 follow_symlinks 為 false 且 src 是符號連結，則將建立一個新的符號連結，而不是複製 src 指向的檔案。

引發帶有引數 src、dst 的 審計事件 shutil.copyfile。

在 3.3 版本中更改: 以前引發 IOError 而不是 OSError。添加了 follow_symlinks 引數。現在返回 dst。

在 3.4 版本中更改: 引發 SameFileError 而不是 Error。由於前者是後者的子類，因此此更改向後相容。

在 3.8 版本中更改: 內部可以使用特定於平臺的快速複製系統呼叫，以便更有效地複製檔案。請參閱 平臺相關的快速複製操作 部分。

exception shutil.SameFileError

如果 copyfile() 中的源和目標是同一檔案，則會引發此異常。

在 3.4 版本中新增。

shutil.copymode(src, dst, *, follow_symlinks=True)

將許可權位從 src 複製到 dst。檔案內容、所有者和組不受影響。src 和 dst 是路徑類物件或以字串形式給出的路徑名。如果 follow_symlinks 為 false，並且 src 和 dst 都是符號連結，則 copymode() 將嘗試修改 dst 本身的模式（而不是它指向的檔案）。並非每個平臺都提供此功能；有關詳細資訊，請參閱 copystat()。如果 copymode() 無法在本地平臺上修改符號連結，並且要求這樣做，它將不執行任何操作並返回。

引發帶有引數 src、dst 的 審計事件 shutil.copymode。

在 3.3 版本中更改: 添加了 follow_symlinks 引數。

shutil.copystat(src, dst, *, follow_symlinks=True)

將許可權位、上次訪問時間、上次修改時間和標誌從 src 複製到 dst。在 Linux 上，如果可能，copystat() 還會複製“擴充套件屬性”。檔案內容、所有者和組不受影響。src 和 dst 是路徑類物件或以字串形式給出的路徑名。

如果 follow_symlinks 為 false，並且 src 和 dst 都指向符號連結，則 copystat() 將對符號連結本身進行操作，而不是符號連結引用的檔案，從 src 符號連結讀取資訊，並將資訊寫入 dst 符號連結。

注意

並非所有平臺都提供檢查和修改符號連結的功能。Python 本身可以告訴您本地有哪些功能可用。

• 如果 os.chmod in os.supports_follow_symlinks 為 True，則 copystat() 可以修改符號連結的許可權位。

• 如果 os.utime in os.supports_follow_symlinks 為 True，則 copystat() 可以修改符號連結的上次訪問時間和修改時間。

• 如果 os.chflags in os.supports_follow_symlinks 為 True，copystat() 可以修改符號連結的標誌。（os.chflags 並非在所有平臺上都可用。）

在部分或全部功能不可用的平臺上，當要求修改符號連結時，copystat() 將會複製它可以複製的所有內容。copystat() 永遠不會返回失敗。

請參閱 os.supports_follow_symlinks 獲取更多資訊。

引發一個 審計事件 shutil.copystat，引數為 src, dst。

3.3 版本更改: 添加了 follow_symlinks 引數，並支援 Linux 擴充套件屬性。

shutil.copy(src, dst, *, follow_symlinks=True)

將檔案 src 複製到檔案或目錄 dst。src 和 dst 應該是 路徑類物件 或字串。 如果 dst 指定一個目錄，檔案將會被複制到 dst 中，並使用 src 的基本檔名。 如果 dst 指定一個已經存在的檔案，它將被替換。 返回新建立檔案的路徑。

如果 follow_symlinks 為 false，且 src 是一個符號連結，那麼 dst 將被建立為一個符號連結。 如果 follow_symlinks 為 true 且 src 是一個符號連結，那麼 dst 將會是 src 指向的檔案的副本。

copy() 複製檔案資料和檔案的許可權模式（請參閱 os.chmod()）。其他元資料，如檔案的建立和修改時間，不會被保留。要保留原始檔案的所有元資料，請改用 copy2()。

引發帶有引數 src、dst 的 審計事件 shutil.copyfile。

引發帶有引數 src、dst 的 審計事件 shutil.copymode。

3.3 版本更改: 添加了 follow_symlinks 引數。現在返回新建立的檔案的路徑。

在 3.8 版本中更改: 內部可以使用特定於平臺的快速複製系統呼叫，以便更有效地複製檔案。請參閱 平臺相關的快速複製操作 部分。

shutil.copy2(src, dst, *, follow_symlinks=True)

與 copy() 相同，除了 copy2() 還會嘗試保留檔案元資料。

當 follow_symlinks 為 false，且 src 是一個符號連結時，copy2() 會嘗試將所有元資料從 src 符號連結複製到新建立的 dst 符號連結。 然而，此功能並非在所有平臺上都可用。 在部分或全部功能不可用的平臺上，copy2() 將會保留它可以保留的所有元資料； copy2() 永遠不會因為無法保留檔案元資料而引發異常。

copy2() 使用 copystat() 來複制檔案元資料。 請參閱 copystat() 獲取有關修改符號連結元資料的平臺支援的更多資訊。

引發帶有引數 src、dst 的 審計事件 shutil.copyfile。

引發一個 審計事件 shutil.copystat，引數為 src, dst。

3.3 版本更改: 添加了 follow_symlinks 引數，嘗試複製擴充套件檔案系統屬性（目前僅限 Linux）。現在返回新建立的檔案的路徑。

在 3.8 版本中更改: 內部可以使用特定於平臺的快速複製系統呼叫，以便更有效地複製檔案。請參閱 平臺相關的快速複製操作 部分。

shutil.ignore_patterns(*patterns)

這個工廠函式建立一個函式，該函式可以用作 copytree() 的 ignore 引數的可呼叫物件，忽略與提供的 glob 風格 patterns 之一匹配的檔案和目錄。請參閱下面的示例。

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

將根目錄為 src 的整個目錄樹遞迴地複製到名為 dst 的目錄，並返回目標目錄。預設情況下，也將建立包含 dst 所需的所有中間目錄。

目錄的許可權和時間使用 copystat() 複製，單個檔案使用 copy2() 複製。

如果 symlinks 為 true，則源樹中的符號連結在新樹中表示為符號連結，並且原始連結的元資料將在平臺允許的範圍內進行復制；如果為 false 或省略，則將連結檔案的內容和元資料複製到新樹中。

當 symlinks 為 false 時，如果符號連結指向的檔案不存在，則會在複製過程結束時在 Error 異常中引發的錯誤列表中新增一個異常。如果您想忽略此異常，可以將可選的 ignore_dangling_symlinks 標誌設定為 true。請注意，此選項在不支援 os.symlink() 的平臺上無效。

如果給定 ignore，則它必須是可呼叫物件，它將接收 copytree() 正在訪問的目錄及其內容的列表作為其引數，如 os.listdir() 返回的那樣。由於 copytree() 是遞迴呼叫的，因此對於複製的每個目錄，ignore 可呼叫物件將呼叫一次。該可呼叫物件必須返回相對於當前目錄的目錄和檔名序列（即其第二個引數中的專案子集）；然後在複製過程中將忽略這些名稱。ignore_patterns() 可用於建立基於 glob 風格模式忽略名稱的此類可呼叫物件。

如果發生異常，則會引發一個 Error，其中包含一個原因列表。

如果給定 copy_function，則它必須是一個可呼叫物件，該物件將用於複製每個檔案。它將使用源路徑和目標路徑作為引數呼叫。預設情況下，使用 copy2()，但可以使用任何支援相同簽名的函式（如 copy()）。

如果 dirs_exist_ok 為 false（預設值）並且 dst 已經存在，則會引發 FileExistsError。如果 dirs_exist_ok 為 true，則複製操作將在遇到現有目錄時繼續，並且 dst 樹中的檔案將被 src 樹中的相應檔案覆蓋。

引發一個 審計事件 shutil.copytree，引數為 src，dst。

3.2 版本更改: 添加了 copy_function 引數，以便能夠提供自定義的複製函式。添加了 ignore_dangling_symlinks 引數，以便在 symlinks 為 false 時忽略懸掛的符號連結錯誤。

3.3 版本更改: 當 symlinks 為 false 時，複製元資料。現在返回 dst。

在 3.8 版本中更改: 內部可以使用特定於平臺的快速複製系統呼叫，以便更有效地複製檔案。請參閱 平臺相關的快速複製操作 部分。

3.8 版本更改: 添加了 dirs_exist_ok 引數。

shutil.rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)

刪除整個目錄樹；path 必須指向一個目錄（但不能是指向目錄的符號連結）。如果 ignore_errors 為 True，則會忽略因刪除失敗而產生的錯誤；如果為 False 或省略，則此類錯誤將透過呼叫由 onexc 或 onerror 指定的處理程式進行處理，或者如果兩者都省略，則會將異常傳播給呼叫方。

此函式可以支援相對於目錄描述符的路徑。

注意

在支援必要的檔案描述符 (fd) 功能的平臺上，預設使用 rmtree() 的防符號連結攻擊版本。在其他平臺上，rmtree() 的實現容易受到符號連結攻擊：在適當的時機和情況下，攻擊者可以操縱檔案系統上的符號連結來刪除他們原本無法訪問的檔案。應用程式可以使用 rmtree.avoids_symlink_attacks 函式屬性來確定適用哪種情況。

如果提供了 onexc，它必須是一個可呼叫物件，接受三個引數：function、path 和 excinfo。

第一個引數 function 是引發異常的函式；它取決於平臺和實現。第二個引數 path 將是傳遞給 function 的路徑名稱。第三個引數 excinfo 是引發的異常。由 onexc 引發的異常將不會被捕獲。

已棄用的 onerror 類似於 onexc，不同之處在於它接收的第三個引數是從 sys.exc_info() 返回的元組。

引發一個帶有引數 path、dir_fd 的審計事件 shutil.rmtree。

在 3.3 版本中更改: 添加了一個防符號連結攻擊的版本，如果平臺支援基於檔案描述符的功能，則會自動使用。

在 3.8 版本中更改: 在 Windows 上，將不再刪除目錄連線的內容，然後再刪除該連線。

在 3.11 版本中更改: 添加了 dir_fd 引數。

在 3.12 版本中更改: 添加了 onexc 引數，棄用了 onerror。

在 3.13 版本中更改: rmtree() 現在會忽略除了頂層路徑之外的所有路徑的 FileNotFoundError 異常。除了 OSError 和 OSError 子類的異常外，現在始終將其他異常傳播給呼叫方。

rmtree.avoids_symlink_attacks

指示當前平臺和實現是否提供了 rmtree() 的防符號連結攻擊版本。目前，這僅適用於支援基於檔案描述符的目錄訪問功能的平臺。

3.3 版本中新增。

shutil.move(src, dst, copy_function=copy2)

遞迴地將檔案或目錄 (src) 移動到另一個位置並返回目標。

如果 dst 是一個現有目錄或指向目錄的符號連結，則 src 將被移動到該目錄內部。該目錄中的目標路徑必須不存在。

如果 dst 已經存在但不是目錄，則可能會根據 os.rename() 的語義覆蓋它。

如果目標位於當前檔案系統上，則使用 os.rename()。否則，使用 copy_function 將 src 複製到目標，然後刪除 src。對於符號連結，將建立一個新的符號連結指向 src 的目標作為目標，並且將刪除 src。

如果給定了 copy_function，它必須是一個可呼叫物件，接受兩個引數，src 和目標，並且如果不能使用 os.rename()，則將使用它將 src 複製到目標。如果源是一個目錄，則會呼叫 copytree()，並傳遞給它 copy_function。預設的 copy_function 是 copy2()。將 copy() 用作 copy_function 可以在無法複製元資料的情況下允許移動成功，但代價是不復制任何元資料。

引發一個帶有引數 src、dst 的審計事件 shutil.move。

在 3.3 版本中更改: 為外部檔案系統添加了顯式的符號連結處理，從而使其適應 GNU 的 mv 的行為。現在返回 dst。

在 3.5 版本中更改: 添加了 copy_function 關鍵字引數。

在 3.8 版本中更改: 內部可以使用特定於平臺的快速複製系統呼叫，以便更有效地複製檔案。請參閱 平臺相關的快速複製操作 部分。

在 3.9 版本中更改: 接受 src 和 dst 的 路徑類物件。

shutil.disk_usage(path)

以具名元組的形式返回有關給定路徑的磁碟使用情況統計資訊，該具名元組具有屬性 total、used 和 free，它們分別是總空間、已用空間和可用空間的大小（以位元組為單位）。path 可以是檔案或目錄。

注意

在 Unix 檔案系統上，path 必須指向 **已掛載** 檔案系統分割槽中的路徑。在這些平臺上，CPython 不會嘗試從非掛載的檔案系統中檢索磁碟使用資訊。

3.3 版本中新增。

在 3.8 版本中更改: 在 Windows 上，path 現在可以是檔案或目錄。

可用性: Unix，Windows。

shutil.chown(path, user=None, group=None, *, dir_fd=None, follow_symlinks=True)

更改給定 path 的所有者 user 和/或 group。

user 可以是系統使用者名稱或 uid；group 也是如此。至少需要一個引數。

另請參閱底層函式 os.chown()。

引發一個帶有引數 path、user、group 的審計事件 shutil.chown。

可用性: Unix。

3.3 版本中新增。

3.13 版本更改: 添加了 dir_fd 和 follow_symlinks 引數。

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

返回如果呼叫給定的 cmd 將要執行的可執行檔案的路徑。如果不會呼叫任何 cmd，則返回 None。

mode 是一個傳遞給 os.access() 的許可權掩碼，預設情況下確定檔案是否存在以及是否可執行。

path 是一個 “PATH 字串”，指定要查詢的目錄，以 os.pathsep 分隔。當沒有指定 path 時，PATH 環境變數將從 os.environ 讀取，如果未設定，則回退到 os.defpath。

在 Windows 上，如果 mode 不包括 os.X_OK，則當前目錄會新增到 path 的前面。當 mode 包括 os.X_OK 時，將查詢 Windows API NeedCurrentDirectoryForExePathW 以確定是否應將當前目錄新增到 path 的前面。要避免為可執行檔案查詢當前工作目錄：設定環境變數 NoDefaultCurrentDirectoryInExePath。

同樣在 Windows 上，PATHEXT 環境變數用於解析可能尚未包含副檔名的命令。例如，如果您呼叫 shutil.which("python")，which() 將搜尋 PATHEXT 以知道它應該在 path 目錄中查詢 python.exe。例如，在 Windows 上

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

當 cmd 是包含目錄元件的路徑時，也會應用此規則。

>> shutil.which("C:\\Python33\\python")
'C:\\Python33\\python.EXE'

3.3 版本中新增。

3.8 版本更改: 現在接受 bytes 型別。如果 cmd 型別是 bytes，則結果型別也是 bytes。

3.12 版本更改: 在 Windows 上，如果 mode 包括 os.X_OK 並且 WinAPI NeedCurrentDirectoryForExePathW(cmd) 為 false，則不再將當前目錄新增到搜尋路徑的前面，否則即使當前目錄已在搜尋路徑中也會新增到前面；即使 cmd 包括目錄元件或以 PATHEXT 中的副檔名結尾，現在也使用 PATHEXT；並且現在可以找到沒有副檔名的檔名。

exception shutil.Error

此異常收集在多檔案操作期間引發的異常。對於 copytree()，異常引數是 3 元組 (srcname, dstname, exception) 的列表。

平臺相關的有效複製操作

從 Python 3.8 開始，所有涉及檔案複製的函式（copyfile()、copy()、copy2()、copytree() 和 move()）可能會使用平臺特定的“快速複製”系統呼叫，以便更有效地複製檔案（請參閱 bpo-33671）。“快速複製”意味著複製操作發生在核心中，避免像 “outfd.write(infd.read())” 那樣在 Python 中使用使用者空間緩衝區。

在 macOS 上，fcopyfile 用於複製檔案內容（而不是元資料）。

在 Linux 上，使用 os.sendfile()。

在 Windows 上，shutil.copyfile() 使用更大的預設緩衝區大小（1 MiB 而不是 64 KiB）和基於 memoryview() 的 shutil.copyfileobj() 變體。

如果快速複製操作失敗並且未在目標檔案中寫入任何資料，則 shutil 將在內部靜默回退到使用效率較低的 copyfileobj() 函式。

3.8 版本更改。

copytree 示例

一個使用 ignore_patterns() 助手的示例

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

這將複製除 .pyc 檔案和名稱以 tmp 開頭的檔案或目錄之外的所有內容。

另一個使用 ignore 引數新增日誌呼叫的示例

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # nothing will be ignored

copytree(source, destination, ignore=_logpath)

rmtree 示例

此示例顯示如何在 Windows 上刪除目錄樹，其中某些檔案設定了只讀位。它使用 onexc 回撥來清除只讀位並重新嘗試刪除。任何後續失敗都將傳播。

import os, stat
import shutil

def remove_readonly(func, path, _):
    "Clear the readonly bit and reattempt the removal"
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onexc=remove_readonly)

存檔操作

3.2 版本新增。

3.5 版本更改: 添加了對 xztar 格式的支援。

還提供了用於建立和讀取壓縮和存檔檔案的高階實用程式。它們依賴於 zipfile 和 tarfile 模組。

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

建立一個存檔檔案（例如 zip 或 tar）並返回其名稱。

base_name 是要建立的檔名，包括路徑，減去任何特定於格式的副檔名。

format 是存檔格式： “zip” (如果 zlib 模組可用)、“tar”、“gztar”（如果 zlib 模組可用）、“bztar”（如果 bz2 模組可用）或 “xztar”（如果 lzma 模組可用）。

root_dir 是將作為存檔根目錄的目錄，存檔中的所有路徑都將相對於它；例如，我們通常在建立存檔之前 chdir 到 root_dir 中。

base_dir 是我們開始存檔的目錄；即 base_dir 將是存檔中所有檔案和目錄的公共字首。必須相對於 root_dir 給出 base_dir。請參閱 使用 base_dir 的存檔示例，瞭解如何一起使用 base_dir 和 root_dir。

root_dir 和 base_dir 均預設為當前目錄。

如果 dry_run 為 true，則不會建立任何存檔，但會將要執行的操作記錄到 logger 中。

建立 tar 存檔時使用 owner 和 group。預設情況下，使用當前所有者和組。

logger 必須是與 PEP 282 相容的物件，通常是 logging.Logger 的例項。

verbose 引數未使用且已棄用。

引發一個 審計事件 shutil.make_archive，其引數為 base_name、format、root_dir、base_dir。

注意

當使用 register_archive_format() 註冊的自定義歸檔器不支援 root_dir 引數時，此函式不是執行緒安全的。在這種情況下，它會臨時將程序的當前工作目錄更改為 root_dir 以執行歸檔。

在 3.8 版本中更改: 對於使用 format="tar" 建立的歸檔檔案，現在使用現代 pax (POSIX.1-2001) 格式，而不是傳統的 GNU 格式。

在 3.10.6 版本中更改: 此函式在建立標準 .zip 和 tar 歸檔檔案時現在是執行緒安全的。

shutil.get_archive_formats()

返回支援的歸檔格式列表。 返回的序列中的每個元素都是一個元組 (name, description)。

預設情況下，shutil 提供以下格式：

• zip：ZIP 檔案（如果 zlib 模組可用）。

• tar：未壓縮的 tar 檔案。 新的歸檔檔案使用 POSIX.1-2001 pax 格式。

• gztar：gzip 壓縮的 tar 檔案（如果 zlib 模組可用）。

• bztar：bzip2 壓縮的 tar 檔案（如果 bz2 模組可用）。

• xztar：xz 壓縮的 tar 檔案（如果 lzma 模組可用）。

您可以使用 register_archive_format() 註冊新格式或為任何現有格式提供自己的歸檔器。

shutil.register_archive_format(name, function[, extra_args[, description]])

為格式 name 註冊一個歸檔器。

function 是將用於解包歸檔檔案的可呼叫物件。 可呼叫物件將接收要建立的檔案的 base_name，後跟開始歸檔的 base_dir （預設為 os.curdir）。 其他引數將作為關鍵字引數傳遞：owner、group、dry_run 和 logger（如在 make_archive() 中傳遞的）。

如果 function 具有設定為 True 的自定義屬性 function.supports_root_dir，則 root_dir 引數將作為關鍵字引數傳遞。 否則，在呼叫 function 之前，程序的當前工作目錄將臨時更改為 root_dir。 在這種情況下，make_archive() 不是執行緒安全的。

如果給定，extra_args 是 (name, value) 對的序列，當使用歸檔器可呼叫物件時，將用作額外的關鍵字引數。

description 由 get_archive_formats() 使用，該函式返回歸檔器的列表。 預設為空字串。

在 3.12 版本中更改: 添加了對支援 root_dir 引數的函式的支援。

shutil.unregister_archive_format(name)

從支援的格式列表中刪除歸檔格式 name。

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])

解包一個歸檔檔案。 filename 是歸檔檔案的完整路徑。

extract_dir 是解包歸檔檔案的目標目錄的名稱。 如果未提供，則使用當前工作目錄。

format 是歸檔格式：“zip”、“tar”、“gztar”、“bztar” 或 “xztar” 之一。 或使用 register_unpack_format() 註冊的任何其他格式。 如果未提供，unpack_archive() 將使用歸檔檔名副檔名，並檢視是否為該副檔名註冊瞭解包器。 如果未找到，則會引發 ValueError。

僅限關鍵字的 filter 引數將傳遞給底層解包函式。 對於 zip 檔案，不接受 filter。 對於 tar 檔案，建議將其設定為 'data'，除非使用特定於 tar 和類 UNIX 檔案系統的功能。(有關詳細資訊，請參閱 提取過濾器。) 'data' 過濾器將在 Python 3.14 中成為 tar 檔案的預設值。

引發一個 審計事件 shutil.unpack_archive，其引數為 filename、extract_dir、format。

警告

切勿在未事先檢查的情況下從不受信任的來源提取歸檔檔案。 檔案可能會在 extract_dir 引數中指定的路徑之外建立，例如，具有以 “/” 開頭的絕對檔名或具有兩個點 “..” 的成員。

在 3.7 版本中更改: 接受 filename 和 extract_dir 的 路徑類物件。

在 3.12 版本中更改: 添加了 filter 引數。

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

註冊一個解包格式。 name 是格式的名稱，extensions 是與格式對應的副檔名列表，例如 Zip 檔案的 .zip。

function 是將用於解包歸檔檔案的可呼叫物件。 可呼叫物件將接收

• 歸檔檔案的路徑，作為位置引數；

• 必須提取歸檔檔案的目錄，作為位置引數；

• 如果將其提供給 unpack_archive()，則可能有一個 filter 關鍵字引數；

• 額外的關鍵字引數，由 extra_args 指定，為 (名稱, 值) 元組的序列。

可以提供 description 來描述格式，並且將由 get_unpack_formats() 函式返回。

shutil.unregister_unpack_format(name)

取消註冊一個解包格式。name 是格式的名稱。

shutil.get_unpack_formats()

返回所有已註冊的解包格式的列表。返回的序列的每個元素都是一個元組 (name, extensions, description)。

預設情況下，shutil 提供以下格式：

• zip：ZIP 檔案（僅當相應的模組可用時，解壓壓縮檔案才有效）。

• tar：未壓縮的 tar 檔案。

• gztar：gzip 壓縮的 tar 檔案（如果 zlib 模組可用）。

• bztar：bzip2 壓縮的 tar 檔案（如果 bz2 模組可用）。

• xztar：xz 壓縮的 tar 檔案（如果 lzma 模組可用）。

您可以使用 register_unpack_format() 註冊新格式或為您已有的任何格式提供自己的解包器。

歸檔示例

在此示例中，我們建立一個 gzip 壓縮的 tar 檔案，其中包含使用者 .ssh 目錄中的所有檔案

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'

生成的歸檔檔案包含

$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts

使用 base_dir 的歸檔示例

在此示例中，與上面的示例類似，我們展示如何使用 make_archive()，但這次使用了 base_dir。我們現在有以下目錄結構

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

在最終的歸檔檔案中，應該包含 please_add.txt，但不應包含 do_not_add.txt。因此我們使用以下程式碼

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/my_archive.tar'

列出生成的歸檔檔案中的檔案，得到以下結果

$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt

查詢輸出終端的大小

shutil.get_terminal_size(fallback=(columns, lines))

獲取終端視窗的大小。

對於兩個維度中的每一個，都會檢查環境變數 COLUMNS 和 LINES。如果變數已定義且值為正整數，則使用該值。

當未定義 COLUMNS 或 LINES 時（這是常見情況），透過呼叫 os.get_terminal_size() 查詢連線到 sys.__stdout__ 的終端。

如果無法成功查詢終端大小，可能是因為系統不支援查詢，或者因為我們沒有連線到終端，則使用 fallback 引數中給出的值。 fallback 預設為 (80, 24)，這是許多終端模擬器使用的預設大小。

返回的值是 os.terminal_size 型別的命名元組。

另請參閱：Single UNIX Specification，版本 2，其他環境變數。

3.3 版本中新增。

在 3.11 版本中更改: 如果 os.get_terminal_size() 返回零值，也會使用 fallback 值。