tarfile --- Đọc và ghi tập tin lưu trữ tar

Source code: Lib/tarfile.py

Mô-đun tarfile cho phép đọc và ghi các kho lưu trữ tar, bao gồm cả những kho sử dụng nén gzip, bz2 và lzma. Sử dụng mô-đun zipfile để đọc hoặc ghi các tệp .zip hoặc các hàm cấp cao hơn trong shutil.

Một số sự kiện và số liệu:

  • đọc và ghi các kho lưu trữ nén gzip, bz2, compression.zstd và lzma nếu có sẵn các mô-đun tương ứng.

    Nếu bất kỳ optional modules nào bị thiếu trong bản sao CPython của bạn, hãy tìm tài liệu từ nhà phân phối của bạn (nghĩa là bất kỳ ai đã cung cấp Python cho bạn). Nếu bạn là nhà phân phối, hãy xem Yêu cầu đối với các mô-đun tùy chọn.

  • hỗ trợ đọc/ghi cho định dạng POSIX.1-1988 (ustar).

  • hỗ trợ đọc/ghi cho định dạng tar GNU bao gồm các phần mở rộng longname và longlink, hỗ trợ chỉ đọc cho tất cả các biến thể của phần mở rộng sparse bao gồm cả việc khôi phục các tệp thưa thớt.

  • hỗ trợ đọc/ghi cho định dạng POSIX.1-2001 (pax).

  • xử lý các thư mục, tệp thông thường, liên kết cứng, liên kết tượng trưng, ​​fifos, thiết bị ký tự và thiết bị khối, đồng thời có thể thu thập và khôi phục thông tin tệp như dấu thời gian, quyền truy cập và chủ sở hữu.

Thay đổi trong phiên bản 3.3: Đã thêm hỗ trợ nén lzma.

Thay đổi trong phiên bản 3.12: Các kho lưu trữ được trích xuất bằng filter, giúp hạn chế các tính năng đáng ngạc nhiên/nguy hiểm hoặc thừa nhận rằng chúng được mong đợi và kho lưu trữ hoàn toàn đáng tin cậy.

Thay đổi trong phiên bản 3.14: Đặt bộ lọc trích xuất mặc định thành data, bộ lọc này không cho phép một số tính năng nguy hiểm như liên kết đến đường dẫn tuyệt đối hoặc đường dẫn bên ngoài đích. Trước đây, chiến lược lọc tương đương với fully_trusted.

Thay đổi trong phiên bản 3.14: Đã thêm hỗ trợ nén Zstandard bằng compression.zstd.

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Trả về đối tượng TarFile cho tên đường dẫn name. Để biết thông tin chi tiết về các đối tượng TarFile và các đối số từ khóa được phép, hãy xem Đối tượng TarFile.

mode phải là một chuỗi có dạng 'filemode[:compression]', mặc định là 'r'. Dưới đây là danh sách đầy đủ các kết hợp chế độ:

chế độ

hành động

'r' hoặc 'r:*'

Mở để đọc với tính năng nén trong suốt (được khuyến nghị).

'r:'

Mở để đọc độc quyền mà không cần nén.

'r:gz'

Mở để đọc bằng nén gzip.

'r:bz2'

Mở để đọc với nén bzip2.

'r:xz'

Mở để đọc với nén lzma.

'r:zst'

Mở để đọc với nén Zstandard.

'x' hoặc 'x:'

Tạo một tarfile độc quyền mà không cần nén. Đưa ra ngoại lệ FileExistsError nếu nó đã tồn tại.

'x:gz'

Tạo một tarfile với nén gzip. Đưa ra ngoại lệ FileExistsError nếu nó đã tồn tại.

'x:bz2'

Tạo một tarfile với nén bzip2. Đưa ra ngoại lệ FileExistsError nếu nó đã tồn tại.

'x:xz'

Tạo một tarfile với nén lzma. Đưa ra ngoại lệ FileExistsError nếu nó đã tồn tại.

'x:zst'

Tạo một tarfile với nén Zstandard. Đưa ra ngoại lệ FileExistsError nếu nó đã tồn tại.

'a' hoặc 'a:'

Mở để nối thêm mà không cần nén. Tệp được tạo nếu nó không tồn tại.

'w' hoặc 'w:'

Mở để viết không nén.

'w:gz'

Mở để viết nén gzip.

'w:bz2'

Mở để viết nén bzip2.

'w:xz'

Mở cho văn bản nén lzma.

'w:zst'

Mở cho văn bản nén Zstandard.

Lưu ý rằng 'a:gz', 'a:bz2' hoặc 'a:xz' là không thể. Nếu mode không phù hợp để mở một tệp (nén) nhất định để đọc, ReadError sẽ được nâng lên. Sử dụng mode 'r' để tránh điều này. Nếu phương pháp nén không được hỗ trợ, CompressionError sẽ được nâng lên.

Nếu fileobj được chỉ định, nó sẽ được sử dụng thay thế cho file object được mở ở chế độ nhị phân cho name. Nó được cho là ở vị trí 0.

Đối với các chế độ 'w:gz', 'x:gz', 'w|gz', 'w:bz2', 'x:bz2', 'w|bz2', tarfile.open() chấp nhận đối số từ khóa compresslevel (9 mặc định) để chỉ định mức độ nén của tệp.

Đối với các chế độ 'w:xz', 'x:xz' và 'w|xz', tarfile.open() chấp nhận đối số từ khóa preset để chỉ định mức độ nén của tệp.

Đối với các chế độ 'w:zst', 'x:zst' và 'w|zst', tarfile.open() chấp nhận đối số từ khóa level để chỉ định mức độ nén của tệp. Đối số từ khóa options cũng có thể được thông qua, cung cấp các tham số nén Zstandard nâng cao được mô tả bởi CompressionParameter. Đối số từ khóa zstd_dict có thể được chuyển để cung cấp ZstdDict, một từ điển Zstandard được sử dụng để cải thiện việc nén lượng dữ liệu nhỏ hơn.

Đối với các mục đích đặc biệt, có định dạng thứ hai cho mode: 'filemode|[compression]'. tarfile.open() sẽ trả về một đối tượng TarFile xử lý dữ liệu của nó dưới dạng luồng khối. Không có tìm kiếm ngẫu nhiên sẽ được thực hiện trên tập tin. Nếu được cung cấp, fileobj có thể là bất kỳ đối tượng nào có phương thức read() hoặc write() (tùy thuộc vào mode) hoạt động với byte. bufsize chỉ định kích thước khối và mặc định là byte 20 * 512. Sử dụng biến thể này kết hợp với ví dụ: sys.stdin.buffer, ổ cắm file object hoặc thiết bị băng. Tuy nhiên, đối tượng TarFile như vậy bị hạn chế ở chỗ nó không cho phép truy cập ngẫu nhiên, xem Ví dụ. Các chế độ hiện có thể có:

Chế độ

hành động

'r|*'

Mở một khối tar stream để đọc với tính năng nén trong suốt.

'r|'

Mở stream khối tar không nén để đọc.

'r|gz'

Mở stream được nén bằng gzip để đọc.

'r|bz2'

Mở stream nén bzip2 để đọc.

'r|xz'

Mở stream nén lzma để đọc.

'r|zst'

Mở stream nén Zstandard để đọc.

'w|'

Mở stream không nén để viết.

'w|gz'

Mở stream được nén bằng gzip để viết.

'w|bz2'

Mở stream nén bzip2 để viết.

'w|xz'

Mở stream nén lzma để viết.

'w|zst'

Mở stream nén Zstandard để viết.

Thay đổi trong phiên bản 3.5: Chế độ 'x' (tạo độc quyền) đã được thêm vào.

Thay đổi trong phiên bản 3.6: Tham số name chấp nhận path-like object.

Thay đổi trong phiên bản 3.12: Đối số từ khóa compresslevel cũng hoạt động cho các luồng.

Thay đổi trong phiên bản 3.14: Đối số từ khóa preset cũng hoạt động cho các luồng.

class tarfile.TarFile

Lớp đọc và ghi lưu trữ tar. Không sử dụng trực tiếp lớp này: thay vào đó hãy sử dụng tarfile.open(). Xem Đối tượng TarFile.

tarfile.is_tarfile(name)

Trả về True nếu name là tệp lưu trữ tar mà mô-đun tarfile có thể đọc được. name có thể là một đối tượng str, tệp hoặc giống như tệp.

Thay đổi trong phiên bản 3.9: Hỗ trợ tập tin và các đối tượng giống như tập tin.

Mô-đun tarfile xác định các ngoại lệ sau:

exception tarfile.TarError

Lớp cơ sở cho tất cả các ngoại lệ tarfile.

exception tarfile.ReadError

Được nâng lên khi một kho lưu trữ tar được mở, mô-đun tarfile không thể xử lý được hoặc bằng cách nào đó không hợp lệ.

exception tarfile.CompressionError

Được nâng lên khi phương pháp nén không được hỗ trợ hoặc khi dữ liệu không thể được giải mã chính xác.

exception tarfile.StreamError

Được nêu ra đối với những hạn chế điển hình đối với các đối tượng TarFile giống như luồng.

exception tarfile.ExtractError

Được đưa ra đối với lỗi non-fatal khi sử dụng TarFile.extract(), nhưng chỉ khi TarFile.errorlevel== 2.

exception tarfile.HeaderError

Được tăng lên bởi TarInfo.frombuf() nếu bộ đệm nhận được không hợp lệ.

exception tarfile.FilterError

Lớp cơ sở dành cho thành viên refused theo bộ lọc.

tarinfo

Thông tin về thành viên mà bộ lọc từ chối trích xuất, dưới dạng TarInfo.

exception tarfile.AbsolutePathError

Được nêu ra để từ chối trích xuất một thành viên có đường dẫn tuyệt đối.

exception tarfile.OutsideDestinationError

Được nêu ra để từ chối trích xuất một thành viên bên ngoài thư mục đích.

exception tarfile.SpecialFileError

Được nêu ra để từ chối trích xuất một tệp đặc biệt (ví dụ: một thiết bị hoặc đường ống).

exception tarfile.AbsoluteLinkError

Được nêu ra để từ chối trích xuất một liên kết tượng trưng với một đường dẫn tuyệt đối.

exception tarfile.LinkOutsideDestinationError

Được nêu ra để từ chối trích xuất một liên kết tượng trưng trỏ ra ngoài thư mục đích.

exception tarfile.LinkFallbackError

Được đưa ra để từ chối mô phỏng một liên kết (cứng hoặc tượng trưng) bằng cách trích xuất một thành viên lưu trữ khác, khi thành viên đó sẽ bị vị trí bộ lọc từ chối. Ngoại lệ được đưa ra để từ chối thành viên thay thế có sẵn là BaseException.__context__.

Added in version 3.14.

Các hằng số sau đây có sẵn ở cấp mô-đun:

tarfile.ENCODING

Mã hóa ký tự mặc định: 'utf-8' trên Windows, giá trị được trả về bởi sys.getfilesystemencoding() nếu không.

tarfile.REGTYPE
tarfile.AREGTYPE

Một tập tin thông thường type.

tarfile.LNKTYPE

Một liên kết (bên trong tarfile) type.

tarfile.SYMTYPE

Một liên kết tượng trưng type.

tarfile.CHRTYPE

Một thiết bị đặc biệt dành cho nhân vật type.

tarfile.BLKTYPE

Một khối thiết bị đặc biệt type.

tarfile.DIRTYPE

Một thư mục type.

tarfile.FIFOTYPE

Một thiết bị đặc biệt FIFO type.

tarfile.CONTTYPE

Một tập tin liền kề type.

tarfile.GNUTYPE_LONGNAME

Một tên dài GNU tar type.

Một liên kết dài GNU tar type.

tarfile.GNUTYPE_SPARSE

Một tập tin thưa thớt tar GNU type.

Mỗi hằng số sau đây xác định định dạng lưu trữ tar mà mô-đun tarfile có thể tạo. Xem phần Các định dạng tar được hỗ trợ để biết chi tiết.

tarfile.USTAR_FORMAT

định dạng POSIX.1-1988 (ustar).

tarfile.GNU_FORMAT

định dạng tar GNU.

tarfile.PAX_FORMAT

định dạng POSIX.1-2001 (khách hàng).

tarfile.DEFAULT_FORMAT

Định dạng mặc định để tạo lưu trữ. Đây hiện tại là PAX_FORMAT.

Thay đổi trong phiên bản 3.8: Định dạng mặc định cho các kho lưu trữ mới đã được thay đổi thành PAX_FORMAT từ GNU_FORMAT.

Xem thêm

Mô-đun zipfile

Tài liệu của mô-đun tiêu chuẩn zipfile.

Hoạt động lưu trữ

Tài liệu về các phương tiện lưu trữ cấp cao hơn được cung cấp bởi mô-đun shutil tiêu chuẩn.

GNU tar manual, Basic Tar Format

Tài liệu về các tệp lưu trữ tar, bao gồm phần mở rộng tar GNU.

Đối tượng TarFile

Đối tượng TarFile cung cấp giao diện cho kho lưu trữ tar. Kho lưu trữ tar là một chuỗi các khối. Thành viên lưu trữ (tệp được lưu trữ) được tạo thành từ khối tiêu đề, theo sau là khối dữ liệu. Có thể lưu trữ một tập tin trong kho lưu trữ tar nhiều lần. Mỗi thành viên lưu trữ được đại diện bởi một đối tượng TarInfo, xem Đối tượng TarInfo để biết chi tiết.

Đối tượng TarFile có thể được sử dụng làm trình quản lý bối cảnh trong câu lệnh with. Nó sẽ tự động đóng lại khi khối được hoàn thành. Xin lưu ý rằng trong trường hợp có ngoại lệ, kho lưu trữ được mở để viết sẽ không được hoàn thiện; chỉ đối tượng tệp được sử dụng nội bộ sẽ bị đóng. Xem phần Ví dụ để biết trường hợp sử dụng.

Added in version 3.2: Đã thêm hỗ trợ cho giao thức quản lý bối cảnh.

class tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1, stream=False)

Tất cả các đối số sau đây là tùy chọn và cũng có thể được truy cập dưới dạng thuộc tính phiên bản.

name là tên đường dẫn của kho lưu trữ. name có thể là path-like object. Nó có thể được bỏ qua nếu fileobj được đưa ra. Trong trường hợp này, thuộc tính name của đối tượng tệp sẽ được sử dụng nếu nó tồn tại.

mode là 'r' để đọc từ kho lưu trữ hiện có, 'a' để nối dữ liệu vào tệp hiện có, 'w' để tạo tệp mới ghi đè tệp hiện có hoặc 'x' để chỉ tạo tệp mới nếu nó chưa tồn tại.

Nếu fileobj được cung cấp, nó được sử dụng để đọc hoặc ghi dữ liệu. Nếu có thể xác định được, mode sẽ bị ghi đè bởi chế độ của fileobj. fileobj sẽ được sử dụng từ vị trí 0.

Ghi chú

fileobj không bị đóng khi TarFile bị đóng.

format kiểm soát định dạng lưu trữ để ghi. Nó phải là một trong các hằng số USTAR_FORMAT, GNU_FORMAT hoặc PAX_FORMAT được xác định ở cấp mô-đun. Khi đọc, định dạng sẽ được tự động phát hiện, ngay cả khi có các định dạng khác nhau trong một kho lưu trữ.

Đối số tarinfo có thể được sử dụng để thay thế lớp TarInfo mặc định bằng một lớp khác.

Nếu dereference là False, hãy thêm các liên kết tượng trưng và cứng vào kho lưu trữ. Nếu là True, hãy thêm nội dung của tệp đích vào kho lưu trữ. Điều này không có tác dụng đối với các hệ thống không hỗ trợ liên kết tượng trưng.

Nếu ignore_zeros là False, hãy coi khối trống là phần cuối của kho lưu trữ. Nếu là True, hãy bỏ qua các khối trống (và không hợp lệ) và cố gắng thu hút càng nhiều thành viên càng tốt. Điều này chỉ hữu ích khi đọc các tài liệu lưu trữ bị nối hoặc bị hỏng.

debug có thể được đặt từ 0 (không có thông báo gỡ lỗi) cho đến 3 (tất cả các thông báo gỡ lỗi). Các tin nhắn được ghi vào sys.stderr.

errorlevel kiểm soát cách xử lý lỗi trích xuất, xem the corresponding attribute.

Các đối số encoding và errors xác định mã hóa ký tự được sử dụng để đọc hoặc ghi kho lưu trữ và cách xử lý các lỗi chuyển đổi. Cài đặt mặc định sẽ hoạt động với hầu hết người dùng. Xem phần vấn đề về Unicode để biết thông tin chuyên sâu.

Đối số pax_headers là một từ điển tùy chọn gồm các chuỗi sẽ được thêm dưới dạng tiêu đề toàn cục pax nếu format là PAX_FORMAT.

Nếu stream được đặt thành True thì khi đọc thông tin lưu trữ về các tệp trong kho lưu trữ sẽ không được lưu vào bộ nhớ đệm, giúp tiết kiệm bộ nhớ.

Thay đổi trong phiên bản 3.2: Sử dụng 'surrogateescape' làm mặc định cho đối số errors.

Thay đổi trong phiên bản 3.5: Chế độ 'x' (tạo độc quyền) đã được thêm vào.

Thay đổi trong phiên bản 3.6: Tham số name chấp nhận path-like object.

Thay đổi trong phiên bản 3.13: Thêm tham số stream.

classmethod TarFile.open(...)

Nhà xây dựng thay thế. Hàm tarfile.open() thực chất là một lối tắt cho phương thức lớp này.

TarFile.getmember(name)

Trả về đối tượng TarInfo cho thành viên name. Nếu không tìm thấy name trong kho lưu trữ, KeyError sẽ được nâng lên.

Ghi chú

Nếu một thành viên xuất hiện nhiều lần trong kho lưu trữ, lần xuất hiện cuối cùng của nó được coi là phiên bản cập nhật nhất.

TarFile.getmembers()

Trả về các thành viên của kho lưu trữ dưới dạng danh sách các đối tượng TarInfo. Danh sách có thứ tự giống như các thành viên trong kho lưu trữ.

TarFile.getnames()

Trả về các thành viên dưới dạng danh sách tên của họ. Nó có cùng thứ tự với danh sách được trả về bởi getmembers().

TarFile.list(verbose=True, *, members=None)

In mục lục ra sys.stdout. Nếu verbose là False thì chỉ in tên của các thành viên. Nếu là True, đầu ra tương tự như ls -l sẽ được tạo ra. Nếu members tùy chọn được cung cấp, nó phải là tập hợp con của danh sách được trả về bởi getmembers().

Thay đổi trong phiên bản 3.5: Đã thêm tham số members.

TarFile.next()

Trả lại thành viên tiếp theo của kho lưu trữ dưới dạng đối tượng TarInfo, khi TarFile được mở để đọc. Trả lại None nếu không còn nữa.

TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)

Trích xuất tất cả các thành viên từ kho lưu trữ vào thư mục làm việc hiện tại hoặc thư mục path. Nếu members tùy chọn được cung cấp, nó phải là tập hợp con của danh sách được trả về bởi getmembers(). Thông tin thư mục như chủ sở hữu, thời gian sửa đổi và quyền được đặt sau khi tất cả thành viên đã được trích xuất. Điều này được thực hiện để giải quyết hai vấn đề: Thời gian sửa đổi của thư mục được đặt lại mỗi khi tệp được tạo trong đó. Và nếu quyền của thư mục không cho phép ghi thì việc giải nén tệp vào thư mục đó sẽ không thành công.

Nếu numeric_owner là True, số uid và gid từ tarfile sẽ được sử dụng để đặt chủ sở hữu/nhóm cho các tệp được trích xuất. Mặt khác, các giá trị được đặt tên từ tarfile sẽ được sử dụng.

Đối số filter chỉ định cách members được sửa đổi hoặc từ chối trước khi trích xuất. Xem Bộ lọc trích xuất để biết chi tiết. Bạn chỉ nên đặt cài đặt này một cách rõ ràng nếu yêu cầu các tính năng tar cụ thể hoặc filter='data' để hỗ trợ các phiên bản Python có mặc định kém an toàn hơn (3.13 trở xuống).

Cảnh báo

Không bao giờ trích xuất tài liệu lưu trữ từ các nguồn không đáng tin cậy mà không kiểm tra trước.

Kể từ Python 3.14, mặc định (data) sẽ ngăn chặn các vấn đề bảo mật nguy hiểm nhất. Tuy nhiên, nó sẽ không ngăn chặn được hành vi ngoài ý muốn hoặc không an toàn của all. Đọc phần Bộ lọc trích xuất để biết chi tiết.

Thay đổi trong phiên bản 3.5: Đã thêm tham số numeric_owner.

Thay đổi trong phiên bản 3.6: Tham số path chấp nhận path-like object.

Thay đổi trong phiên bản 3.12: Đã thêm tham số filter.

Thay đổi trong phiên bản 3.14: Tham số filter hiện được mặc định là 'data'.

TarFile.extract(member, path='', set_attrs=True, *, numeric_owner=False, filter=None)

Trích xuất một thành viên từ kho lưu trữ vào thư mục làm việc hiện tại, sử dụng tên đầy đủ của nó. Thông tin tập tin của nó được trích xuất chính xác nhất có thể. member có thể là tên tệp hoặc đối tượng TarInfo. Bạn có thể chỉ định một thư mục khác bằng path. path có thể là path-like object. Thuộc tính tệp (chủ sở hữu, mtime, chế độ) được đặt trừ khi set_attrs sai.

Các đối số numeric_owner và filter giống như đối với extractall().

Ghi chú

Phương pháp extract() không giải quyết được một số vấn đề trích xuất. Trong hầu hết các trường hợp, bạn nên cân nhắc sử dụng phương pháp extractall().

Cảnh báo

Không bao giờ trích xuất tài liệu lưu trữ từ các nguồn không đáng tin cậy mà không kiểm tra trước. Xem cảnh báo dành cho extractall() để biết chi tiết.

Thay đổi trong phiên bản 3.2: Đã thêm tham số set_attrs.

Thay đổi trong phiên bản 3.5: Đã thêm tham số numeric_owner.

Thay đổi trong phiên bản 3.6: Tham số path chấp nhận path-like object.

Thay đổi trong phiên bản 3.12: Đã thêm tham số filter.

TarFile.extractfile(member)

Trích xuất một thành viên từ kho lưu trữ dưới dạng đối tượng tệp. member có thể là tên tệp hoặc đối tượng TarInfo. Nếu member là một tệp thông thường hoặc một liên kết, một đối tượng io.BufferedReader sẽ được trả về. Đối với tất cả các thành viên hiện có khác, None được trả lại. Nếu member không xuất hiện trong kho lưu trữ, KeyError sẽ được nâng lên.

Thay đổi trong phiên bản 3.3: Trả về một đối tượng io.BufferedReader.

Thay đổi trong phiên bản 3.13: Đối tượng io.BufferedReader được trả về có thuộc tính mode luôn bằng 'rb'.

TarFile.errorlevel: int

Nếu errorlevel là 0 thì lỗi sẽ được bỏ qua khi sử dụng TarFile.extract() và TarFile.extractall(). Tuy nhiên, chúng xuất hiện dưới dạng thông báo lỗi trong đầu ra gỡ lỗi khi debug lớn hơn 0. Nếu 1 (mặc định), tất cả các lỗi fatal đều được đưa ra dưới dạng ngoại lệ OSError hoặc FilterError. Nếu 2, tất cả các lỗi non-fatal cũng được đưa ra dưới dạng ngoại lệ TarError.

Một số trường hợp ngoại lệ, ví dụ: những nguyên nhân gây ra bởi các loại đối số sai hoặc hỏng dữ liệu, luôn được nêu ra.

extraction filters tùy chỉnh sẽ tăng FilterError đối với lỗi fatal và ExtractError đối với lỗi non-fatal.

Lưu ý rằng khi có ngoại lệ xảy ra, kho lưu trữ có thể được trích xuất một phần. Trách nhiệm của người dùng là phải dọn dẹp.

TarFile.extraction_filter

Added in version 3.12.

extraction filter được sử dụng làm mặc định cho đối số filter của extract() và extractall().

Thuộc tính có thể là None hoặc có thể gọi được. Tên chuỗi không được phép cho thuộc tính này, không giống như đối số filter cho extract().

Nếu extraction_filter là None (mặc định), các phương pháp trích xuất sẽ sử dụng bộ lọc data theo mặc định.

Thuộc tính có thể được đặt trên các phiên bản hoặc được ghi đè trong các lớp con. Cũng có thể đặt nó trên chính lớp TarFile để đặt mặc định chung, tuy nhiên, vì nó ảnh hưởng đến tất cả việc sử dụng tarfile, nên cách tốt nhất là chỉ nên làm như vậy trong các ứng dụng cấp cao nhất hoặc site configuration. Để đặt mặc định chung theo cách này, một hàm lọc cần được gói trong staticmethod() để ngăn chặn việc đưa đối số self vào.

Thay đổi trong phiên bản 3.14: Bộ lọc mặc định được đặt thành data, không cho phép một số tính năng nguy hiểm như liên kết đến đường dẫn tuyệt đối hoặc đường dẫn bên ngoài đích đến. Trước đây, mặc định tương đương với fully_trusted.

TarFile.add(name, arcname=None, recursive=True, *, filter=None)

Thêm tệp name vào kho lưu trữ. name có thể là bất kỳ loại tệp nào (thư mục, fifo, liên kết tượng trưng, ​​​​v.v.). Nếu được cung cấp, arcname chỉ định tên thay thế cho tệp trong kho lưu trữ. Các thư mục được thêm đệ quy theo mặc định. Điều này có thể tránh được bằng cách đặt recursive thành False. Đệ quy thêm các mục theo thứ tự được sắp xếp. Nếu filter được cung cấp, thì đó phải là một hàm nhận đối số đối tượng TarInfo và trả về đối tượng TarInfo đã thay đổi. Thay vào đó, nếu nó trả về None thì đối tượng TarInfo sẽ bị loại khỏi kho lưu trữ. Xem Ví dụ để biết ví dụ.

Thay đổi trong phiên bản 3.2: Đã thêm tham số filter.

Thay đổi trong phiên bản 3.7: Đệ quy thêm các mục theo thứ tự được sắp xếp.

TarFile.addfile(tarinfo, fileobj=None)

Thêm đối tượng TarInfo tarinfo vào kho lưu trữ. Nếu tarinfo đại diện cho một tệp thông thường có kích thước khác 0 thì đối số fileobj phải là binary file và các byte tarinfo.size được đọc từ tệp đó và thêm vào kho lưu trữ. Bạn có thể tạo các đối tượng TarInfo trực tiếp hoặc bằng cách sử dụng gettarinfo().

Thay đổi trong phiên bản 3.13: fileobj phải được cung cấp cho các tệp thông thường có kích thước khác 0.

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)

Tạo đối tượng TarInfo từ kết quả của os.stat() hoặc tương đương trên tệp hiện có. Tệp được đặt tên theo name hoặc được chỉ định là file object fileobj với bộ mô tả tệp. name có thể là path-like object. Nếu được cung cấp, arcname chỉ định tên thay thế cho tệp trong kho lưu trữ, nếu không, tên được lấy từ thuộc tính name của fileobj hoặc đối số name. Tên phải là một chuỗi văn bản.

Bạn có thể sửa đổi một số thuộc tính của TarInfo trước khi thêm nó bằng addfile(). Nếu đối tượng tệp không phải là đối tượng tệp thông thường được đặt ở đầu tệp, các thuộc tính như size có thể cần sửa đổi. Đây là trường hợp của các đối tượng như GzipFile. Zz004zz cũng có thể được sửa đổi, trong trường hợp đó arcname có thể là một chuỗi giả.

Thay đổi trong phiên bản 3.6: Tham số name chấp nhận path-like object.

TarFile.close()

Đóng TarFile. Trong chế độ ghi, hai khối 0 hoàn thiện sẽ được thêm vào kho lưu trữ.

TarFile.pax_headers: dict

Một từ điển chứa các cặp khóa-giá trị của tiêu đề toàn cục pax.

Đối tượng TarInfo

Đối tượng TarInfo đại diện cho một thành viên trong TarFile. Ngoài việc lưu trữ tất cả các thuộc tính bắt buộc của một tệp (như loại tệp, kích thước, thời gian, quyền, chủ sở hữu, v.v.), nó còn cung cấp một số phương pháp hữu ích để xác định loại của tệp. Nó not chứa chính dữ liệu của tập tin.

Các đối tượng TarInfo được trả về bằng các phương thức của TarFile getmember(), getmembers() và gettarinfo().

Việc sửa đổi các đối tượng được trả về bởi getmember() hoặc getmembers() sẽ ảnh hưởng đến tất cả các hoạt động tiếp theo trên kho lưu trữ. Đối với những trường hợp không mong muốn, bạn có thể sử dụng copy.copy() hoặc gọi phương thức replace() để tạo bản sao sửa đổi trong một bước.

Một số thuộc tính có thể được đặt thành None để cho biết rằng một phần siêu dữ liệu không được sử dụng hoặc không xác định. Các phương thức TarInfo khác nhau xử lý None khác nhau:

  • Các phương thức extract() hoặc extractall() sẽ bỏ qua siêu dữ liệu tương ứng, để siêu dữ liệu này được đặt thành mặc định.

  • addfile() sẽ thất bại.

  • list() sẽ in một chuỗi giữ chỗ.

class tarfile.TarInfo(name='')

Tạo một đối tượng TarInfo.

classmethod TarInfo.frombuf(buf, encoding, errors)

Tạo và trả về đối tượng TarInfo từ bộ đệm chuỗi buf.

Tăng HeaderError nếu bộ đệm không hợp lệ.

classmethod TarInfo.fromtarfile(tarfile)

Đọc thành viên tiếp theo từ đối tượng TarFile tarfile và trả về nó dưới dạng đối tượng TarInfo.

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

Tạo bộ đệm chuỗi từ đối tượng TarInfo. Để biết thông tin về các đối số, hãy xem hàm tạo của lớp TarFile.

Thay đổi trong phiên bản 3.2: Sử dụng 'surrogateescape' làm mặc định cho đối số errors.

Đối tượng TarInfo có các thuộc tính dữ liệu công khai sau:

TarInfo.name: str

Tên của thành viên lưu trữ.

TarInfo.size: int

Kích thước tính bằng byte.

TarInfo.mtime: int | float

Thời gian sửa đổi lần cuối tính bằng giây kể từ epoch, như trong os.stat_result.st_mtime.

Thay đổi trong phiên bản 3.12: Có thể được đặt thành None cho extract() và extractall(), khiến quá trình trích xuất bị bỏ qua khi áp dụng thuộc tính này.

TarInfo.mode: int

Các bit cấp phép, như đối với os.chmod().

Thay đổi trong phiên bản 3.12: Có thể được đặt thành None cho extract() và extractall(), khiến quá trình trích xuất bị bỏ qua khi áp dụng thuộc tính này.

TarInfo.type

Loại tập tin. type thường là một trong những hằng số sau: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE. Để xác định loại đối tượng TarInfo thuận tiện hơn, hãy sử dụng các phương pháp is*() bên dưới.

TarInfo.linkname: str

Tên của tên tệp đích, chỉ xuất hiện trong các đối tượng TarInfo thuộc loại LNKTYPE và SYMTYPE.

Đối với các liên kết tượng trưng (SYMTYPE), linkname có liên quan đến thư mục chứa liên kết. Đối với các liên kết cứng (LNKTYPE), linkname có liên quan đến thư mục gốc của kho lưu trữ.

TarInfo.uid: int

ID người dùng của người dùng ban đầu đã lưu trữ thành viên này.

Thay đổi trong phiên bản 3.12: Có thể được đặt thành None cho extract() và extractall(), khiến quá trình trích xuất bị bỏ qua khi áp dụng thuộc tính này.

TarInfo.gid: int

ID nhóm của người dùng ban đầu đã lưu trữ thành viên này.

Thay đổi trong phiên bản 3.12: Có thể được đặt thành None cho extract() và extractall(), khiến quá trình trích xuất bị bỏ qua khi áp dụng thuộc tính này.

TarInfo.uname: str

Tên người dùng.

Thay đổi trong phiên bản 3.12: Có thể được đặt thành None cho extract() và extractall(), khiến quá trình trích xuất bị bỏ qua khi áp dụng thuộc tính này.

TarInfo.gname: str

Tên nhóm.

Thay đổi trong phiên bản 3.12: Có thể được đặt thành None cho extract() và extractall(), khiến quá trình trích xuất bị bỏ qua khi áp dụng thuộc tính này.

TarInfo.chksum: int

Tổng kiểm tra tiêu đề.

TarInfo.devmajor: int

Số chính của thiết bị.

TarInfo.devminor: int

Số nhỏ của thiết bị.

TarInfo.offset: int

Tiêu đề tar bắt đầu ở đây.

TarInfo.offset_data: int

Dữ liệu của tập tin bắt đầu ở đây.

TarInfo.sparse

Thông tin thành viên thưa thớt.

TarInfo.pax_headers: dict

Một từ điển chứa các cặp khóa-giá trị của tiêu đề mở rộng pax được liên kết.

TarInfo.replace(name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)

Added in version 3.12.

Trả về bản sao new của đối tượng TarInfo với các thuộc tính đã cho đã thay đổi. Ví dụ: để trả về TarInfo với tên nhóm được đặt thành 'staff', hãy sử dụng:

new_tarinfo = old_tarinfo.replace(gname='staff')

Theo mặc định, một bản sao sâu sẽ được tạo. Nếu deep sai thì bản sao sẽ nông, tức là pax_headers và mọi thuộc tính tùy chỉnh đều được chia sẻ với đối tượng TarInfo ban đầu.

Đối tượng TarInfo cũng cung cấp một số phương thức truy vấn thuận tiện:

TarInfo.isfile()

Trả về True nếu đối tượng TarInfo là một tệp thông thường.

TarInfo.isreg()

Tương tự với isfile()

TarInfo.isdir()

Trả về True nếu đó là một thư mục.

TarInfo.issym()

Trả về True nếu đó là liên kết tượng trưng.

TarInfo.islnk()

Trả về True nếu là link cứng.

TarInfo.ischr()

Trả về True nếu nó là thiết bị ký tự.

TarInfo.isblk()

Trả về True nếu là thiết bị khối.

TarInfo.isfifo()

Trả về True nếu đó là FIFO.

TarInfo.isdev()

Trả về True nếu nó là một trong các thiết bị ký tự, thiết bị khối hoặc FIFO.

Bộ lọc trích xuất

Added in version 3.12.

Định dạng tar được thiết kế để ghi lại tất cả các chi tiết của hệ thống tệp giống UNIX, điều này khiến nó trở nên rất mạnh mẽ. Thật không may, các tính năng này giúp dễ dàng tạo các tệp tar có tác dụng không mong muốn - và có thể độc hại - khi được giải nén. Ví dụ: giải nén tệp tar có thể ghi đè lên các tệp tùy ý theo nhiều cách khác nhau (ví dụ: bằng cách sử dụng đường dẫn tuyệt đối, thành phần đường dẫn .. hoặc liên kết tượng trưng ảnh hưởng đến các thành viên sau này).

Trong hầu hết các trường hợp, chức năng đầy đủ là không cần thiết. Do đó, tarfile hỗ trợ các bộ lọc trích xuất: một cơ chế nhằm hạn chế chức năng và do đó giảm thiểu một số vấn đề bảo mật.

Cảnh báo

Không có bộ lọc nào có sẵn chặn các tính năng lưu trữ nguy hiểm của all. Không bao giờ trích xuất tài liệu lưu trữ từ các nguồn không đáng tin cậy mà không kiểm tra trước. Xem thêm Gợi ý xác minh thêm.

Xem thêm

PEP 706

Chứa thêm động lực và lý do đằng sau thiết kế.

Đối số filter cho TarFile.extract() hoặc extractall() có thể là:

  • chuỗi 'fully_trusted': Tôn trọng tất cả siêu dữ liệu như được chỉ định trong kho lưu trữ. Nên sử dụng nếu người dùng hoàn toàn tin tưởng vào kho lưu trữ hoặc thực hiện xác minh phức tạp của riêng họ.

  • chuỗi 'tar': Tôn vinh hầu hết các tính năng dành riêng cho tar (tức là các tính năng của hệ thống tệp giống UNIX), nhưng chặn các tính năng rất có thể gây ngạc nhiên hoặc độc hại. Xem tar_filter() để biết chi tiết.

  • chuỗi 'data': Bỏ qua hoặc chặn hầu hết các tính năng dành riêng cho hệ thống tệp giống UNIX. Dành cho việc trích xuất kho lưu trữ dữ liệu đa nền tảng. Xem data_filter() để biết chi tiết.

  • None (mặc định): Sử dụng TarFile.extraction_filter.

    Nếu đó cũng là None (mặc định), bộ lọc 'data' sẽ được sử dụng.

    Thay đổi trong phiên bản 3.14: Bộ lọc mặc định được đặt thành data. Trước đây, mặc định tương đương với fully_trusted.

  • Một lệnh gọi sẽ được gọi cho mỗi thành viên được trích xuất với TarInfo mô tả thành viên và đường dẫn đích đến nơi giải nén kho lưu trữ (tức là sử dụng cùng một đường dẫn cho tất cả các thành viên):

    filter(member: TarInfo, path: str, /) -> TarInfo | không có

    Có thể gọi được ngay trước khi mỗi thành viên được trích xuất, do đó, nó có thể tính đến trạng thái hiện tại của đĩa. Nó có thể:

    • trả về một đối tượng TarInfo sẽ được sử dụng thay vì siêu dữ liệu trong kho lưu trữ hoặc

    • trả về None, trong trường hợp đó thành viên sẽ bị bỏ qua, hoặc

    • đưa ra một ngoại lệ để hủy bỏ thao tác hoặc bỏ qua thành viên, tùy thuộc vào errorlevel. Lưu ý rằng khi quá trình trích xuất bị hủy bỏ, extractall() có thể khiến kho lưu trữ được giải nén một phần. Nó không cố gắng dọn dẹp.

Bộ lọc được đặt tên mặc định

Các bộ lọc được đặt tên và xác định trước có sẵn dưới dạng hàm nên chúng có thể được sử dụng lại trong các bộ lọc tùy chỉnh:

tarfile.fully_trusted_filter(member, path)

Trả về member không thay đổi.

Điều này thực hiện bộ lọc 'fully_trusted'.

tarfile.tar_filter(member, path)

Triển khai bộ lọc 'tar'.

  • Loại bỏ các dấu gạch chéo ở đầu (/ và os.sep) khỏi tên tệp.

  • Refuse để trích xuất các tệp có đường dẫn tuyệt đối (trong trường hợp tên là tuyệt đối ngay cả sau khi loại bỏ dấu gạch chéo, ví dụ: C:/foo trên Windows). Điều này làm tăng AbsolutePathError.

  • Refuse để giải nén các tệp có đường dẫn tuyệt đối (sau khi đi theo các liên kết tượng trưng) sẽ nằm ngoài đích. Điều này làm tăng OutsideDestinationError.

  • Xóa các bit chế độ cao (setuid, setgid, Sticky) và nhóm/các bit ghi khác (S_IWGRP | S_IWOTH).

Trả về thành viên TarInfo đã sửa đổi.

tarfile.data_filter(member, path)

Triển khai bộ lọc 'data'. Ngoài những gì tar_filter làm:

  • Chuẩn hóa mục tiêu liên kết (TarInfo.linkname) bằng os.path.normpath(). Lưu ý rằng điều này sẽ loại bỏ các thành phần .. bên trong, điều này có thể thay đổi ý nghĩa của liên kết nếu đường dẫn trong TarInfo.linkname đi qua các liên kết tượng trưng.

  • Refuse để trích xuất các liên kết (cứng hoặc mềm) liên kết đến các đường dẫn tuyệt đối hoặc các liên kết bên ngoài đích.

    Điều này làm tăng AbsoluteLinkError hoặc LinkOutsideDestinationError.

    Lưu ý rằng những tệp như vậy bị từ chối ngay cả trên nền tảng không hỗ trợ liên kết tượng trưng.

  • Refuse để giải nén các tập tin thiết bị (bao gồm cả đường ống). Điều này làm tăng SpecialFileError.

  • Đối với các tệp thông thường, bao gồm các liên kết cứng:

    • Đặt quyền đọc và ghi của chủ sở hữu (S_IRUSR | S_IWUSR).

    • Xóa nhóm và quyền thực thi khác (S_IXGRP | S_IXOTH) nếu chủ sở hữu không có nó (S_IXUSR).

  • Đối với các tệp (thư mục) khác, hãy đặt mode thành None để các phương pháp trích xuất bỏ qua việc áp dụng các bit cấp phép.

  • Đặt thông tin người dùng và nhóm (uid, gid, uname, gname) thành None, để các phương pháp trích xuất bỏ qua việc thiết lập thông tin đó.

Trả về thành viên TarInfo đã sửa đổi.

Lưu ý rằng bộ lọc này không chặn các tính năng lưu trữ nguy hiểm của all. Xem Gợi ý xác minh thêm để biết chi tiết.

Thay đổi trong phiên bản 3.14: Mục tiêu liên kết hiện đã được chuẩn hóa.

Lọc lỗi

Khi một bộ lọc từ chối giải nén một tập tin, nó sẽ đưa ra một ngoại lệ thích hợp, một lớp con của FilterError. Điều này sẽ hủy bỏ việc trích xuất nếu TarFile.errorlevel là 1 hoặc nhiều hơn. Với errorlevel=0, lỗi sẽ được ghi lại và thành viên sẽ bị bỏ qua nhưng quá trình trích xuất sẽ tiếp tục.

Gợi ý xác minh thêm

Ngay cả với filter='data', tarfile không phù hợp để giải nén các tệp không đáng tin cậy mà không kiểm tra trước. Trong số các vấn đề khác, các bộ lọc được xác định trước không ngăn chặn các cuộc tấn công từ chối dịch vụ. Người dùng nên thực hiện kiểm tra bổ sung.

Dưới đây là danh sách không đầy đủ những điều cần xem xét:

  • Giải nén vào new temporary directory để ngăn chặn ví dụ: khai thác các liên kết có sẵn và để dễ dàng dọn dẹp hơn sau khi trích xuất không thành công.

  • Không cho phép các liên kết tượng trưng nếu bạn không cần chức năng này.

  • Khi làm việc với dữ liệu không đáng tin cậy, hãy sử dụng các giới hạn bên ngoài (ví dụ: cấp hệ điều hành) đối với mức sử dụng ổ đĩa, bộ nhớ và CPU.

  • Kiểm tra tên tệp dựa trên danh sách các ký tự được phép (để lọc các ký tự điều khiển, ký tự dễ nhầm lẫn, dấu phân cách đường dẫn ngoại, v.v.).

  • Kiểm tra xem tên tệp có phần mở rộng dự kiến hay không (không khuyến khích các tệp thực thi khi bạn “nhấp vào chúng” hoặc các tệp không có phần mở rộng như tên thiết bị đặc biệt của Windows).

  • Giới hạn số lượng tệp được trích xuất, tổng kích thước của dữ liệu được trích xuất, độ dài tên tệp (bao gồm cả độ dài liên kết tượng trưng) và kích thước của từng tệp riêng lẻ.

  • Kiểm tra các tệp sẽ bị ẩn trên hệ thống tệp không phân biệt chữ hoa chữ thường.

Cũng lưu ý rằng:

  • Tệp Tar có thể chứa nhiều phiên bản của cùng một tệp. Những cái sau dự kiến ​​​​sẽ ghi đè lên bất kỳ cái nào trước đó. Tính năng này rất quan trọng để cho phép cập nhật kho lưu trữ băng từ, nhưng có thể bị lạm dụng có mục đích xấu.

  • tarfile không bảo vệ khỏi các sự cố với dữ liệu “trực tiếp”, ví dụ: kẻ tấn công sửa đổi thư mục đích (hoặc nguồn) trong khi đang tiến hành trích xuất (hoặc lưu trữ).

Hỗ trợ các phiên bản Python cũ hơn

Bộ lọc trích xuất đã được thêm vào Python 3.12, nhưng có thể được chuyển trở lại các phiên bản cũ hơn dưới dạng bản cập nhật bảo mật. Để kiểm tra xem tính năng này có khả dụng hay không, hãy sử dụng ví dụ: hasattr(tarfile, 'data_filter') thay vì kiểm tra phiên bản Python.

Các ví dụ sau đây cho thấy cách hỗ trợ các phiên bản Python có và không có tính năng này. Lưu ý rằng việc cài đặt extraction_filter sẽ ảnh hưởng đến mọi hoạt động tiếp theo.

  • Kho lưu trữ hoàn toàn đáng tin cậy:

    my_tarfile.extraction_filter = (thành viên lambda, đường dẫn: thành viên)
my_tarfile.extractall()

  • Sử dụng bộ lọc 'data' nếu có, nhưng hoàn nguyên về hành vi Python 3.11 ('fully_trusted') nếu tính năng này không khả dụng:

    my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                       (thành viên lambda, đường dẫn: thành viên))
my_tarfile.extractall()

  • Sử dụng bộ lọc 'data'; fail nếu không có:

    my_tarfile.extractall(filter=tarfile.data_filter)

    hoặc:

    my_tarfile.extraction_filter = tarfile.data_filter
my_tarfile.extractall()

  • Sử dụng bộ lọc 'data'; warn nếu không có:

    nếu hasattr(tarfile, 'data_filter'):
    my_tarfile.extractall(filter='data')
khác:
    # remove cái này khi không còn cần thiết nữa
    Warn_the_user('Giải nén có thể không an toàn; hãy cân nhắc việc cập nhật Python')
    my_tarfile.extractall()

Ví dụ về bộ lọc trích xuất trạng thái

Mặc dù các phương pháp trích xuất của tarfile có thể gọi filter đơn giản, các bộ lọc tùy chỉnh có thể là các đối tượng phức tạp hơn với trạng thái bên trong. Có thể hữu ích khi viết chúng như trình quản lý bối cảnh, được sử dụng như thế này

với StatefulFilter() là filter_func:
    tar.extractall(path, filter=filter_func)

Bộ lọc như vậy có thể được viết là, ví dụ:

lớp StatefulFilter:
    định nghĩa __init__(tự):
        self.file_count = 0

    chắc chắn __enter__(tự):
        tự trở về

    def __call__(bản thân, thành viên, đường dẫn):
        self.file_count += 1
        thành viên trở lại

    def __exit__(self, *exc_info):
        print(f'{self.file_count} tệp được trích xuất')

Giao diện dòng lệnh

Added in version 3.4.

Mô-đun tarfile cung cấp giao diện dòng lệnh đơn giản để tương tác với kho lưu trữ tar.

Nếu bạn muốn tạo một kho lưu trữ tar mới, hãy chỉ định tên của nó sau tùy chọn -c và sau đó liệt kê (các) tên tệp sẽ được đưa vào:

$ python -m tarfile -c monty.tar spam.txt trứng.txt

Việc chuyển một thư mục cũng được chấp nhận:

$ python -m tarfile -c monty.tar life-of-brian_1979/

Nếu bạn muốn trích xuất kho lưu trữ tar vào thư mục hiện tại, hãy sử dụng tùy chọn -e:

$ python -m tarfile -e monty.tar

Bạn cũng có thể trích xuất kho lưu trữ tar vào một thư mục khác bằng cách chuyển tên thư mục:

$ python -m tarfile -e monty.tar other-dir/

Để biết danh sách các tệp trong kho lưu trữ tar, hãy sử dụng tùy chọn -l:

$ python -m tarfile -l monty.tar

Tùy chọn dòng lệnh

-l <tarfile>
--list <tarfile>

Liệt kê các tập tin trong một tarfile.

-c <tarfile> <source1> ... <sourceN>
--create <tarfile> <source1> ... <sourceN>

Tạo tarfile từ các tập tin nguồn.

-e <tarfile> [<output_dir>]
--extract <tarfile> [<output_dir>]

Trích xuất tarfile vào thư mục hiện tại nếu output_dir không được chỉ định.

-t <tarfile>
--test <tarfile>

Kiểm tra xem tarfile có hợp lệ hay không.

-v, --verbose

Đầu ra dài dòng.

--filter <filtername>

Chỉ định filter cho --extract. Xem Bộ lọc trích xuất để biết chi tiết. Chỉ tên chuỗi mới được chấp nhận (nghĩa là fully_trusted, tar và data).

Ví dụ

Đọc ví dụ

Cách trích xuất toàn bộ kho lưu trữ tar vào thư mục làm việc hiện tại

tập tin nhập khẩu
tar = tarfile.open("sample.tar.gz")
tar.extractall(filter='data')
tar.close()

Cách trích xuất một tập hợp con của kho lưu trữ tar bằng TarFile.extractall() bằng cách sử dụng chức năng tạo thay vì danh sách

hệ điều hành nhập khẩu
tập tin nhập khẩu

def py_files(thành viên):
    cho tarinfo trong các thành viên:
        nếu os.path.splitext(tarinfo.name)[1] == ".py":
            thông tin năng suất

tar = tarfile.open("sample.tar.gz")
tar.extractall(thành viên=py_files(tar))
tar.close()

Cách đọc kho lưu trữ tar nén gzip và hiển thị một số thông tin thành viên

tập tin nhập khẩu
tar = tarfile.open("sample.tar.gz", "r:gz")
cho tarinfo trong tar:
    print(tarinfo.name, "is", tarinfo.size, "kích thước byte và là ", end="")
    nếu tarinfo.isreg():
        print("một tập tin thông thường.")
    Elif tarinfo.isdir():
        in ("một thư mục.")
    khác:
        print("cái gì đó khác.")
tar.close()

Viết ví dụ

Cách tạo kho lưu trữ tar không nén từ danh sách tên tệp

tập tin nhập khẩu
tar = tarfile.open("sample.tar", "w")
cho tên trong ["foo", "bar", "quux"]:
    tar.add(tên)
tar.close()

Ví dụ tương tự sử dụng câu lệnh with:

tập tin nhập khẩu
với tarfile.open("sample.tar", "w") là tar:
    cho tên trong ["foo", "bar", "quux"]:
        tar.add(tên)

Cách tạo và ghi kho lưu trữ vào thiết bị xuất chuẩn bằng sys.stdout.buffer trong tham số fileobj trong TarFile.add()

hệ thống nhập khẩu
tập tin nhập khẩu
với tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) là tar:
    cho tên trong ["foo", "bar", "quux"]:
        tar.add(tên)

Cách tạo kho lưu trữ và đặt lại thông tin người dùng bằng tham số filter trong TarFile.add()

tập tin nhập khẩu
thiết lập lại def (tarinfo):
    tarinfo.uid = tarinfo.gid = 0
    tarinfo.uname = tarinfo.gname = "root"
    trả lại tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()

Các định dạng tar được hỗ trợ

Có ba định dạng tar có thể được tạo bằng mô-đun tarfile:

  • Định dạng ustar POSIX.1-1988 (USTAR_FORMAT). Nó hỗ trợ tên tệp có độ dài tối đa 256 ký tự và tên liên kết lên tới 100 ký tự. Kích thước tệp tối đa là 8 GiB. Đây là một định dạng cũ và hạn chế nhưng được hỗ trợ rộng rãi.

  • Định dạng tar GNU (GNU_FORMAT). Nó hỗ trợ tên tệp và tên liên kết dài, tệp lớn hơn 8 GiB và tệp thưa thớt. Đây là tiêu chuẩn thực tế trên các hệ thống GNU/Linux. tarfile hỗ trợ đầy đủ các phần mở rộng tar GNU cho các tên dài, hỗ trợ tệp thưa thớt ở chế độ chỉ đọc.

  • Định dạng pax POSIX.1-2001 (PAX_FORMAT). Đây là định dạng linh hoạt nhất và hầu như không có giới hạn. Nó hỗ trợ tên tệp và tên liên kết dài, tệp lớn và lưu trữ tên đường dẫn theo cách di động. Việc triển khai tar hiện đại, bao gồm GNU tar, bsdtar/libarchive và star, hỗ trợ đầy đủ các tính năng pax mở rộng; một số thư viện cũ hoặc không được bảo trì có thể không, nhưng nên xử lý các kho lưu trữ pax như thể chúng ở định dạng ustar được hỗ trợ phổ biến. Đây là định dạng mặc định hiện tại cho các kho lưu trữ mới.

    Nó mở rộng định dạng ustar hiện có với các tiêu đề bổ sung cho thông tin không thể được lưu trữ bằng cách khác. Có hai loại tiêu đề pax: Tiêu đề mở rộng chỉ ảnh hưởng đến tiêu đề tệp tiếp theo, tiêu đề chung có giá trị cho toàn bộ kho lưu trữ và ảnh hưởng đến tất cả các tệp sau. Tất cả dữ liệu trong tiêu đề pax được mã hóa bằng UTF-8 vì lý do tính di động.

Có một số biến thể khác của định dạng tar có thể đọc được nhưng không thể tạo:

  • Định dạng V7 cổ xưa. Đây là định dạng tar đầu tiên từ Unix Seventh Edition, chỉ lưu trữ các tệp và thư mục thông thường. Tên không được dài quá 100 ký tự, không có thông tin tên người dùng/nhóm. Một số kho lưu trữ đã tính toán sai tổng kiểm tra tiêu đề trong trường hợp các trường có ký tự không phải ASCII.

  • Định dạng mở rộng tar của SunOS. Định dạng này là một biến thể của định dạng pax POSIX.1-2001 nhưng không tương thích.

vấn đề về Unicode

Định dạng tar ban đầu được hình thành để tạo bản sao lưu trên ổ băng từ với mục tiêu chính là lưu giữ thông tin hệ thống tệp. Ngày nay, kho lưu trữ tar thường được sử dụng để phân phối tệp và trao đổi tệp lưu trữ qua mạng. Một vấn đề của định dạng ban đầu (là cơ sở của tất cả các định dạng khác) là không có khái niệm hỗ trợ các mã hóa ký tự khác nhau. Ví dụ: kho lưu trữ tar thông thường được tạo trên hệ thống UTF-8 không thể đọc chính xác trên hệ thống Latin-1 nếu nó chứa các ký tự không phải ASCII. Siêu dữ liệu văn bản (như tên tệp, tên liên kết, tên người dùng/nhóm) sẽ bị hỏng. Thật không may, không có cách nào để tự động phát hiện mã hóa của kho lưu trữ. Định dạng pax được thiết kế để giải quyết vấn đề này. Nó lưu trữ siêu dữ liệu không phải ASCII bằng cách sử dụng mã hóa ký tự phổ quát UTF-8.

Chi tiết chuyển đổi ký tự trong tarfile được kiểm soát bởi các đối số từ khóa encoding và errors của lớp TarFile.

encoding xác định mã hóa ký tự để sử dụng cho siêu dữ liệu trong kho lưu trữ. Giá trị mặc định là sys.getfilesystemencoding() hoặc 'ascii' làm giá trị dự phòng. Tùy thuộc vào việc kho lưu trữ được đọc hay ghi, siêu dữ liệu phải được giải mã hoặc mã hóa. Nếu encoding không được đặt phù hợp, quá trình chuyển đổi này có thể không thành công.

Đối số errors xác định cách xử lý các ký tự không thể chuyển đổi. Các giá trị có thể được liệt kê trong phần Trình xử lý lỗi. Lược đồ mặc định là 'surrogateescape' mà Python cũng sử dụng cho các lệnh gọi hệ thống tệp của nó, xem Tên tệp, đối số dòng lệnh và biến môi trường.

Đối với kho lưu trữ PAX_FORMAT (mặc định), encoding thường không cần thiết vì tất cả siêu dữ liệu được lưu trữ bằng UTF-8. encoding chỉ được sử dụng trong một số trường hợp hiếm hoi khi các tiêu đề pax nhị phân được giải mã hoặc khi các chuỗi có ký tự thay thế được lưu trữ.