shutil --- 高階文件操作?

目錄和文件操作?

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

將文件類對(duì)象 fsrc 的內(nèi)容拷貝到文件類對(duì)象 fdst。 整數(shù)值 length 如果給出則為緩沖區(qū)大小。 特別地， length 為負(fù)值表示拷貝數(shù)據(jù)時(shí)不對(duì)源數(shù)據(jù)進(jìn)行分塊循環(huán)處理；默認(rèn)情況下會(huì)分塊讀取數(shù)據(jù)以避免不受控制的內(nèi)存消耗。 請(qǐng)注意如果 fsrc 對(duì)象的當(dāng)前文件位置不為 0，則只有從當(dāng)前文件位置到文件末尾的內(nèi)容會(huì)被拷貝。

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

將名為 src 的文件的內(nèi)容（不包括元數(shù)據(jù)）拷貝到名為 dst 的文件并以盡可能高效的方式返回 dst。 src 和 dst 均為路徑類對(duì)象或以字符串形式給出的路徑名。

dst 必須是完整的目標(biāo)文件名；對(duì)于接受目標(biāo)目錄路徑的拷貝請(qǐng)參見 copy()。 如果 src 和 dst 指定了同一個(gè)文件，則將引發(fā) SameFileError。

目標(biāo)位置必須是可寫的；否則將引發(fā) OSError 異常。 如果 dst 已經(jīng)存在，它將被替換。 特殊文件如字符或塊設(shè)備以及管道無法用此函數(shù)來拷貝。

如果 follow_symlinks 為假值且 src 為符號(hào)鏈接，則將創(chuàng)建一個(gè)新的符號(hào)鏈接而不是拷貝 src 所指向的文件。

引發(fā)一個(gè) 審計(jì)事件 shutil.copyfile 附帶參數(shù) src, dst。

在 3.3 版更改: 曾經(jīng)是引發(fā) IOError 而不是 OSError。 增加了 follow_symlinks 參數(shù)。 現(xiàn)在是返回 dst。

在 3.4 版更改: 引發(fā) SameFileError 而不是 Error。 由于前者是后者的子類，此改變是向后兼容的。

在 3.8 版更改: 可能會(huì)在內(nèi)部使用平臺(tái)專屬的快速拷貝系統(tǒng)調(diào)用以更高效地拷貝文件。 參見 依賴于具體平臺(tái)的高效拷貝操作 一節(jié)。

exception shutil.SameFileError?

此異常會(huì)在 copyfile() 中的源和目標(biāo)為同一文件時(shí)被引發(fā)。

3.4 新版功能.

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

從 src 拷貝權(quán)限位到 dst。 文件的內(nèi)容、所有者和分組將不受影響。 src 和 dst 均為路徑類對(duì)象或字符串形式的路徑名。 如果 follow_symlinks 為假值，并且 src 和 dst 均為符號(hào)鏈接，copymode() 將嘗試修改 dst 本身的模式（而非它所指向的文件）。 此功能并不是在所有平臺(tái)上均可用；請(qǐng)參閱 copystat() 了解詳情。 如果 copymode() 無法修改本機(jī)平臺(tái)上的符號(hào)鏈接，而它被要求這樣做，它將不做任何操作即返回。

引發(fā)一個(gè) 審計(jì)事件 shutil.copymode 附帶參數(shù) src, dst。

在 3.3 版更改: 加入 follow_symlinks 參數(shù)。

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

從 src 拷貝權(quán)限位、最近訪問時(shí)間、最近修改時(shí)間以及旗標(biāo)到 dst。 在 Linux上，copystat() 還會(huì)在可能的情況下拷貝“擴(kuò)展屬性”。 文件的內(nèi)容、所有者和分組將不受影響。 src 和 dst 均為路徑類對(duì)象或字符串形式的路徑名。

如果 follow_symlinks 為假值，并且 src 和 dst 均指向符號(hào)鏈接，copystat() 將作用于符號(hào)鏈接本身而非該符號(hào)鏈接所指向的文件 — 從 src 符號(hào)鏈接讀取信息，并將信息寫入 dst 符號(hào)鏈接。

備注

并非所有平臺(tái)者提供檢查和修改符號(hào)鏈接的功能。 Python 本身可以告訴你哪些功能是在本機(jī)上可用的。

• 如果 os.chmod in os.supports_follow_symlinks 為 True，則 copystat() 可以修改符號(hào)鏈接的權(quán)限位。

• 如果 os.utime in os.supports_follow_symlinks 為 True，則 copystat() 可以修改符號(hào)鏈接的最近訪問和修改時(shí)間。

• 如果 os.chflags in os.supports_follow_symlinks 為 True，則 copystat() 可以修改符號(hào)鏈接的旗標(biāo)。 (os.chflags 不是在所有平臺(tái)上均可用。)

在此功能部分或全部不可用的平臺(tái)上，當(dāng)被要求修改一個(gè)符號(hào)鏈接時(shí)，copystat() 將盡量拷貝所有內(nèi)容。 copystat() 一定不會(huì)返回失敗信息。

更多信息請(qǐng)參閱 os.supports_follow_symlinks。

引發(fā)一個(gè) 審計(jì)事件 shutil.copystat 附帶參數(shù) src, dst。

在 3.3 版更改: 添加了 follow_symlinks 參數(shù)并且支持 Linux 擴(kuò)展屬性。

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

Copies the file src to the file or directory dst. src and dst should be path-like objects or strings. If dst specifies a directory, the file will be copied into dst using the base filename from src. If dst specifies a file that already exists, it will be replaced. Returns the path to the newly created file.

如果 follow_symlinks 為假值且 src 為符號(hào)鏈接，則 dst 也將被創(chuàng)建為符號(hào)鏈接。 如果 follow_symlinks 為真值且 src 為符號(hào)鏈接，dst 將成為 src 所指向的文件的一個(gè)副本。

copy() 會(huì)拷貝文件數(shù)據(jù)和文件的權(quán)限模式 (參見 os.chmod())。 其他元數(shù)據(jù)，例如文件的創(chuàng)建和修改時(shí)間不會(huì)被保留。 要保留所有原有的元數(shù)據(jù)，請(qǐng)改用 copy2() 。

引發(fā)一個(gè) 審計(jì)事件 shutil.copyfile 附帶參數(shù) src, dst。

引發(fā)一個(gè) 審計(jì)事件 shutil.copymode 附帶參數(shù) src, dst。

在 3.3 版更改: 添加了 follow_symlinks 參數(shù)。 現(xiàn)在會(huì)返回新創(chuàng)建文件的路徑。

在 3.8 版更改: 可能會(huì)在內(nèi)部使用平臺(tái)專屬的快速拷貝系統(tǒng)調(diào)用以更高效地拷貝文件。 參見 依賴于具體平臺(tái)的高效拷貝操作 一節(jié)。

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

類似于 copy()，區(qū)別在于 copy2() 還會(huì)嘗試保留文件的元數(shù)據(jù)。

當(dāng) follow_symlinks 為假值且 src 為符號(hào)鏈接時(shí)，copy2() 會(huì)嘗試將來自 src 符號(hào)鏈接的所有元數(shù)據(jù)拷貝到新創(chuàng)建的 dst 符號(hào)鏈接。 但是，此功能不是在所有平臺(tái)上均可用。 在此功能部分或全部不可用的平臺(tái)上，copy2() 將盡量保留所有元數(shù)據(jù)；copy2() 一定不會(huì)由于無法保留文件元數(shù)據(jù)而引發(fā)異常。

copy2() 會(huì)使用 copystat() 來拷貝文件元數(shù)據(jù)。 請(qǐng)參閱 copystat() 了解有關(guān)修改符號(hào)鏈接元數(shù)據(jù)的平臺(tái)支持的更多信息。

引發(fā)一個(gè) 審計(jì)事件 shutil.copyfile 附帶參數(shù) src, dst。

引發(fā)一個(gè) 審計(jì)事件 shutil.copystat 附帶參數(shù) src, dst。

在 3.3 版更改: 添加了 follow_symlinks 參數(shù)，還會(huì)嘗試拷貝擴(kuò)展文件系統(tǒng)屬性（目前僅限 Linux）。 現(xiàn)在會(huì)返回新創(chuàng)建文件的路徑。

在 3.8 版更改: 可能會(huì)在內(nèi)部使用平臺(tái)專屬的快速拷貝系統(tǒng)調(diào)用以更高效地拷貝文件。 參見 依賴于具體平臺(tái)的高效拷貝操作 一節(jié)。

shutil.ignore_patterns(*patterns)?

這個(gè)工廠函數(shù)會(huì)創(chuàng)建一個(gè)函數(shù)，它可被用作 copytree() 的 ignore 可調(diào)用對(duì)象參數(shù)，以忽略那些匹配所提供的 glob 風(fēng)格的 patterns 之一的文件和目錄。 參見以下示例。

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

Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory. All intermediate directories needed to contain dst will also be created by default.

目錄的權(quán)限和時(shí)間會(huì)通過 copystat() 來拷貝，單個(gè)文件則會(huì)使用 copy2() 來拷貝。

如果 symlinks 為真值，源目錄樹中的符號(hào)鏈接會(huì)在新目錄樹中表示為符號(hào)鏈接，并且原鏈接的元數(shù)據(jù)在平臺(tái)允許的情況下也會(huì)被拷貝；如果為假值或省略，則會(huì)將被鏈接文件的內(nèi)容和元數(shù)據(jù)拷貝到新目錄樹。

當(dāng) symlinks 為假值時(shí)，如果符號(hào)鏈接所指向的文件不存在，則會(huì)在拷貝進(jìn)程的末尾將一個(gè)異常添加到 Error 異常中的錯(cuò)誤列表。 如果你希望屏蔽此異常那就將可選的 ignore_dangling_symlinks 旗標(biāo)設(shè)為真值。 請(qǐng)注意此選項(xiàng)在不支持 os.symlink() 的平臺(tái)上將不起作用。

如果給出了 ignore，它必須是一個(gè)可調(diào)用對(duì)象，該對(duì)象將接受 copytree() 所訪問的目錄以及 os.listdir() 所返回的目錄內(nèi)容列表作為其參數(shù)。 由于 copytree() 是遞歸地被調(diào)用的，ignore 可調(diào)用對(duì)象對(duì)于每個(gè)被拷貝目錄都將被調(diào)用一次。 該可調(diào)用對(duì)象必須返回一個(gè)相對(duì)于當(dāng)前目錄的目錄和文件名序列（即其第二個(gè)參數(shù)的子集）；隨后這些名稱將在拷貝進(jìn)程中被忽略。 ignore_patterns() 可被用于創(chuàng)建這種基于 glob 風(fēng)格模式來忽略特定名稱的可調(diào)用對(duì)象。

如果發(fā)生了（一個(gè)或多個(gè)）異常，將引發(fā)一個(gè)附帶原因列表的 Error。

如果給出了 copy_function，它必須是一個(gè)將被用來拷貝每個(gè)文件的可調(diào)用對(duì)象。 它在被調(diào)用時(shí)會(huì)將源路徑和目標(biāo)路徑作為參數(shù)傳入。 默認(rèn)情況下，copy2() 將被使用，但任何支持同樣簽名（與 copy() 一致）都可以使用。

If dirs_exist_ok is false (the default) and dst already exists, a FileExistsError is raised. If dirs_exist_ok is true, the copying operation will continue if it encounters existing directories, and files within the dst tree will be overwritten by corresponding files from the src tree.

引發(fā)一個(gè) 審計(jì)事件 shutil.copytree 附帶參數(shù) src, dst。

在 3.3 版更改: 當(dāng) symlinks 為假值時(shí)拷貝元數(shù)據(jù)。 現(xiàn)在會(huì)返回 dst。

在 3.2 版更改: Added the copy_function argument to be able to provide a custom copy function. Added the ignore_dangling_symlinks argument to silence dangling symlinks errors when symlinks is false.

在 3.8 版更改: 可能會(huì)在內(nèi)部使用平臺(tái)專屬的快速拷貝系統(tǒng)調(diào)用以更高效地拷貝文件。 參見 依賴于具體平臺(tái)的高效拷貝操作 一節(jié)。

3.8 新版功能: dirs_exist_ok 形參。

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

刪除一個(gè)完整的目錄樹；path 必須指向一個(gè)目錄（但不能是一個(gè)目錄的符號(hào)鏈接）。 如果 ignore_errors 為真值，刪除失敗導(dǎo)致的錯(cuò)誤將被忽略；如果為假值或是省略，此類錯(cuò)誤將通過調(diào)用由 onerror 所指定的處理程序來處理，或者如果此參數(shù)被省略則將引發(fā)一個(gè)異常。

This function can support paths relative to directory descriptors.

備注

在支持必要的基于 fd 的函數(shù)的平臺(tái)上，默認(rèn)會(huì)使用 rmtree() 的可防御符號(hào)鏈接攻擊的版本。 在其他平臺(tái)上，rmtree() 較易遭受符號(hào)鏈接攻擊：給定適當(dāng)?shù)臅r(shí)間和環(huán)境，攻擊者可以操縱文件系統(tǒng)中的符號(hào)鏈接來刪除他們?cè)谄渌闆r下無法訪問的文件。 應(yīng)用程序可以使用 rmtree.avoids_symlink_attacks 函數(shù)屬性來確定此類情況具體是哪一些。

如果提供了 onerror，它必須為接受三個(gè)形參的可調(diào)用對(duì)象: function, path 和 excinfo。

第一個(gè)形參 function 是引發(fā)異常的函數(shù)；它依賴于具體的平臺(tái)和實(shí)現(xiàn)。 第二個(gè)形參 path 將是傳遞給 function 的路徑名。 第三個(gè)形參 excinfo 將是由 sys.exc_info() 所返回的異常信息。 由 onerror 所引發(fā)的異常將不會(huì)被捕獲。

Raises an auditing event shutil.rmtree with arguments path, dir_fd.

在 3.3 版更改: 添加了一個(gè)防御符號(hào)鏈接攻擊的版本，如果平臺(tái)支持基于 fd 的函數(shù)就會(huì)被使用。

在 3.8 版更改: 在 Windows 上將不會(huì)再在移除連接之前刪除目錄連接中的內(nèi)容。

在 3.11 版更改: The dir_fd parameter.

rmtree.avoids_symlink_attacks?

指明當(dāng)前平臺(tái)和實(shí)現(xiàn)是否提供防御符號(hào)鏈接攻擊的 rmtree() 版本。 目前它僅在平臺(tái)支持基于 fd 的目錄訪問函數(shù)時(shí)才返回真值。

3.3 新版功能.

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

遞歸地將一個(gè)文件或目錄 (src) 移至另一位置 (dst) 并返回目標(biāo)位置。

如果目標(biāo)是已存在的目錄，則 src 會(huì)被移至該目錄下。 如果目標(biāo)已存在但不是目錄，它可能會(huì)被覆蓋，具體取決于 os.rename() 的語義。

如果目標(biāo)是在當(dāng)前文件系統(tǒng)中，則會(huì)使用 os.rename()。 在其他情況下，src 將被拷貝至 dst，使用的函數(shù)為 copy_function，然后目標(biāo)會(huì)被移除。 對(duì)于符號(hào)鏈接，則將在 dst 之下或以其本身為名稱創(chuàng)建一個(gè)指向 src 目標(biāo)的新符號(hào)鏈接，并且 src 將被移除。

如果給出了 copy_function，則它必須為接受兩個(gè)參數(shù) src 和 dst 的可調(diào)用對(duì)象，并將在 os.rename() 無法使用時(shí)被用來將 src 拷貝到 dst。 如果源是一個(gè)目錄，則會(huì)調(diào)用 copytree()，并向它傳入 copy_function()。 默認(rèn)的 copy_function 是 copy2()。 使用 copy() 作為 copy_function 允許在無法附帶拷貝元數(shù)據(jù)時(shí)讓移動(dòng)操作成功執(zhí)行，但其代價(jià)是不拷貝任何元數(shù)據(jù)。

引發(fā)一個(gè) 審計(jì)事件 shutil.move 附帶參數(shù) src, dst。

在 3.3 版更改: 為異類文件系統(tǒng)添加了顯式的符號(hào)鏈接處理，以便使它適應(yīng) GNU 的 mv 的行為。 現(xiàn)在會(huì)返回 dst。

在 3.5 版更改: 增加了 copy_function 關(guān)鍵字參數(shù)。

在 3.8 版更改: 可能會(huì)在內(nèi)部使用平臺(tái)專屬的快速拷貝系統(tǒng)調(diào)用以更高效地拷貝文件。 參見 依賴于具體平臺(tái)的高效拷貝操作 一節(jié)。

在 3.9 版更改: 接受一個(gè) path-like object 作為 src 和 dst。

shutil.disk_usage(path)?

返回給定路徑的磁盤使用統(tǒng)計(jì)數(shù)據(jù)，形式為一個(gè) named tuple，其中包含 total, used 和 free 屬性，分別表示總計(jì)、已使用和未使用空間的字節(jié)數(shù)。 path 可以是一個(gè)文件或是一個(gè)目錄。

3.3 新版功能.

在 3.8 版更改: 在 Windows 上，path 現(xiàn)在可以是一個(gè)文件或目錄。

可用性: Unix, Windows。

shutil.chown(path, user=None, group=None)?

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

user 可以是一個(gè)系統(tǒng)用戶名或 uid；group 同樣如此。 要求至少有一個(gè)參數(shù)。

另請(qǐng)參閱下層的函數(shù) os.chown()。

引發(fā)一個(gè) 審計(jì)事件 shutil.chown 附帶參數(shù) path, user, group。

可用性: Unix。

3.3 新版功能.

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

返回當(dāng)給定的 cmd 被調(diào)用時(shí)將要運(yùn)行的可執(zhí)行文件的路徑。 如果沒有 cmd 會(huì)被調(diào)用則返回 None。

mode 是一個(gè)傳遞給 os.access() 的權(quán)限掩碼，在默認(rèn)情況下將確定文件是否存在并且為可執(zhí)行文件。

當(dāng)未指定 path 時(shí)，將會(huì)使用 os.environ() 的結(jié)果，返回 "PATH" 的值或回退為 os.defpath。

在 Windows 上當(dāng)前目錄總是會(huì)被添加為 path 的第一項(xiàng)，無論你是否使用默認(rèn)值或提供你自己的路徑，這是命令行終端在查找可執(zhí)行文件時(shí)所采用的行為方式。 此外，當(dāng)在 path 中查找 cmd 時(shí)，還會(huì)檢查 PATHEXT 環(huán)境變量。 例如，如果你調(diào)用 shutil.which("python")，which() 將搜索 PATHEXT 來確定它要在 path 目錄中查找 python.exe。 例如，在 Windows 上:

>>>

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

3.3 新版功能.

在 3.8 版更改: 現(xiàn)在可以接受 bytes 類型。 如果 cmd 的類型為 bytes，結(jié)果的類型也將為 bytes。

exception shutil.Error?

此異常會(huì)收集在多文件操作期間所引發(fā)的異常。 對(duì)于 copytree()，此異常參數(shù)將是一個(gè)由三元組 (srcname, dstname, exception) 構(gòu)成的列表。

from shutil import copytree, ignore_patterns

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

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)

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, onerror=remove_readonly)

歸檔操作?

本模塊也提供了用于創(chuàng)建和讀取壓縮和歸檔文件的高層級(jí)工具。 它們依賴于 zipfile 和 tarfile 模塊。

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

創(chuàng)建一個(gè)歸檔文件（例如 zip 或 tar）并返回其名稱。

base_name 是要?jiǎng)?chuàng)建的文件名稱，包括路徑，去除任何特定格式的擴(kuò)展名。 format 是歸檔格式：為 "zip" (如果 zlib 模塊可用), "tar", "gztar" (如果 zlib 模塊可用), "bztar" (如果 bz2 模塊可用) 或 "xztar" (如果 lzma 模塊可用) 中的一個(gè)。

root_dir 是一個(gè)目錄，它將作為歸檔文件的根目錄，歸檔中的所有路徑都將是它的相對(duì)路徑；例如，我們通常會(huì)在創(chuàng)建歸檔之前用 chdir 命令切換到 root_dir。

base_dir 是我們要執(zhí)行歸檔的起始目錄；也就是說 base_dir 將成為歸檔中所有文件和目錄共有的路徑前綴。 base_dir 必須相對(duì)于 root_dir 給出。 請(qǐng)參閱 使用 base_dir 的歸檔程序示例 了解如何同時(shí)使用 base_dir 和 root_dir。

root_dir 和 base_dir 默認(rèn)均為當(dāng)前目錄。

如果 dry_run 為真值，則不會(huì)創(chuàng)建歸檔文件，但將要被執(zhí)行的操作會(huì)被記錄到 logger。

owner 和 group 將在創(chuàng)建 tar 歸檔文件時(shí)被使用。 默認(rèn)會(huì)使用當(dāng)前的所有者和分組。

logger 必須是一個(gè)兼容 PEP 282 的對(duì)象，通常為 logging.Logger 的實(shí)例。

verbose 參數(shù)已不再使用并進(jìn)入棄用狀態(tài)。

引發(fā)一個(gè) 審計(jì)事件 shutil.make_archive 并附帶參數(shù) base_name, format, root_dir, base_dir。

備注

這個(gè)函數(shù)不是線程安全的。

在 3.8 版更改: 現(xiàn)在對(duì)于通過 format="tar" 創(chuàng)建的歸檔文件將使用新式的 pax (POSIX.1-2001) 格式而非舊式的 GNU 格式。

shutil.get_archive_formats()?

返回支持的歸檔格式列表。 所返回序列中的每個(gè)元素為一個(gè)元組 (name, description)。

默認(rèn)情況下 shutil 提供以下格式:

• zip: ZIP 文件（如果 zlib 模塊可用）。

• tar: 未壓縮的 tar 文件。 對(duì)于新歸檔文件將使用 POSIX.1-2001 pax 格式。

• gztar: gzip 壓縮的 tar 文件（如果 zlib 模塊可用）。

• bztar: bzip2 壓縮的 tar 文件（如果 bz2 模塊可用）。

• xztar: xz 壓縮的 tar 文件（如果 lzma 模塊可用）。

你可以通過使用 register_archive_format() 注冊(cè)新的格式或?yàn)槿魏维F(xiàn)有格式提供你自己的歸檔器。

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

為 name 格式注冊(cè)一個(gè)歸檔器。

function 是將被用來解包歸檔文件的可調(diào)用對(duì)象。 該可調(diào)用對(duì)象將接收要?jiǎng)?chuàng)建文件的 base_name，再加上要?dú)w檔內(nèi)容的 base_dir (其默認(rèn)值為 os.curdir)。 更多參數(shù)會(huì)被作為關(guān)鍵字參數(shù)傳入: owner, group, dry_run 和 logger (與向 make_archive() 傳入的參數(shù)一致)。

如果給出了 extra_args，則其應(yīng)為一個(gè) (name, value) 對(duì)的序列，將在歸檔器可調(diào)用對(duì)象被使用時(shí)作為附加的關(guān)鍵字參數(shù)。

description 由 get_archive_formats() 使用，它將返回歸檔器的列表。 默認(rèn)值為一個(gè)空字符串。

shutil.unregister_archive_format(name)?

從支持的格式中移除歸檔格式 name。

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

解包一個(gè)歸檔文件。 filename 是歸檔文件的完整路徑。

extract_dir 是歸檔文件解包的目標(biāo)目錄名稱。 如果未提供，則將使用當(dāng)前工作目錄。

format 是歸檔格式：應(yīng)為 "zip", "tar", "gztar", "bztar" 或 "xztar" 之一。 或者任何通過 register_unpack_format() 注冊(cè)的其他格式。 如果未提供，unpack_archive() 將使用歸檔文件的擴(kuò)展名來檢查是否注冊(cè)了對(duì)應(yīng)于該擴(kuò)展名的解包器。 在未找到任何解包器的情況下，將引發(fā) ValueError。

引發(fā)一個(gè) 審計(jì)事件 shutil.unpack_archive 附帶參數(shù) filename, extract_dir, format。

警告

Never extract archives from untrusted sources without prior inspection. It is possible that files are created outside of the path specified in the extract_dir argument, e.g. members that have absolute filenames starting with "/" or filenames with two dots "..".

在 3.7 版更改: 接受一個(gè) path-like object 作為 filename 和 extract_dir。

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

注冊(cè)一個(gè)解包格式。 name 為格式名稱而 extensions 為對(duì)應(yīng)于該格式的擴(kuò)展名列表，例如 Zip 文件的擴(kuò)展名為 .zip。

function 是將被用來解包歸檔文件的可調(diào)用對(duì)象。 該可調(diào)用對(duì)象將接受歸檔文件的路徑，加上該歸檔文件要被解包的目標(biāo)目錄。

如果提供了 extra_args，則其應(yīng)為一個(gè) (name, value) 元組的序列，將被作為關(guān)鍵字參數(shù)傳遞給該可調(diào)用對(duì)象。

可以提供 description 來描述該格式，它將被 get_unpack_formats() 返回。

shutil.unregister_unpack_format(name)?

撤銷注冊(cè)一個(gè)解包格式。 name 為格式的名稱。

shutil.get_unpack_formats()?

返回所有已注冊(cè)的解包格式列表。 所返回序列中的每個(gè)元素為一個(gè)元組 (name, extensions, description)。

默認(rèn)情況下 shutil 提供以下格式:

• zip: ZIP 文件（只有在相應(yīng)模塊可用時(shí)才能解包壓縮文件）。

• tar: 未壓縮的 tar 文件。

• gztar: gzip 壓縮的 tar 文件（如果 zlib 模塊可用）。

• bztar: bzip2 壓縮的 tar 文件（如果 bz2 模塊可用）。

• xztar: xz 壓縮的 tar 文件（如果 lzma 模塊可用）。

你可以通過使用 register_unpack_format() 注冊(cè)新的格式或?yàn)槿魏维F(xiàn)有格式提供你自己的解包器。

>>> 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

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── 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))?

獲取終端窗口的尺寸。

對(duì)于兩個(gè)維度中的每一個(gè)，會(huì)分別檢查環(huán)境變量 COLUMNS 和 LINES。 如果定義了這些變量并且其值為正整數(shù)，則將使用這些值。

如果未定義 COLUMNS 或 LINES，這是通常的情況，則連接到 sys.__stdout__ 的終端將通過發(fā)起調(diào)用 os.get_terminal_size() 被查詢。

如果由于系統(tǒng)不支持查詢，或是由于我們未連接到某個(gè)終端而導(dǎo)致查詢終端尺寸不成功，則會(huì)使用在 fallback 形參中給出的值。 fallback 默認(rèn)為 (80, 24)，這是許多終端模擬器所使用的默認(rèn)尺寸。

返回的值是一個(gè) os.terminal_size 類型的具名元組。

另請(qǐng)參閱: The Single UNIX Specification, Version 2, Other Environment Variables.

3.3 新版功能.

在 3.11 版更改: The fallback values are also used if os.get_terminal_size() returns zeroes.