shutil --- Thao tác tệp cấp cao

Source code: Lib/shutil.py

---

Mô-đun shutil cung cấp một số thao tác cấp cao trên tệp và bộ sưu tập tệp. Đặc biệt, các chức năng được cung cấp hỗ trợ sao chép và xóa tập tin. Để biết các thao tác trên từng tệp riêng lẻ, hãy xem thêm mô-đun os.

Cảnh báo

Ngay cả các chức năng sao chép tệp cấp cao hơn (shutil.copy(), shutil.copy2()) cũng không thể sao chép tất cả siêu dữ liệu tệp.

Trên nền tảng POSIX, điều này có nghĩa là chủ sở hữu tệp và nhóm cũng như ACL sẽ bị mất. Trên Mac OS, nhánh tài nguyên và siêu dữ liệu khác không được sử dụng. Điều này có nghĩa là tài nguyên sẽ bị mất và loại tệp cũng như mã người tạo sẽ không chính xác. Trên Windows, chủ sở hữu tệp, ACL và luồng dữ liệu thay thế không được sao chép.

Thao tác thư mục và tập tin

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

Sao chép nội dung của file-like object fsrc vào đối tượng giống như tệp fdst. Số nguyên length, nếu có, là kích thước bộ đệm. Cụ thể, giá trị length âm có nghĩa là sao chép dữ liệu mà không lặp lại dữ liệu nguồn theo từng đoạn; theo mặc định, dữ liệu được đọc theo từng khối để tránh việc tiêu thụ bộ nhớ không kiểm soát được. Lưu ý rằng nếu vị trí tệp hiện tại của đối tượng fsrc không bằng 0 thì chỉ nội dung từ vị trí tệp hiện tại đến cuối tệp mới được sao chép.

copyfileobj() sẽ not đảm bảo rằng luồng đích đã được xóa khi hoàn thành bản sao. Nếu bạn muốn đọc từ đích khi hoàn tất thao tác sao chép (ví dụ: đọc nội dung của tệp tạm thời đã được sao chép từ luồng HTTP), bạn phải đảm bảo rằng bạn đã gọi flush() hoặc close() trên đối tượng giống như tệp trước khi thử đọc tệp đích.

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

Sao chép nội dung (không có siêu dữ liệu) của tệp có tên src sang tệp có tên dst và trả về dst theo cách hiệu quả nhất có thể. src và dst là path-like objects hoặc tên đường dẫn được đưa ra dưới dạng chuỗi.

dst phải là tên tệp đích đầy đủ; hãy xem copy() để biết bản sao chấp nhận đường dẫn thư mục đích. Nếu src và dst chỉ định cùng một tệp, SameFileError sẽ được nâng lên.

Vị trí đích phải có thể ghi được; nếu không, ngoại lệ OSError sẽ xuất hiện. Nếu dst đã tồn tại, nó sẽ được thay thế. Không thể sao chép các tập tin đặc biệt như ký tự hoặc thiết bị khối và đường ống bằng chức năng này.

Nếu follow_symlinks sai và src là một liên kết tượng trưng, ​​một liên kết tượng trưng mới sẽ được tạo thay vì sao chép tệp src trỏ tới.

Tăng một auditing event shutil.copyfile với các đối số src, dst.

Thay đổi trong phiên bản 3.3: IOError từng được nâng lên thay vì OSError. Đã thêm đối số follow_symlinks. Bây giờ trả về dst.

Thay đổi trong phiên bản 3.4: Tăng SameFileError thay vì Error. Vì lớp trước là lớp con của lớp sau nên thay đổi này có khả năng tương thích ngược.

Thay đổi trong phiên bản 3.8: Các cuộc gọi tổng hợp sao chép nhanh dành riêng cho nền tảng có thể được sử dụng nội bộ để sao chép tệp hiệu quả hơn. Xem phần Hoạt động sao chép hiệu quả phụ thuộc vào nền tảng.

exception shutil.SpecialFileError

Ngoại lệ này được đưa ra khi copyfile() hoặc copytree() cố gắng sao chép một đường dẫn có tên.

Added in version 2.7.

exception shutil.SameFileError

Ngoại lệ này được đưa ra nếu nguồn và đích trong copyfile() là cùng một tệp.

Added in version 3.4.

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

Sao chép các bit quyền từ src sang dst. Nội dung tệp, chủ sở hữu và nhóm không bị ảnh hưởng. src và dst là path-like objects hoặc tên đường dẫn được cung cấp dưới dạng chuỗi. Nếu follow_symlinks sai và cả src và dst đều là các liên kết tượng trưng, ​​:func:copymode sẽ cố gắng sửa đổi chế độ của chính dst (chứ không phải tệp mà nó trỏ tới). Chức năng này không có sẵn trên mọi nền tảng; vui lòng xem copystat() để biết thêm thông tin. Nếu copymode() không thể sửa đổi các liên kết tượng trưng trên nền tảng cục bộ và được yêu cầu làm như vậy, nó sẽ không làm gì và quay trở lại.

Tăng một auditing event shutil.copymode với các đối số src, dst.

Thay đổi trong phiên bản 3.3: Đã thêm đối số follow_symlinks.

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

Sao chép các bit quyền, thời gian truy cập lần cuối, thời gian sửa đổi lần cuối và các cờ từ src sang dst. Trên Linux, copystat() cũng sao chép "thuộc tính mở rộng" nếu có thể. Nội dung tệp, chủ sở hữu và nhóm không bị ảnh hưởng. src và dst là path-like objects hoặc tên đường dẫn được cung cấp dưới dạng chuỗi.

Nếu follow_symlinks sai và src và dst đều đề cập đến các liên kết tượng trưng, thì copystat() sẽ hoạt động trên chính các liên kết tượng trưng thay vì các tệp mà các liên kết tượng trưng đề cập đến—đọc thông tin từ liên kết tượng trưng src và ghi thông tin vào liên kết tượng trưng dst.

Ghi chú

Không phải tất cả các nền tảng đều cung cấp khả năng kiểm tra và sửa đổi các liên kết tượng trưng. Bản thân Python có thể cho bạn biết chức năng nào có sẵn tại địa phương.

• Nếu os.chmod in os.supports_follow_symlinks là True, copystat() có thể sửa đổi các bit quyền của một liên kết tượng trưng.

• Nếu os.utime in os.supports_follow_symlinks là True, copystat() có thể sửa đổi lần truy cập và sửa đổi cuối cùng của một liên kết tượng trưng.

• Nếu os.chflags in os.supports_follow_symlinks là True, copystat() có thể sửa đổi cờ của một liên kết tượng trưng. (os.chflags không khả dụng trên tất cả các nền tảng.)

Trên các nền tảng không có một số hoặc tất cả chức năng này, khi được yêu cầu sửa đổi liên kết tượng trưng, copystat() sẽ sao chép mọi thứ có thể. copystat() không bao giờ trả về lỗi.

Vui lòng xem os.supports_follow_symlinks để biết thêm thông tin.

Tăng một auditing event shutil.copystat với các đối số src, dst.

Thay đổi trong phiên bản 3.3: Đã thêm đối số follow_symlinks và hỗ trợ cho các thuộc tính mở rộng của Linux.

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

Sao chép tệp src vào tệp hoặc thư mục dst. src và dst phải là path-like objects hoặc chuỗi. Nếu dst chỉ định một thư mục, tệp sẽ được sao chép vào dst bằng tên tệp cơ sở từ src. Nếu dst chỉ định một tệp đã tồn tại, nó sẽ được thay thế. Trả về đường dẫn tới file vừa tạo.

Nếu follow_symlinks sai và src là liên kết tượng trưng, ​​*dst* sẽ được tạo dưới dạng liên kết tượng trưng. Nếu follow_symlinks là đúng và src là một liên kết tượng trưng thì dst sẽ là bản sao của tệp mà src đề cập đến.

copy() sao chép dữ liệu tệp và chế độ cấp phép của tệp (xem os.chmod()). Siêu dữ liệu khác, như thời gian tạo và sửa đổi tệp, không được giữ nguyên. Để bảo toàn tất cả siêu dữ liệu tệp từ bản gốc, thay vào đó hãy sử dụng copy2().

Tăng một auditing event shutil.copyfile với các đối số src, dst.

Tăng một auditing event shutil.copymode với các đối số src, dst.

Thay đổi trong phiên bản 3.3: Đã thêm đối số follow_symlinks. Bây giờ trả về đường dẫn đến tệp mới tạo.

Thay đổi trong phiên bản 3.8: Các cuộc gọi tổng hợp sao chép nhanh dành riêng cho nền tảng có thể được sử dụng nội bộ để sao chép tệp hiệu quả hơn. Xem phần Hoạt động sao chép hiệu quả phụ thuộc vào nền tảng.

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

Giống hệt copy() ngoại trừ copy2() cũng cố gắng bảo toàn siêu dữ liệu của tệp.

Khi follow_symlinks sai và src là một liên kết tượng trưng, ​​:func:copy2 sẽ cố gắng sao chép tất cả siêu dữ liệu từ liên kết tượng trưng src sang liên kết tượng trưng dst mới được tạo. Tuy nhiên, chức năng này không có sẵn trên tất cả các nền tảng. Trên các nền tảng không có một số hoặc tất cả chức năng này, copy2() sẽ bảo toàn tất cả siêu dữ liệu có thể; copy2() không bao giờ đưa ra ngoại lệ vì nó không thể bảo toàn siêu dữ liệu của tệp.

copy2() sử dụng copystat() để sao chép siêu dữ liệu của tệp. Vui lòng xem copystat() để biết thêm thông tin về hỗ trợ nền tảng để sửa đổi siêu dữ liệu liên kết tượng trưng.

Tăng một auditing event shutil.copyfile với các đối số src, dst.

Tăng một auditing event shutil.copystat với các đối số src, dst.

Thay đổi trong phiên bản 3.3: Đã thêm đối số follow_symlinks, cố gắng sao chép cả các thuộc tính hệ thống tệp mở rộng (hiện chỉ có trên Linux). Bây giờ trả về đường dẫn đến tệp mới tạo.

Thay đổi trong phiên bản 3.8: Các cuộc gọi tổng hợp sao chép nhanh dành riêng cho nền tảng có thể được sử dụng nội bộ để sao chép tệp hiệu quả hơn. Xem phần Hoạt động sao chép hiệu quả phụ thuộc vào nền tảng.

shutil.ignore_patterns(*patterns)

Hàm xuất xưởng này tạo ra một hàm có thể được sử dụng làm hàm có thể gọi cho đối số ignore của copytree(), bỏ qua các tệp và thư mục khớp với một trong các patterns kiểu toàn cầu được cung cấp. Xem ví dụ dưới đây.

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

Sao chép đệ quy toàn bộ cây thư mục có gốc tại src vào thư mục có tên dst và trả về thư mục đích. Tất cả các thư mục trung gian cần thiết để chứa dst cũng sẽ được tạo theo mặc định.

Quyền và thời gian của các thư mục được sao chép bằng copystat(), các tệp riêng lẻ được sao chép bằng copy2().

Nếu symlinks là đúng, các liên kết tượng trưng trong cây nguồn sẽ được biểu diễn dưới dạng liên kết tượng trưng trong cây mới và siêu dữ liệu của các liên kết ban đầu sẽ được sao chép trong phạm vi nền tảng cho phép; nếu sai hoặc bị bỏ qua, nội dung và siêu dữ liệu của các tệp được liên kết sẽ được sao chép sang cây mới.

Khi symlinks sai, nếu tệp được trỏ đến bởi liên kết tượng trưng không tồn tại, một ngoại lệ sẽ được thêm vào danh sách các lỗi nêu ra trong ngoại lệ Error ở cuối quá trình sao chép. Bạn có thể đặt cờ ignore_dangling_symlinks tùy chọn thành true nếu bạn muốn tắt tiếng ngoại lệ này. Lưu ý rằng tùy chọn này không có tác dụng trên nền tảng không hỗ trợ os.symlink().

Nếu ignore được cung cấp, nó phải là một lệnh gọi được sẽ nhận làm đối số của thư mục đang được copytree() truy cập và danh sách nội dung của nó, được trả về bởi os.listdir(). Vì copytree() được gọi đệ quy nên ignore có thể gọi được sẽ được gọi một lần cho mỗi thư mục được sao chép. Hàm có thể gọi phải trả về một chuỗi tên thư mục và tệp liên quan đến thư mục hiện tại (tức là một tập hợp con của các mục trong đối số thứ hai của nó); những tên này sau đó sẽ bị bỏ qua trong quá trình sao chép. ignore_patterns() có thể được sử dụng để tạo ra một lệnh gọi có thể bỏ qua các tên dựa trên các mẫu kiểu toàn cầu.

Nếu (các) ngoại lệ xảy ra, Error sẽ xuất hiện cùng với danh sách các lý do.

Nếu copy_function được cung cấp, nó phải là một lệnh gọi được sẽ được sử dụng để sao chép từng tệp. Nó sẽ được gọi với đường dẫn nguồn và đường dẫn đích làm đối số. Theo mặc định, copy2() được sử dụng, nhưng bất kỳ chức năng nào hỗ trợ cùng chữ ký (như copy()) đều có thể được sử dụng.

Nếu dirs_exist_ok sai (mặc định) và dst đã tồn tại, FileExistsError sẽ được nâng lên. Nếu dirs_exist_ok là đúng, thao tác sao chép sẽ tiếp tục nếu nó gặp các thư mục hiện có và các tệp trong cây dst sẽ bị ghi đè bởi các tệp tương ứng từ cây src.

Tăng một auditing event shutil.copytree với các đối số src, dst.

Thay đổi trong phiên bản 3.2: Đã thêm đối số copy_function để có thể cung cấp chức năng sao chép tùy chỉnh. Đã thêm đối số ignore_dangling_symlinks để tắt các lỗi liên kết tượng trưng lơ lửng khi symlinks sai.

Thay đổi trong phiên bản 3.3: Sao chép siêu dữ liệu khi symlinks sai. Bây giờ trả về dst.

Thay đổi trong phiên bản 3.8: Các cuộc gọi tổng hợp sao chép nhanh dành riêng cho nền tảng có thể được sử dụng nội bộ để sao chép tệp hiệu quả hơn. Xem phần Hoạt động sao chép hiệu quả phụ thuộc vào nền tảng.

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

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

Xóa toàn bộ cây thư mục; path phải trỏ đến một thư mục (nhưng không phải là liên kết tượng trưng đến một thư mục). Nếu ignore_errors đúng, các lỗi do xóa không thành công sẽ bị bỏ qua; nếu sai hoặc bị bỏ qua, các lỗi đó sẽ được xử lý bằng cách gọi một trình xử lý được chỉ định bởi onexc hoặc onerror hoặc, nếu cả hai bị bỏ qua, các ngoại lệ sẽ được truyền tới người gọi.

Chức năng này có thể hỗ trợ paths relative to directory descriptors.

Ghi chú

Trên các nền tảng hỗ trợ các chức năng dựa trên fd cần thiết, phiên bản rmtree() chống tấn công liên kết tượng trưng được sử dụng theo mặc định. Trên các nền tảng khác, việc triển khai rmtree() dễ bị tấn công bằng liên kết tượng trưng: với thời điểm và hoàn cảnh thích hợp, kẻ tấn công có thể thao túng các liên kết tượng trưng trên hệ thống tệp để xóa các tệp mà chúng không thể truy cập được. Các ứng dụng có thể sử dụng thuộc tính hàm rmtree.avoids_symlink_attacks để xác định trường hợp nào được áp dụng.

Nếu onexc được cung cấp, nó phải là một lệnh gọi được chấp nhận ba tham số: function, path và excinfo.

Tham số đầu tiên, function, là hàm đưa ra ngoại lệ; nó phụ thuộc vào nền tảng và việc triển khai. Tham số thứ hai, path, sẽ là tên đường dẫn được truyền tới function. Tham số thứ ba, excinfo, là ngoại lệ được đưa ra. Các ngoại lệ do onexc đưa ra sẽ không bị bắt.

onerror không được dùng nữa tương tự như onexc, ngoại trừ tham số thứ ba mà nó nhận được là bộ dữ liệu được trả về từ sys.exc_info().

Xem thêm

ví dụ về rmtree để biết ví dụ về cách xử lý việc xóa cây thư mục chứa các tệp chỉ đọc.

Tăng một auditing event shutil.rmtree với các đối số path, dir_fd.

Thay đổi trong phiên bản 3.3: Đã thêm phiên bản chống tấn công liên kết tượng trưng được sử dụng tự động nếu nền tảng hỗ trợ các chức năng dựa trên fd.

Thay đổi trong phiên bản 3.8: Trên Windows, sẽ không xóa nội dung của một đường nối thư mục trước khi xóa đường nối đó nữa.

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

Thay đổi trong phiên bản 3.12: Đã thêm tham số onexc, onerror không được dùng nữa.

Thay đổi trong phiên bản 3.13: rmtree() hiện bỏ qua các ngoại lệ FileNotFoundError cho tất cả ngoại trừ đường dẫn cấp cao nhất. Các ngoại lệ khác ngoài OSError và các lớp con của OSError hiện luôn được truyền tới người gọi.

rmtree.avoids_symlink_attacks

Cho biết liệu nền tảng và cách triển khai hiện tại có cung cấp phiên bản rmtree() chống tấn công bằng liên kết tượng trưng hay không. Hiện tại điều này chỉ đúng với các nền tảng hỗ trợ chức năng truy cập thư mục dựa trên fd.

Added in version 3.3.

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

Di chuyển đệ quy một tệp hoặc thư mục (src) sang vị trí khác và trả về đích.

Nếu dst là một thư mục hiện có hoặc một liên kết tượng trưng đến một thư mục thì src sẽ được di chuyển vào bên trong thư mục đó. Đường dẫn đích trong thư mục đó không được tồn tại.

Nếu dst đã tồn tại nhưng không phải là một thư mục, nó có thể bị ghi đè tùy thuộc vào ngữ nghĩa của os.rename().

Nếu đích nằm trên hệ thống tệp hiện tại thì os.rename() sẽ được sử dụng. Nếu không, src sẽ được sao chép đến đích bằng copy_function rồi bị xóa. Trong trường hợp liên kết tượng trưng, ​​​​một liên kết tượng trưng mới trỏ đến mục tiêu của src sẽ được tạo làm đích và src sẽ bị xóa.

Nếu copy_function được cung cấp, nó phải là một lệnh gọi có hai đối số, src và đích, đồng thời sẽ được sử dụng để sao chép src đến đích nếu không thể sử dụng os.rename(). Nếu nguồn là một thư mục, copytree() sẽ được gọi, chuyển cho nó copy_function. Zz008zz mặc định là copy2(). Việc sử dụng copy() làm copy_function cho phép di chuyển thành công khi không thể sao chép siêu dữ liệu, với chi phí là không sao chép bất kỳ siêu dữ liệu nào.

Tăng một auditing event shutil.move với các đối số src, dst.

Thay đổi trong phiên bản 3.3: Đã thêm xử lý liên kết tượng trưng rõ ràng cho các hệ thống tệp nước ngoài, do đó điều chỉnh nó cho phù hợp với hoạt động của mv của GNU. Bây giờ trả về dst.

Thay đổi trong phiên bản 3.5: Đã thêm đối số từ khóa copy_function.

Thay đổi trong phiên bản 3.8: Các cuộc gọi tổng hợp sao chép nhanh dành riêng cho nền tảng có thể được sử dụng nội bộ để sao chép tệp hiệu quả hơn. Xem phần Hoạt động sao chép hiệu quả phụ thuộc vào nền tảng.

Thay đổi trong phiên bản 3.9: Chấp nhận path-like object cho cả src và dst.

shutil.disk_usage(path)

Trả về số liệu thống kê mức sử dụng đĩa về đường dẫn đã cho dưới dạng named tuple với các thuộc tính total, used và free, là tổng dung lượng đã sử dụng và dung lượng trống tính bằng byte. path có thể là một tập tin hoặc một thư mục.

Ghi chú

Trên hệ thống tệp Unix, path phải trỏ đến một đường dẫn trong phân vùng hệ thống tệp mounted. Trên các nền tảng đó, CPython không cố truy xuất thông tin sử dụng ổ đĩa từ các hệ thống tệp không được gắn kết.

Added in version 3.3.

Thay đổi trong phiên bản 3.8: Trên Windows, path hiện có thể là một tệp hoặc thư mục.

sẵn có: Unix, Windows.

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

Thay đổi chủ sở hữu user và/hoặc group của path đã cho.

user có thể là tên người dùng hệ thống hoặc uid; điều tương tự cũng áp dụng cho group. Cần có ít nhất một đối số.

Xem thêm os.chown(), hàm cơ bản.

Tăng một auditing event shutil.chown với các đối số path, user, group.

sẵn có: Unix.

Added in version 3.3.

Thay đổi trong phiên bản 3.13: Đã thêm thông số dir_fd và follow_symlinks.

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

Trả lại đường dẫn đến tệp thực thi sẽ được chạy nếu cmd đã cho được gọi. Nếu không có cmd nào được gọi, hãy trả về None.

mode là mặt nạ cấp phép được chuyển tới os.access(), theo mặc định xác định xem tệp có tồn tại và có thể thực thi được hay không.

path là một "chuỗi PATH" chỉ định các thư mục cần tìm, được phân cách bằng os.pathsep. Khi không chỉ định path, biến môi trường PATH được đọc từ os.environ, quay trở lại os.defpath nếu nó không được đặt.

Nếu cmd chứa thành phần thư mục, which() chỉ kiểm tra trực tiếp đường dẫn được chỉ định và không tìm kiếm các thư mục được liệt kê trong path hoặc trong biến môi trường PATH của hệ thống.

Trên Windows, thư mục hiện tại được thêm vào trước path nếu mode không bao gồm os.X_OK. Khi mode bao gồm os.X_OK, Windows API NeedCurrentDirectoryForExePathW sẽ được tham khảo để xác định xem thư mục hiện tại có nên được thêm vào trước path hay không. Để tránh phải tham khảo thư mục làm việc hiện tại để tìm các tệp thực thi: hãy đặt biến môi trường NoDefaultCurrentDirectoryInExePath.

Ngoài ra trên Windows, biến môi trường PATHEXT được sử dụng để giải quyết các lệnh có thể chưa bao gồm phần mở rộng. Ví dụ: nếu bạn gọi shutil.which("python"), which() sẽ tìm kiếm PATHEXT để biết rằng nó sẽ tìm python.exe trong thư mục path. Ví dụ: trên Windows:

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

Điều này cũng được áp dụng khi cmd là đường dẫn chứa thành phần thư mục

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

Added in version 3.3.

Thay đổi trong phiên bản 3.8: Loại bytes hiện được chấp nhận. Nếu loại cmd là bytes thì loại kết quả cũng là bytes.

Thay đổi trong phiên bản 3.12: Trên Windows, thư mục hiện tại không còn được thêm vào trước đường dẫn tìm kiếm nếu mode bao gồm os.X_OK và WinAPI NeedCurrentDirectoryForExePathW(cmd) là sai, nếu không thì thư mục hiện tại sẽ được thêm vào trước ngay cả khi nó đã có trong đường dẫn tìm kiếm; PATHEXT hiện được sử dụng ngay cả khi cmd bao gồm một thành phần thư mục hoặc kết thúc bằng phần mở rộng trong PATHEXT; và bây giờ có thể tìm thấy tên tệp không có phần mở rộng.

exception shutil.Error

Ngoại lệ này thu thập các ngoại lệ được nêu ra trong quá trình thực hiện nhiều tệp. Đối với copytree(), đối số ngoại lệ là danh sách 3 bộ dữ liệu (srcname, dstname, exception).

Hoạt động sao chép hiệu quả phụ thuộc vào nền tảng

Bắt đầu từ Python 3.8, tất cả các hàm liên quan đến sao chép tệp (copyfile(), copy(), copy2(), copytree() và move()) có thể sử dụng các lệnh gọi tổng hợp "sao chép nhanh" dành riêng cho nền tảng để sao chép tệp hiệu quả hơn (xem bpo-33671). "sao chép nhanh" có nghĩa là hoạt động sao chép xảy ra trong kernel, tránh việc sử dụng vùng đệm vùng người dùng trong Python như trong "outfd.write(infd.read())".

Trên macOS fcopyfile được dùng để sao chép nội dung file (không phải siêu dữ liệu).

Trên Linux os.copy_file_range() hoặc os.sendfile() được sử dụng.

Trên Solaris os.sendfile() được sử dụng.

Trên Windows shutil.copyfile() sử dụng kích thước bộ đệm mặc định lớn hơn (1 MiB thay vì 64 KiB) và sử dụng biến thể shutil.copyfileobj() dựa trên memoryview().

Nếu thao tác sao chép nhanh không thành công và không có dữ liệu nào được ghi vào tệp đích thì Shutil sẽ âm thầm quay trở lại chức năng copyfileobj() kém hiệu quả hơn trong nội bộ.

Thay đổi trong phiên bản 3.8.

Thay đổi trong phiên bản 3.14: Solaris hiện sử dụng os.sendfile().

Thay đổi trong phiên bản 3.14: Sao chép khi ghi hoặc sao chép phía máy chủ có thể được sử dụng nội bộ thông qua os.copy_file_range() trên các hệ thống tệp Linux được hỗ trợ.

ví dụ về cây sao chép

Một ví dụ sử dụng trình trợ giúp ignore_patterns()

từ bản sao nhập khẩu của Shutil, ign_patterns

copytree(nguồn, đích, bỏ qua=ignore_patterns('*.pyc', 'tmp*'))

Thao tác này sẽ sao chép mọi thứ ngoại trừ tệp .pyc và tệp hoặc thư mục có tên bắt đầu bằng tmp.

Một ví dụ khác sử dụng đối số ignore để thêm lệnh gọi ghi nhật ký:

từ bản sao nhập khẩu của Shutil
nhập nhật ký

def _logpath(đường dẫn, tên):
    logging.info('Đang làm việc ở %s', path)
    return [] # nothing sẽ bị bỏ qua

copytree(nguồn, đích, bỏ qua=_logpath)

ví dụ về rmtree

Ví dụ này cho thấy cách xóa cây thư mục trên Windows trong đó một số tệp có tập bit chỉ đọc. Nó sử dụng lệnh gọi lại onexc để xóa bit chỉ đọc và thử xóa lại. Bất kỳ thất bại tiếp theo sẽ lan truyền.

nhập hệ điều hành, thống kê
nhập khẩu

def Remove_readonly(func, đường dẫn, _):
    "Xóa bit chỉ đọc và thử xóa lại"
    os.chmod(đường dẫn, stat.S_IWRITE)
    func(đường dẫn)

Shutil.rmtree(thư mục, onexc=remove_readonly)

Hoạt động lưu trữ

Added in version 3.2.

Thay đổi trong phiên bản 3.5: Đã thêm hỗ trợ cho định dạng xztar.

Các tiện ích cấp cao để tạo và đọc các tệp nén và lưu trữ cũng được cung cấp. Họ dựa vào các mô-đun zipfile và tarfile.

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

Tạo một tệp lưu trữ (chẳng hạn như zip hoặc tar) và trả về tên của nó.

base_name là tên của tệp cần tạo, bao gồm đường dẫn, trừ mọi phần mở rộng dành riêng cho định dạng.

format là định dạng lưu trữ: một trong các "zip" (nếu có mô-đun zlib), "tar", "gztar" (nếu có mô-đun zlib), "bztar" (nếu có mô-đun bz2), "xztar" (nếu có mô-đun lzma) hoặc "zstdtar" (nếu có mô-đun compression.zstd).

root_dir là thư mục sẽ là thư mục gốc của kho lưu trữ, tất cả các đường dẫn trong kho lưu trữ sẽ liên quan đến nó; ví dụ: chúng tôi thường chdir vào root_dir trước khi tạo kho lưu trữ.

base_dir là thư mục nơi chúng tôi bắt đầu lưu trữ; tức là base_dir sẽ là tiền tố chung của tất cả các tệp và thư mục trong kho lưu trữ. base_dir phải được đưa ra tương ứng với root_dir. Xem Lưu trữ ví dụ với base_dir để biết cách sử dụng base_dir và root_dir cùng nhau.

root_dir và base_dir đều mặc định là thư mục hiện tại.

Nếu dry_run là đúng thì không có kho lưu trữ nào được tạo nhưng các thao tác sẽ được thực thi sẽ được ghi vào logger.

owner và group được sử dụng khi tạo kho lưu trữ tar. Theo mặc định, sử dụng chủ sở hữu và nhóm hiện tại.

logger phải là một đối tượng tương thích với PEP 282, thường là một phiên bản của logging.Logger.

Đối số verbose không được sử dụng và không được dùng nữa.

Tăng một auditing event shutil.make_archive với các đối số base_name, format, root_dir, base_dir.

Ghi chú

Chức năng này không an toàn cho luồng khi các trình lưu trữ tùy chỉnh được đăng ký với register_archive_format() không hỗ trợ đối số root_dir. Trong trường hợp này, nó tạm thời thay đổi thư mục làm việc hiện tại của tiến trình thành root_dir để thực hiện lưu trữ.

Thay đổi trong phiên bản 3.8: Định dạng pax hiện đại (POSIX.1-2001) hiện được sử dụng thay cho định dạng GNU cũ cho các kho lưu trữ được tạo bằng format="tar".

Thay đổi trong phiên bản 3.10.6: Chức năng này hiện được đảm bảo an toàn cho luồng trong quá trình tạo kho lưu trữ .zip và tar tiêu chuẩn.

shutil.get_archive_formats()

Trả về danh sách các định dạng được hỗ trợ để lưu trữ. Mỗi phần tử của chuỗi trả về là một bộ (name, description).

Theo mặc định shutil cung cấp các định dạng sau:

• zip: tệp ZIP (nếu có mô-đun zlib).

• tar: Tệp tar không nén. Sử dụng định dạng POSIX.1-2001 pax cho các kho lưu trữ mới.

• gztar: gzip'ed tar-file (nếu có mô-đun zlib).

• bztar: bzip2'ed tar-file (nếu có mô-đun bz2).

• xztar: xz'ed tar-file (nếu có mô-đun lzma).

• zstdtar: Tệp tar nén tiêu chuẩn Z (nếu có mô-đun compression.zstd).

Bạn có thể đăng ký các định dạng mới hoặc cung cấp trình lưu trữ của riêng mình cho mọi định dạng hiện có bằng cách sử dụng register_archive_format().

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

Đăng ký một kho lưu trữ cho định dạng name.

function là lệnh gọi sẽ được sử dụng để giải nén các kho lưu trữ. Người có thể gọi sẽ nhận được base_name của tệp cần tạo, theo sau là base_dir (mặc định là os.curdir) để bắt đầu lưu trữ từ đó. Các đối số tiếp theo được chuyển dưới dạng đối số từ khóa: owner, group, dry_run và logger (như được truyền trong make_archive()).

Nếu function có thuộc tính tùy chỉnh function.supports_root_dir được đặt thành True thì đối số root_dir sẽ được chuyển dưới dạng đối số từ khóa. Nếu không, thư mục làm việc hiện tại của tiến trình sẽ tạm thời được thay đổi thành root_dir trước khi gọi function. Trong trường hợp này, make_archive() không an toàn cho luồng.

Nếu được cung cấp, extra_args là một chuỗi các cặp (name, value) sẽ được sử dụng làm đối số từ khóa bổ sung khi sử dụng trình lưu trữ có thể gọi được.

description được get_archive_formats() sử dụng để trả về danh sách người lưu trữ. Mặc định là một chuỗi trống.

Thay đổi trong phiên bản 3.12: Đã thêm hỗ trợ cho các hàm hỗ trợ đối số root_dir.

shutil.unregister_archive_format(name)

Xóa định dạng lưu trữ name khỏi danh sách các định dạng được hỗ trợ.

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

Giải nén một kho lưu trữ. filename là đường dẫn đầy đủ của kho lưu trữ.

extract_dir là tên của thư mục đích nơi kho lưu trữ được giải nén. Nếu không được cung cấp, thư mục làm việc hiện tại sẽ được sử dụng.

format là định dạng lưu trữ: một trong các "zip", "tar", "gztar", "bztar", "xztar" hoặc "zstdtar". Hoặc bất kỳ định dạng nào khác được đăng ký với register_unpack_format(). Nếu không được cung cấp, unpack_archive() sẽ sử dụng phần mở rộng tên tệp lưu trữ và xem liệu trình giải nén đã được đăng ký cho phần mở rộng đó hay chưa. Trong trường hợp không tìm thấy, ValueError sẽ được nâng lên.

Đối số filter chỉ có từ khóa được chuyển đến hàm giải nén cơ bản. Đối với file zip, filter không được chấp nhận. Đối với các tệp tar, bạn nên sử dụng 'data' (mặc định kể từ Python 3.14), trừ khi sử dụng các tính năng dành riêng cho hệ thống tệp giống tar và UNIX. (Xem Bộ lọc trích xuất để biết chi tiết.)

Tăng một auditing event shutil.unpack_archive với các đối số filename, extract_dir, format.

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. Có thể các tệp được tạo bên ngoài đường dẫn được chỉ định trong đối số extract_dir, ví dụ: thành viên có tên tệp tuyệt đối bắt đầu bằng "/" hoặc tên tệp có hai dấu chấm "..".

Kể từ Python 3.14, mặc định cho cả hai định dạng tích hợp (tệp zip và tar) sẽ ngăn chặn những vấn đề bảo mật nguy hiểm nhất như vậy, nhưng sẽ không ngăn được hành vi ngoài ý muốn của all. Đọc phần Gợi ý xác minh thêm để biết chi tiết cụ thể về tar.

Thay đổi trong phiên bản 3.7: Chấp nhận path-like object cho filename và extract_dir.

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

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

Đăng ký một định dạng giải nén. name là tên của định dạng và extensions là danh sách các phần mở rộng tương ứng với định dạng, như .zip cho file Zip.

function là lệnh gọi sẽ được sử dụng để giải nén các kho lưu trữ. Người có thể gọi sẽ nhận được:

• đường dẫn của kho lưu trữ, như một đối số vị trí;

• thư mục mà kho lưu trữ phải được trích xuất vào, làm đối số vị trí;

• có thể là một đối số từ khóa filter, nếu nó được trao cho unpack_archive();

• đối số từ khóa bổ sung, được chỉ định bởi extra_args dưới dạng một chuỗi các bộ dữ liệu (name, value).

description có thể được cung cấp để mô tả định dạng và sẽ được hàm get_unpack_formats() trả về.

shutil.unregister_unpack_format(name)

Hủy đăng ký một định dạng giải nén. name là tên của định dạng.

shutil.get_unpack_formats()

Trả về danh sách tất cả các định dạng đã đăng ký để giải nén. Mỗi phần tử của chuỗi trả về là một bộ (name, extensions, description).

Theo mặc định shutil cung cấp các định dạng sau:

• zip: file ZIP (giải nén file nén chỉ hoạt động nếu có sẵn mô-đun tương ứng).

• tar: tập tin tar không nén.

• gztar: gzip'ed tar-file (nếu có mô-đun zlib).

• bztar: bzip2'ed tar-file (nếu có mô-đun bz2).

• xztar: xz'ed tar-file (nếu có mô-đun lzma).

• zstdtar: Tệp tar nén tiêu chuẩn Z (nếu có mô-đun compression.zstd).

Bạn có thể đăng ký các định dạng mới hoặc cung cấp trình giải nén của riêng mình cho mọi định dạng hiện có bằng cách sử dụng register_unpack_format().

Ví dụ lưu trữ

Trong ví dụ này, chúng tôi tạo một kho lưu trữ tệp tar được gzip chứa tất cả các tệp được tìm thấy trong thư mục .ssh của người dùng:

>>> từ lệnh nhập khẩu im lặng make_archive
>>> nhập hệ điều hành
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(tên_lưu trữ, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'

Kho lưu trữ kết quả chứa:

$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/nhân viên 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/nhân viên 65 2008-06-09 13:26:54 ./config
-rwx------ tarek/nhân viên 668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/nhân viên 609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/nhân viên 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

Lưu trữ ví dụ với base_dir

Trong ví dụ này, tương tự như one above, chúng tôi trình bày cách sử dụng make_archive(), nhưng lần này sử dụng base_dir. Bây giờ chúng ta có cấu trúc thư mục sau:

$ cây tmp
tmp
└── gốc
    └── cấu trúc
        ├── nội dung
            └── xin vui lòng_add.txt
        └── do_not_add.txt

Trong kho lưu trữ cuối cùng, please_add.txt nên được đưa vào, nhưng do_not_add.txt thì không. Vì vậy chúng tôi sử dụng như sau:

>>> từ lệnh nhập khẩu im lặng make_archive
>>> nhập hệ điều hành
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
... archive_name,
... 'tar',
... root_dir='tmp/root',
... base_dir='cấu trúc/nội dung',
... )
'/Users/tarek/myarchive.tar'

Việc liệt kê các tệp trong kho lưu trữ kết quả cho chúng ta:

$ python -m tarfile -l /Users/tarek/myarchive.tar
cấu trúc/nội dung/
cấu trúc/nội dung/please_add.txt

Truy vấn kích thước của thiết bị đầu cuối đầu ra

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

Lấy kích thước của cửa sổ terminal.

Đối với mỗi chiều trong số hai chiều, biến môi trường lần lượt là COLUMNS và LINES được chọn. Nếu biến được xác định và giá trị là số nguyên dương thì nó sẽ được sử dụng.

Khi COLUMNS hoặc LINES không được xác định, đây là trường hợp phổ biến, thiết bị đầu cuối được kết nối với sys.__stdout__ sẽ được truy vấn bằng cách gọi os.get_terminal_size().

Nếu kích thước thiết bị đầu cuối không thể được truy vấn thành công, do hệ thống không hỗ trợ truy vấn hoặc do chúng tôi không kết nối với thiết bị đầu cuối, thì giá trị được cung cấp trong tham số fallback sẽ được sử dụng. fallback mặc định là (80, 24), đây là kích thước mặc định được nhiều trình mô phỏng thiết bị đầu cuối sử dụng.

Giá trị được trả về là một bộ có tên thuộc loại os.terminal_size.

Xem thêm: Thông số kỹ thuật UNIX đơn, Phiên bản 2, Other Environment Variables.

Added in version 3.3.

Thay đổi trong phiên bản 3.11: Các giá trị fallback cũng được sử dụng nếu os.get_terminal_size() trả về số 0.