`pkgutil` --- Tiện ích mở rộng gói¶

Mô-đun này cung cấp các tiện ích cho hệ thống nhập, đặc biệt là hỗ trợ gói.

class pkgutil.ModuleInfo(module_finder, name, ispkg)¶: Một bộ có tên chứa bản tóm tắt ngắn gọn về thông tin của mô-đun.

Added in version 3.6.

pkgutil.extend_path(path, name)¶

Mở rộng đường dẫn tìm kiếm cho các mô-đun bao gồm một gói. Mục đích sử dụng là đặt đoạn mã sau vào __init__.py:

từ pkgutil nhập Extend_path
__path__ = mở rộng_path(__path__, __name__)

Đối với mỗi thư mục trên sys.path có thư mục con khớp với tên gói, hãy thêm thư mục con đó vào __path__ của gói. Điều này rất hữu ích nếu người ta muốn phân phối các phần khác nhau của một gói logic duy nhất dưới dạng nhiều thư mục.

Nó cũng tìm kiếm các tệp *.pkg bắt đầu trong đó * khớp với đối số name. Tính năng này tương tự như các tệp *.pth (xem mô-đun site để biết thêm thông tin), ngoại trừ việc nó không có các dòng chữ đặc biệt bắt đầu bằng import. Tệp *.pkg được tin cậy theo mệnh giá: ngoài việc bỏ qua các dòng trống và bỏ qua nhận xét, tất cả các mục được tìm thấy trong tệp *.pkg đều được thêm vào đường dẫn, bất kể chúng có tồn tại trên hệ thống tệp hay không (đây là một tính năng).

Nếu đường dẫn đầu vào không phải là một danh sách (như trường hợp các gói bị đóng băng), nó sẽ được trả về không thay đổi. Đường dẫn đầu vào không được sửa đổi; một bản sao mở rộng được trả lại. Các mục chỉ được thêm vào bản sao ở cuối.

Người ta cho rằng sys.path là một dãy. Các mục của sys.path không phải là chuỗi tham chiếu đến các thư mục hiện có sẽ bị bỏ qua. Các mục Unicode trên sys.path gây ra lỗi khi sử dụng làm tên tệp có thể khiến hàm này đưa ra một ngoại lệ (phù hợp với hành vi của os.path.isdir()).

pkgutil.get_importer(path_item)¶

Truy xuất finder cho path_item đã cho.

Công cụ tìm được trả về sẽ được lưu vào bộ nhớ đệm trong sys.path_importer_cache nếu nó mới được tạo bằng hook hook.

Bộ nhớ đệm (hoặc một phần của nó) có thể được xóa thủ công nếu cần quét lại sys.path_hooks.

Thay đổi trong phiên bản 3.3: Đã cập nhật để dựa trực tiếp vào importlib thay vì dựa vào mô phỏng nhập PEP 302 nội bộ của gói.

pkgutil.iter_importers(fullname='')¶

Mang lại các đối tượng finder cho tên mô-đun đã cho.

Nếu fullname chứa '.', các công cụ tìm kiếm sẽ dành cho gói chứa fullname, nếu không chúng sẽ là tất cả các công cụ tìm kiếm cấp cao nhất đã được đăng ký (tức là các công cụ tìm kiếm trên cả sys.meta_path và sys.path_hooks).

Nếu mô-đun được đặt tên nằm trong một gói thì gói đó sẽ được nhập dưới dạng tác dụng phụ của việc gọi hàm này.

Nếu không có tên mô-đun nào được chỉ định thì tất cả các công cụ tìm cấp cao nhất sẽ được tạo.

Thay đổi trong phiên bản 3.3: Đã cập nhật để dựa trực tiếp vào importlib thay vì dựa vào mô phỏng nhập PEP 302 nội bộ của gói.

pkgutil.iter_modules(path=None, prefix='')¶

Mang lại ModuleInfo cho tất cả các mô-đun con trên path hoặc nếu path là None, thì tất cả các mô-đun cấp cao nhất trên sys.path.

path phải là None hoặc danh sách các đường dẫn để tìm kiếm các mô-đun.

prefix là một chuỗi xuất hiện ở mặt trước của mỗi tên mô-đun trên đầu ra.

Ghi chú

Chỉ hoạt động đối với finder xác định phương thức iter_modules(). Giao diện này không chuẩn nên mô-đun này cũng cung cấp các triển khai cho importlib.machinery.FileFinder và zipimport.zipimporter.

Thay đổi trong phiên bản 3.3: Đã cập nhật để dựa trực tiếp vào importlib thay vì dựa vào mô phỏng nhập PEP 302 nội bộ của gói.

pkgutil.walk_packages(path=None, prefix='', onerror=None)¶

Mang lại ModuleInfo cho tất cả các mô-đun theo cách đệ quy trên path hoặc, nếu path là None, tất cả các mô-đun có thể truy cập được.

path phải là None hoặc danh sách các đường dẫn để tìm kiếm các mô-đun.

prefix là một chuỗi xuất hiện ở mặt trước của mỗi tên mô-đun trên đầu ra.

Lưu ý rằng hàm này phải nhập tất cả packages (not tất cả các mô-đun!) trên path đã cho, để truy cập thuộc tính __path__ để tìm các mô-đun con.

onerror là một hàm được gọi với một đối số (tên của gói đang được nhập) nếu có bất kỳ ngoại lệ nào xảy ra trong khi cố gắng nhập gói. Nếu không có chức năng onerror nào được cung cấp, ImportErrors sẽ bị bắt và bỏ qua, trong khi tất cả các ngoại lệ khác sẽ được truyền đi, kết thúc tìm kiếm.

Ví dụ:

# list tất cả các mô-đun python có thể truy cập
walk_packages()

# list tất cả các mô-đun con của ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

Ghi chú

Chỉ hoạt động đối với finder xác định phương thức iter_modules(). Giao diện này không chuẩn nên mô-đun này cũng cung cấp các triển khai cho importlib.machinery.FileFinder và zipimport.zipimporter.

Thay đổi trong phiên bản 3.3: Đã cập nhật để dựa trực tiếp vào importlib thay vì dựa vào mô phỏng nhập PEP 302 nội bộ của gói.

pkgutil.get_data(package, resource)¶

Nhận tài nguyên từ một gói.

Đây là một trình bao bọc cho loader get_data API. Đối số package phải là tên của gói, ở định dạng mô-đun tiêu chuẩn (foo.bar). Đối số resource phải ở dạng tên tệp tương đối, sử dụng / làm dấu phân cách đường dẫn.

Hàm trả về một chuỗi nhị phân là nội dung của tài nguyên đã chỉ định.

Hàm này sử dụng phương thức loader get_data() để hỗ trợ các mô-đun được cài đặt trong hệ thống tệp cũng như trong các tệp zip, cơ sở dữ liệu hoặc ở nơi khác.

Đối với các gói nằm trong hệ thống tệp đã được nhập, đây gần như tương đương với

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, Resource), 'rb').read()

Giống như hàm open(), get_data() có thể đi theo các thư mục mẹ (../) và các đường dẫn tuyệt đối (ví dụ: bắt đầu bằng / hoặc C:/). Nó có thể mở các tạo phẩm biên dịch/cài đặt như tệp .py và .pyc hoặc các tệp bằng reserved filenames. Để tương thích với các trình tải không phải hệ thống tập tin, hãy tránh sử dụng các tính năng này.

Cảnh báo

Chức năng này dành cho đầu vào đáng tin cậy. Nó không xác minh rằng resource "thuộc về" package.

Nếu bạn sử dụng đường dẫn resource do người dùng cung cấp, hãy cân nhắc việc xác minh đường dẫn đó. Ví dụ: yêu cầu tên tệp chữ và số có phần mở rộng đã biết hoặc cài đặt và kiểm tra danh sách các tài nguyên đã biết.

Nếu không thể định vị hoặc tải gói hoặc gói đó sử dụng loader không hỗ trợ get_data thì None sẽ được trả về. Đặc biệt, loader dành cho namespace packages không hỗ trợ get_data.

Xem thêm

Mô-đun importlib.resources cung cấp quyền truy cập có cấu trúc vào tài nguyên mô-đun.

pkgutil.resolve_name(name)¶

Phân giải tên cho một đối tượng.

Chức năng này được sử dụng ở nhiều nơi trong thư viện tiêu chuẩn (xem bpo-12915) - và chức năng tương đương cũng có trong các gói bên thứ ba được sử dụng rộng rãi như setuptools, Django và Pyramid.

Dự kiến, name sẽ là một chuỗi ở một trong các định dạng sau, trong đó W là tốc ký của mã định danh Python hợp lệ và dấu chấm là viết tắt của dấu chấm trong các biểu thức giả này:

W(.W)*
W(.W)*:(W(.W)*)?

Biểu mẫu đầu tiên chỉ nhằm mục đích tương thích ngược. Nó giả định rằng một phần của tên có dấu chấm là một gói và phần còn lại là một đối tượng ở đâu đó trong gói đó, có thể được lồng bên trong các đối tượng khác. Vì không thể suy ra vị trí nơi gói dừng và hệ thống phân cấp đối tượng bắt đầu bằng cách kiểm tra nên các nỗ lực nhập lặp lại phải được thực hiện bằng biểu mẫu này.

Ở dạng thứ hai, lệnh gọi làm rõ điểm phân chia thông qua việc cung cấp một dấu hai chấm: tên có dấu chấm ở bên trái dấu hai chấm là gói được nhập và tên có dấu chấm ở bên phải là hệ thống phân cấp đối tượng trong gói đó. Chỉ cần một lần nhập trong biểu mẫu này. Nếu nó kết thúc bằng dấu hai chấm thì một đối tượng mô-đun sẽ được trả về.

Hàm sẽ trả về một đối tượng (có thể là một mô-đun) hoặc đưa ra một trong các ngoại lệ sau:

ValueError -- nếu name không có định dạng được nhận dạng.

ImportError -- nếu quá trình nhập không thành công trong khi lẽ ra nó không nên như vậy.

AttributeError -- Nếu xảy ra lỗi khi duyệt qua hệ thống phân cấp đối tượng trong gói đã nhập để đến đối tượng mong muốn.

Added in version 3.9.

`pkgutil` --- Tiện ích mở rộng gói¶

Chủ đề trước

Chủ đề tiếp

Trang này

pkgutil --- Tiện ích mở rộng gói¶

`pkgutil` --- Tiện ích mở rộng gói¶