importlib.resources -- Đọc, mở và truy cập tài nguyên gói

Source code: Lib/importlib/resources/__init__.py

---

Added in version 3.7.

Mô-đun này tận dụng hệ thống nhập của Python để cung cấp quyền truy cập vào resources trong packages.

"Tài nguyên" là các tài nguyên dạng tệp được liên kết với một mô-đun hoặc gói trong Python. Các tài nguyên có thể được chứa trực tiếp trong một gói, trong thư mục con có trong gói đó hoặc liền kề với các mô-đun bên ngoài gói. Tài nguyên có thể là văn bản hoặc nhị phân. Do đó, các nguồn mô-đun Python (.py), các tạo phẩm biên dịch (pycache) và các tạo phẩm cài đặt của gói (như reserved filenames trong thư mục) là các tài nguyên thực tế về mặt kỹ thuật của gói đó. Tuy nhiên, trong thực tế, tài nguyên chủ yếu là những tạo phẩm không phải Python được tác giả gói cung cấp cụ thể.

Tài nguyên có thể được mở hoặc đọc ở chế độ nhị phân hoặc văn bản.

Tài nguyên gần giống với các tệp trong thư mục, mặc dù điều quan trọng cần lưu ý là đây chỉ là một phép ẩn dụ. Tài nguyên và gói do not phải tồn tại dưới dạng tệp và thư mục vật lý trên hệ thống tệp: ví dụ: một gói và tài nguyên của nó có thể được nhập từ tệp zip bằng zipimport.

Cảnh báo

importlib.resources tuân theo mô hình bảo mật tương tự như chức năng open() tích hợp. Việc truyền các đầu vào không đáng tin cậy tới các chức năng trong mô-đun này là không an toàn.

Ghi chú

Mô-đun này cung cấp chức năng tương tự như pkg_resources Basic Resource Access mà không cần nâng cao hiệu năng của gói đó. Điều này làm cho việc đọc các tài nguyên có trong gói trở nên dễ dàng hơn, với ngữ nghĩa ổn định và nhất quán hơn.

Cổng sau độc lập của mô-đun này cung cấp thêm thông tin về using importlib.resources và migrating from pkg_resources to importlib.resources.

Loaders muốn hỗ trợ đọc tài nguyên phải triển khai phương thức get_resource_reader(fullname) như được chỉ định bởi importlib.resources.abc.ResourceReader.

class importlib.resources.Anchor

Đại diện cho một điểm neo cho các tài nguyên, module object hoặc tên mô-đun dưới dạng chuỗi. Được xác định là Union[str, ModuleType].

importlib.resources.files(anchor: Anchor | None = None)

Trả về một đối tượng Traversable đại diện cho vùng chứa tài nguyên (thư mục think) và các tài nguyên của nó (tệp think). Một Traversable có thể chứa các vùng chứa khác (ví dụ như các thư mục con).

anchor là Anchor tùy chọn. Nếu mỏ neo là một gói thì tài nguyên sẽ được phân giải từ gói đó. Nếu là một mô-đun, tài nguyên được phân giải liền kề với mô-đun đó (trong cùng một gói hoặc gói gốc). Nếu neo bị bỏ qua, mô-đun của người gọi sẽ được sử dụng.

Added in version 3.9.

Thay đổi trong phiên bản 3.12: Tham số package được đổi tên thành anchor. anchor hiện có thể là một mô-đun không phải gói và nếu bị bỏ qua sẽ mặc định là mô-đun của người gọi. package vẫn được chấp nhận về khả năng tương thích nhưng sẽ tăng DeprecationWarning. Hãy cân nhắc việc chuyển neo theo vị trí hoặc sử dụng importlib_resources >= 5.10 để có giao diện tương thích trên các Python cũ hơn.

importlib.resources.as_file(traversable)

Cho một đối tượng Traversable đại diện cho một tệp hoặc thư mục, thường là từ importlib.resources.files(), trả về một trình quản lý bối cảnh để sử dụng trong câu lệnh with. Trình quản lý bối cảnh cung cấp đối tượng pathlib.Path.

Việc thoát khỏi trình quản lý bối cảnh sẽ dọn sạch mọi tệp hoặc thư mục tạm thời được tạo khi tài nguyên được trích xuất từ ​​ví dụ:. một tập tin zip.

Sử dụng as_file khi các phương thức Traversable (read_text, v.v.) không đủ và cần có tệp hoặc thư mục thực tế trên hệ thống tệp.

Added in version 3.9.

Thay đổi trong phiên bản 3.12: Đã thêm hỗ trợ cho traversable đại diện cho một thư mục.

Chức năng API

Có sẵn một bộ trợ giúp đơn giản, tương thích ngược. Chúng cho phép các hoạt động phổ biến trong một cuộc gọi chức năng duy nhất.

Đối với tất cả các chức năng sau:

• anchor là Anchor, như trong files(). Không giống như trong files, nó có thể không bị bỏ qua.

• path_names là các thành phần của tên đường dẫn của tài nguyên, liên quan đến neo. Ví dụ: để lấy văn bản của tài nguyên có tên info.txt, hãy sử dụng:

  importlib.resources.read_text(my_module, "info.txt")
  

  Giống như Traversable.joinpath, Các thành phần riêng lẻ nên sử dụng dấu gạch chéo lên (/) làm dấu phân cách đường dẫn. Ví dụ: những điều sau đây là tương đương:

  importlib.resources.read_binary(my_module, "pics/painting.png")
  importlib.resources.read_binary(my_module, "pics", "painting.png")
  

  Vì lý do tương thích ngược, các hàm đọc văn bản yêu cầu đối số encoding rõ ràng nếu có nhiều path_names. Ví dụ: để lấy văn bản của info/chapter1.txt, hãy sử dụng:

  importlib.resources.read_text(my_module, "thông tin", "chapter1.txt",
                                mã hóa='utf-8')
  

importlib.resources.open_binary(anchor, *path_names)

Mở tài nguyên được đặt tên để đọc nhị phân.

Xem the introduction để biết chi tiết về anchor và path_names.

Hàm này trả về một đối tượng BinaryIO, tức là một luồng nhị phân mở để đọc.

Chức năng này gần tương đương với:

file(anchor).joinpath(*path_names).open('rb')

Thay đổi trong phiên bản 3.13: Nhiều path_names được chấp nhận.

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

Mở tài nguyên được đặt tên để đọc văn bản. Theo mặc định, nội dung được đọc là UTF-8 nghiêm ngặt.

Xem the introduction để biết chi tiết về anchor và path_names. encoding và errors có ý nghĩa tương tự như trong open() tích hợp.

Vì lý do tương thích ngược, đối số encoding phải được cung cấp rõ ràng nếu có nhiều path_names. Giới hạn này dự kiến ​​sẽ được loại bỏ trong Python 3.15.

Hàm này trả về một đối tượng TextIO, tức là một luồng văn bản mở để đọc.

Chức năng này gần tương đương với:

files(anchor).joinpath(*path_names).open('r',coding=encoding)

Thay đổi trong phiên bản 3.13: Nhiều path_names được chấp nhận. encoding và errors phải được đưa ra làm đối số từ khóa.

importlib.resources.read_binary(anchor, *path_names)

Đọc và trả về nội dung của tài nguyên được đặt tên là bytes.

Xem the introduction để biết chi tiết về anchor và path_names.

Chức năng này gần tương đương với:

tập tin (anchor).joinpath(*path_names).read_bytes()

Thay đổi trong phiên bản 3.13: Nhiều path_names được chấp nhận.

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

Đọc và trả về nội dung của tài nguyên được đặt tên là str. Theo mặc định, nội dung được đọc là UTF-8 nghiêm ngặt.

Xem the introduction để biết chi tiết về anchor và path_names. encoding và errors có ý nghĩa tương tự như trong open() tích hợp.

Vì lý do tương thích ngược, đối số encoding phải được cung cấp rõ ràng nếu có nhiều path_names. Giới hạn này dự kiến ​​sẽ được loại bỏ trong Python 3.15.

Chức năng này gần tương đương với:

tập tin(anchor).joinpath(*path_names).read_text(encoding=encoding)

Thay đổi trong phiên bản 3.13: Nhiều path_names được chấp nhận. encoding và errors phải được đưa ra làm đối số từ khóa.

importlib.resources.path(anchor, *path_names)

Cung cấp đường dẫn đến resource dưới dạng đường dẫn hệ thống tệp thực tế. Hàm này trả về một trình quản lý bối cảnh để sử dụng trong câu lệnh with. Trình quản lý bối cảnh cung cấp đối tượng pathlib.Path.

Việc thoát trình quản lý bối cảnh sẽ xóa mọi tệp tạm thời được tạo, ví dụ: khi tài nguyên cần được trích xuất từ ​​tệp zip.

Ví dụ: phương thức stat() yêu cầu đường dẫn hệ thống tệp thực tế; nó có thể được sử dụng như thế này:

với importlib.resources.path(anchor, "resource.txt") là fspath:
    kết quả = fspath.stat()

Xem the introduction để biết chi tiết về anchor và path_names.

Chức năng này gần tương đương với:

as_file(files(anchor).joinpath(*path_names))

Thay đổi trong phiên bản 3.13: Nhiều path_names được chấp nhận. encoding và errors phải được đưa ra làm đối số từ khóa.

importlib.resources.is_resource(anchor, *path_names)

Trả về True nếu tài nguyên được đặt tên tồn tại, nếu không thì trả về False. Hàm này không coi thư mục là tài nguyên.

Xem the introduction để biết chi tiết về anchor và path_names.

Chức năng này gần tương đương với:

tập tin (anchor).joinpath(*path_names).is_file()

Thay đổi trong phiên bản 3.13: Nhiều path_names được chấp nhận.

importlib.resources.contents(anchor, *path_names)

Trả về một lần lặp qua các mục được đặt tên trong gói hoặc đường dẫn. Iterable trả về tên của tài nguyên (ví dụ: tệp) và không phải tài nguyên (ví dụ: thư mục) dưới dạng str. Việc lặp lại không lặp lại vào các thư mục con.

Xem the introduction để biết chi tiết về anchor và path_names.

Chức năng này gần tương đương với:

lấy tài nguyên trong tệp (anchor).joinpath(*path_names).iterdir():
    mang lại tài nguyên.name

Sắp loại bỏ từ phiên bản 3.11: Ưu tiên iterdir() như trên, nó cung cấp nhiều quyền kiểm soát kết quả hơn và chức năng phong phú hơn.