本人榮幸地宣布，我的首個 Python 項目 tzst 已正式登陸 PyPI (Python Package Index)。tzst 是一個致力于簡化 .tzst 和 .tar.zst 歸檔文件創(chuàng)建與管理的 Python 庫，其核心優(yōu)勢在于集成了性能卓越的 Zstandard (zstd) 壓縮算法。

在軟件開發(fā)實踐中，Zstandard 以其出色的壓縮比和處理速度受到廣泛認可。然而，在 Python 環(huán)境中，直接且便捷地操作經(jīng)由 tar 歸檔后再使用 Zstandard 壓縮的文件（即 .tar.zst，本項目亦稱 .tzst）尚存改進空間。tzst 的開發(fā)初衷便是為了填補這一空白，提供一個功能全面、接口友好的解決方案。

tzst 的主要特性

tzst 具備一系列精心設計的特性，旨在提升用戶體驗和操作效率：

• 卓越的壓縮性能：采用 Zstandard 算法，實現(xiàn)高壓縮比與高速壓縮/解壓。
• 兼容 tar 格式：生成符合 tar 規(guī)范的標準歸檔文件，并應用 Zstandard 進行壓縮。
• 命令行接口 (CLI)：提供一套設計直觀的命令行工具，便于進行快速的歸檔管理。
• Python 應用程序接口 (API)：為程序化集成需求提供符合 Pythonic 風格的、簡潔易用的 API。
• 跨平臺支持：確保在 Windows、macOS 及 Linux 等主流操作系統(tǒng)上均可穩(wěn)定運行。
• 支持多種文件擴展名：無縫處理 .tzst 與 .tar.zst 兩種標準文件擴展名。
• 靈活的解壓選項：支持按完整路徑結構解壓，或?qū)w檔內(nèi)所有文件提取至單一扁平化目錄。

安裝指南

獲取 tzst 的過程十分便捷。通過 PyPI，您可以使用 pip 命令輕松安裝：

pip install tzst

若需從源代碼構建或參與項目開發(fā)，可按以下步驟操作：

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e . # 標準源碼安裝
# 或針對開發(fā)環(huán)境，安裝包含額外開發(fā)工具的版本：
pip install -e .[dev]

快速入門

tzst 提供了命令行工具和 Python API 兩種使用方式，均易于掌握。

命令行操作示例

通過 tzst 命令，您可以高效執(zhí)行歸檔任務：

• 創(chuàng)建歸檔文件:

  tzst a archive.tzst file1.txt directory/
  

• 解壓歸檔文件:

  tzst x archive.tzst
  

• 列出歸檔內(nèi)容:

  tzst l archive.tzst
  

• 測試歸檔文件完整性:

  tzst t archive.tzst
  

注：項目的 README.md 文件提及了使用 uvx tzst 的方式，該方法可能在包解析和執(zhí)行速度上具有優(yōu)勢，且無需顯式安裝 tzst。

Python API 調(diào)用示例

在 Python 代碼中集成 tzst 同樣直接：

from tzst import create_archive, extract_archive, list_archive, test_archive

# 創(chuàng)建歸檔文件
create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"])

# 解壓歸檔文件
extract_archive("archive.tzst", "output_directory/")

# 列出歸檔文件內(nèi)容
contents = list_archive("archive.tzst", verbose=True)
for item in contents:
    print(f"{item['name']}: {item['size']} bytes")

# 測試歸檔文件完整性
if test_archive("archive.tzst"):
    print("歸檔文件經(jīng)驗證有效。")
else:
    print("歸檔文件可能存在損壞。")

功能詳解

命令行接口 (CLI)

tzst 的 CLI 工具提供了一組核心命令，包括：

• a (別名 add, create)：用于創(chuàng)建新的歸檔文件或向現(xiàn)有歸檔文件中添加文件。用戶可指定壓縮級別（范圍 1-22，默認值為 3）。
• x (別名 extract)：按照歸檔文件內(nèi)的完整路徑結構提取文件。
• e (別名 extract-flat)：提取文件，但不創(chuàng)建歸檔時的目錄結構（實現(xiàn)扁平化輸出）。
• l (別名 list)：列出歸檔文件中的內(nèi)容。通過 -v 選項可獲取更詳細的列表信息。
• t (別名 test)：對歸檔文件的完整性進行測試。

Python API

tzst 的 Python API 以 TzstArchive 類為核心，提供了面向?qū)ο蟮臍w檔操作方式。 此外，庫中還包含一組便捷函數(shù)（例如 create_archive, extract_archive, list_archive, test_archive），旨在簡化常見的歸檔任務。

通過 TzstArchive 類進行操作的示例：

from tzst import TzstArchive

# 創(chuàng)建新的歸檔文件，指定壓縮級別
with TzstArchive("archive.tzst", "w", compression_level=5) as archive: #
    archive.add("file.txt") #
    archive.add("data_directory/", recursive=True) #

# 讀取現(xiàn)有歸檔文件
with TzstArchive("archive.tzst", "r") as archive: #
    contents = archive.list(verbose=True) #
    for item in contents:
        print(item['name'])
    archive.extract(path="extraction_output/") #

文件擴展名與壓縮級別管理

• 文件擴展名：tzst 能夠自動識別和處理 .tzst 及 .tar.zst 兩種擴展名。在創(chuàng)建歸檔文件時，若未指定這兩種標準擴展名，系統(tǒng)將默認添加 .tzst。
• 壓縮級別：Zstandard 算法支持從 1 至 22 的壓縮級別。級別數(shù)值越高，壓縮效果越好，但相應地會增加處理時間。tzst 默認采用級別 3，該級別在壓縮效率與處理速度之間實現(xiàn)了較好的平衡。

tzst 的比較優(yōu)勢

相較于其他常見的壓縮歸檔工具：

• 與 tar + gzip 對比：Zstandard 通常能提供更高的壓縮比，并且在解壓速度上更具優(yōu)勢。
• 與 tar + xz 對比：在達到相近壓縮比的情況下，Zstandard 的壓縮速度顯著優(yōu)于 xz。
• 與 zip 對比：tzst 通常能夠?qū)崿F(xiàn)更佳的壓縮效果，并能更完善地保留 Unix 文件系統(tǒng)的權限及元數(shù)據(jù)信息。

異常處理機制

tzst 定義了一系列特定的異常類，如 TzstArchiveError, TzstCompressionError, TzstDecompressionError, 和 TzstFileNotFoundError。 這種設計有助于開發(fā)者在應用程序中實現(xiàn)更為精確和健壯的錯誤捕獲與處理邏輯。

開發(fā)與社區(qū)貢獻

若您對 tzst 項目的后續(xù)開發(fā)抱有興趣，或希望貢獻代碼，誠邀您訪問項目的 GitHub 倉庫。 README.md 文件中包含了詳細的開發(fā)環(huán)境配置說明、測試執(zhí)行步驟以及代碼質(zhì)量保障措施等信息。

tzst 當前版本為 0.2.0。

結語

tzst 的發(fā)布代表了本人在開源領域貢獻的一項初步嘗試。衷心希望此工具能為廣大的 Python 開發(fā)者在處理 .tar.zst 格式文件時提供實質(zhì)性的便利。歡迎各位試用 tzst，并期待任何形式的建議、反饋。若在使用過程中遇到任何問題，請不吝通過 GitHub Issues 提出。

• PyPI 項目地址: https://pypi.org/project/tzst/
• GitHub 倉庫地址: https://github.com/xixu-me/tzst

感謝您的關注。