gzip --- Hỗ trợ các tập tin gzip

Source code: Lib/gzip.py

---

Mô-đun này cung cấp một giao diện đơn giản để nén và giải nén các tệp giống như các chương trình GNU gzip và gunzip.

Đây là một optional module. Nếu nó 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.

Việc nén dữ liệu được cung cấp bởi mô-đun zlib.

Mô-đun gzip cung cấp lớp GzipFile, cũng như các chức năng tiện lợi open(), compress() và decompress(). Lớp GzipFile đọc và ghi các tệp định dạng gzip-, tự động nén hoặc giải nén dữ liệu để nó trông giống như một file object thông thường.

Lưu ý rằng các định dạng tệp bổ sung có thể được giải nén bằng chương trình gzip và gunzip, chẳng hạn như các định dạng do compress và pack tạo ra, không được mô-đun này hỗ trợ.

Mô-đun xác định các mục sau:

gzip.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

Mở tệp nén gzip ở chế độ nhị phân hoặc văn bản, trả về file object.

Đối số filename có thể là tên tệp thực tế (đối tượng str hoặc bytes) hoặc đối tượng tệp hiện có để đọc hoặc ghi vào.

Đối số mode có thể là bất kỳ 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' hoặc 'xb' cho chế độ nhị phân hoặc 'rt', 'at', 'wt' hoặc 'xt' cho chế độ văn bản. Mặc định là 'rb'.

Đối số compresslevel là một số nguyên từ 0 đến 9, giống như đối với hàm tạo GzipFile.

Đối với chế độ nhị phân, hàm này tương đương với hàm tạo GzipFile: GzipFile(filename, mode, compresslevel). Trong trường hợp này, không được cung cấp các đối số encoding, errors và newline.

Đối với chế độ văn bản, một đối tượng GzipFile được tạo và được gói trong một phiên bản io.TextIOWrapper với mã hóa được chỉ định, hành vi xử lý lỗi và (các) kết thúc dòng.

Thay đổi trong phiên bản 3.3: Đã thêm hỗ trợ để filename trở thành đối tượng tệp, hỗ trợ chế độ văn bản và các đối số encoding, errors và newline.

Thay đổi trong phiên bản 3.4: Đã thêm hỗ trợ cho các chế độ 'x', 'xb' và 'xt'.

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

exception gzip.BadGzipFile

Một ngoại lệ được đưa ra đối với các tệp gzip không hợp lệ. Nó kế thừa từ OSError. EOFError và zlib.error cũng có thể được nâng lên đối với các tệp gzip không hợp lệ.

Added in version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

Trình xây dựng cho lớp GzipFile, mô phỏng hầu hết các phương thức của file object, ngoại trừ phương thức truncate(). Ít nhất một trong số fileobj và filename phải có giá trị không tầm thường.

Phiên bản lớp mới dựa trên fileobj, có thể là một tệp thông thường, một đối tượng io.BytesIO hoặc bất kỳ đối tượng nào khác mô phỏng một tệp. Nó mặc định là None, trong trường hợp đó filename được mở để cung cấp một đối tượng tệp.

Khi fileobj không phải là None, đối số filename chỉ được sử dụng để đưa vào tiêu đề tệp gzip, có thể bao gồm tên tệp gốc của tệp không nén. Nó mặc định có tên tệp là fileobj, nếu có thể thấy rõ; mặt khác, nó mặc định là chuỗi trống và trong trường hợp này, tên tệp gốc không được đưa vào tiêu đề.

Đối số mode có thể là bất kỳ 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' hoặc 'xb', tùy thuộc vào việc tệp sẽ được đọc hay ghi. Mặc định là chế độ fileobj nếu thấy rõ; nếu không thì mặc định là 'rb'. Trong các bản phát hành Python trong tương lai, chế độ fileobj sẽ không được sử dụng. Tốt hơn là luôn chỉ định mode để viết.

Lưu ý rằng tệp luôn được mở ở chế độ nhị phân. Để mở tệp nén ở chế độ văn bản, hãy sử dụng open() (hoặc gói GzipFile của bạn bằng io.TextIOWrapper).

Đối số compresslevel là một số nguyên từ 0 đến 9 kiểm soát mức độ nén; 1 là nhanh nhất và tạo ra độ nén ít nhất, còn 9 là chậm nhất và tạo ra độ nén nhiều nhất. 0 không nén. Mặc định là 9.

Đối số mtime tùy chọn là dấu thời gian được gzip yêu cầu. Thời gian ở định dạng Unix, tức là số giây kể từ 00:00:00 UTC, ngày 1 tháng 1 năm 1970. Nếu mtime bị bỏ qua hoặc None, thời gian hiện tại sẽ được sử dụng. Sử dụng mtime = 0 để tạo luồng nén không phụ thuộc vào thời gian tạo.

Xem bên dưới để biết thuộc tính mtime được đặt khi giải nén.

Việc gọi phương thức close() của đối tượng GzipFile không đóng fileobj, vì bạn có thể muốn thêm nhiều tài liệu hơn sau dữ liệu nén. Điều này cũng cho phép bạn chuyển một đối tượng io.BytesIO được mở để ghi dưới dạng fileobj và truy xuất bộ nhớ đệm kết quả bằng phương thức getvalue() của đối tượng io.BytesIO.

GzipFile hỗ trợ giao diện io.BufferedIOBase, bao gồm phép lặp và câu lệnh with. Chỉ có phương pháp truncate() không được triển khai.

GzipFile cũng cung cấp phương thức và thuộc tính sau:

peek(n)

Đọc byte không nén n mà không cần nâng cao vị trí tệp. Số byte trả về có thể nhiều hơn hoặc ít hơn yêu cầu.

Ghi chú

Mặc dù việc gọi peek() không thay đổi vị trí tệp của GzipFile nhưng nó có thể thay đổi vị trí của đối tượng tệp cơ bản (ví dụ: nếu GzipFile được tạo bằng tham số fileobj).

Added in version 3.2.

mode

'rb' để đọc và 'wb' để viết.

Thay đổi trong phiên bản 3.13: Trong các phiên bản trước đó là số nguyên 1 hoặc 2.

mtime

Khi giải nén, thuộc tính này được đặt thành dấu thời gian cuối cùng trong tiêu đề được đọc gần đây nhất. Nó là một số nguyên, chứa số giây kể từ kỷ nguyên Unix (00:00:00 UTC, ngày 1 tháng 1 năm 1970). Giá trị ban đầu trước khi đọc bất kỳ tiêu đề nào là None.

name

Đường dẫn đến tệp gzip trên đĩa, dưới dạng str hoặc bytes. Tương đương với đầu ra của os.fspath() trên đường dẫn đầu vào ban đầu, không có sự chuẩn hóa, độ phân giải hoặc mở rộng nào khác.

Thay đổi trong phiên bản 3.1: Hỗ trợ cho câu lệnh with đã được thêm vào, cùng với đối số hàm tạo mtime và thuộc tính mtime.

Thay đổi trong phiên bản 3.2: Đã thêm hỗ trợ cho các tệp không có phần đệm và không thể tìm kiếm được.

Thay đổi trong phiên bản 3.3: Phương pháp io.BufferedIOBase.read1() hiện đã được triển khai.

Thay đổi trong phiên bản 3.4: Đã thêm hỗ trợ cho chế độ 'x' và 'xb'.

Thay đổi trong phiên bản 3.5: Đã thêm hỗ trợ để viết bytes-like objects tùy ý. Phương thức read() hiện chấp nhận đối số là None.

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

Sắp loại bỏ từ phiên bản 3.9: Việc mở GzipFile để viết mà không chỉ định đối số mode không được dùng nữa.

Thay đổi trong phiên bản 3.12: Xóa thuộc tính filename, thay vào đó hãy sử dụng thuộc tính name.

gzip.compress(data, compresslevel=9, *, mtime=0)

Nén data, trả về đối tượng bytes chứa dữ liệu đã nén. compresslevel và mtime có cùng ý nghĩa như trong hàm tạo GzipFile ở trên, nhưng mtime mặc định là 0 cho đầu ra có thể lặp lại.

Added in version 3.2.

Thay đổi trong phiên bản 3.8: Đã thêm tham số mtime cho đầu ra có thể tái tạo.

Thay đổi trong phiên bản 3.11: Tốc độ được cải thiện bằng cách nén tất cả dữ liệu cùng một lúc thay vì theo kiểu truyền phát. Các cuộc gọi có mtime được đặt thành 0 sẽ được ủy quyền cho zlib.compress() để có tốc độ tốt hơn. Trong trường hợp này, đầu ra có thể chứa giá trị byte "OS" tiêu đề gzip khác với 255 "không xác định" do quá trình triển khai zlib cơ bản cung cấp.

Thay đổi trong phiên bản 3.13: Byte hệ điều hành tiêu đề gzip được đảm bảo được đặt thành 255 khi chức năng này được sử dụng như trường hợp trong phiên bản 3.10 trở về trước.

Thay đổi trong phiên bản 3.14: Tham số mtime hiện được mặc định là 0 cho đầu ra có thể tái tạo. Đối với hành vi sử dụng thời gian hiện tại trước đó, hãy chuyển None sang mtime.

gzip.decompress(data)

Giải nén data, trả về đối tượng bytes chứa dữ liệu không nén. Chức năng này có khả năng giải nén dữ liệu gzip nhiều thành viên (nhiều khối gzip được nối với nhau). Khi dữ liệu chắc chắn chỉ chứa một thành viên, hàm zlib.decompress() với wbits được đặt thành 31 sẽ nhanh hơn.

Added in version 3.2.

Thay đổi trong phiên bản 3.11: Tốc độ được cải thiện bằng cách giải nén các thành phần cùng một lúc trong bộ nhớ thay vì theo kiểu truyền phát.

Ví dụ về cách sử dụng

Ví dụ về cách đọc tệp nén:

nhập gzip
với gzip.open('/home/joe/file.txt.gz', 'rb') là f:
    file_content = f.read()

Ví dụ về cách tạo tệp GZIP nén:

nhập gzip
content = b"Có rất nhiều nội dung ở đây"
với gzip.open('/home/joe/file.txt.gz', 'wb') là f:
    f.write(nội dung)

Ví dụ về cách GZIP nén tệp hiện có:

nhập gzip
nhập khẩu
với open('/home/joe/file.txt', 'rb') là f_in:
    với gzip.open('/home/joe/file.txt.gz', 'wb') là f_out:
        im lặng.copyfileobj(f_in, f_out)

Ví dụ về cách GZIP nén chuỗi nhị phân:

nhập gzip
s_in = b"Có rất nhiều nội dung ở đây"
s_out = gzip.compress(s_in)

Xem thêm

Mô-đun zlib

Mô-đun nén dữ liệu cơ bản cần thiết để hỗ trợ định dạng tệp gzip.

Trong trường hợp quá trình nén gzip (de) bị tắc nghẽn, gói python-isal sẽ tăng tốc độ nén (de) bằng API gần như tương thích.

Giao diện dòng lệnh

Mô-đun gzip cung cấp giao diện dòng lệnh đơn giản để nén hoặc giải nén tệp.

Sau khi thực thi, mô-đun gzip sẽ giữ lại (các) tệp đầu vào.

Thay đổi trong phiên bản 3.8: Thêm giao diện dòng lệnh mới với cách sử dụng. Theo mặc định, khi bạn thực thi CLI, mức nén mặc định là 6.

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

file

Nếu file không được chỉ định, hãy đọc từ sys.stdin.

--fast

Cho biết phương pháp nén nhanh nhất (nén ít hơn).

--best

Cho biết phương pháp nén chậm nhất (nén tốt nhất).

-d, --decompress

Giải nén tập tin đã cho.

-h, --help

Hiển thị thông báo trợ giúp.