runpy --- Định vị và thực thi các mô-đun Python

Source code: Lib/runpy.py

---

Mô-đun runpy được sử dụng để định vị và chạy các mô-đun Python mà không cần nhập chúng trước. Công dụng chính của nó là triển khai chuyển đổi dòng lệnh -m cho phép định vị các tập lệnh bằng cách sử dụng không gian tên mô-đun Python thay vì hệ thống tệp.

Lưu ý rằng đây là not một mô-đun hộp cát - tất cả mã được thực thi trong quy trình hiện tại và mọi tác dụng phụ (chẳng hạn như nhập các mô-đun khác vào bộ nhớ đệm) sẽ vẫn giữ nguyên sau khi các chức năng quay trở lại.

Hơn nữa, mọi hàm và lớp được xác định bởi mã thực thi đều không được đảm bảo hoạt động chính xác sau khi hàm runpy trả về. Nếu giới hạn đó không được chấp nhận đối với một trường hợp sử dụng nhất định, importlib có thể là lựa chọn phù hợp hơn mô-đun này.

Mô-đun runpy cung cấp hai chức năng:

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

Thực thi mã của mô-đun đã chỉ định và trả về từ điển toàn cầu của mô-đun kết quả. Mã của mô-đun trước tiên được định vị bằng cơ chế nhập tiêu chuẩn (tham khảo PEP 302 để biết chi tiết) và sau đó được thực thi trong không gian tên mô-đun mới.

Đối số mod_name phải là tên mô-đun tuyệt đối. Nếu tên mô-đun đề cập đến một gói chứ không phải một mô-đun thông thường thì gói đó sẽ được nhập và mô-đun con __main__ trong gói đó sẽ được thực thi và từ điển toàn cầu của mô-đun kết quả được trả về.

Đối số từ điển tùy chọn init_globals có thể được sử dụng để điền trước từ điển toàn cục của mô-đun trước khi mã được thực thi. init_globals sẽ không được sửa đổi. Nếu bất kỳ biến toàn cục đặc biệt nào dưới đây được xác định trong init_globals, thì các định nghĩa đó sẽ bị run_module() ghi đè.

Các biến toàn cục đặc biệt __name__, __spec__, __file__, __cached__, __loader__ và __package__ được đặt trong từ điển toàn cầu trước khi mã mô-đun được thực thi. (Lưu ý rằng đây là tập hợp biến tối thiểu - các biến khác có thể được đặt ngầm dưới dạng chi tiết triển khai trình thông dịch.)

__name__ được đặt thành run_name nếu đối số tùy chọn này không phải là None, thành mod_name + '.__main__' nếu mô-đun được đặt tên là một gói và đối số mod_name nếu ngược lại.

__spec__ sẽ được đặt phù hợp cho mô-đun nhập actually (nghĩa là __spec__.name sẽ luôn là mod_name hoặc mod_name + '.__main__', không bao giờ là run_name).

__file__, __cached__, __loader__ và __package__ là set as normal dựa trên thông số kỹ thuật của mô-đun.

Nếu đối số alter_sys được cung cấp và đánh giá thành True thì sys.argv[0] được cập nhật với giá trị __file__ và sys.modules[__name__] được cập nhật với một đối tượng mô-đun tạm thời cho mô-đun đang được thực thi. Cả sys.argv[0] và sys.modules[__name__] đều được khôi phục về giá trị ban đầu trước khi hàm trả về.

Lưu ý rằng thao tác sys này không an toàn cho luồng. Các luồng khác có thể thấy mô-đun được khởi tạo một phần cũng như danh sách các đối số đã thay đổi. Bạn nên để mô-đun sys một mình khi gọi hàm này từ mã luồng.

Xem thêm

Tùy chọn -m cung cấp chức năng tương đương từ dòng lệnh.

Thay đổi trong phiên bản 3.1: Đã thêm khả năng thực thi các gói bằng cách tìm kiếm mô-đun con __main__.

Thay đổi trong phiên bản 3.2: Đã thêm biến toàn cục __cached__ (xem PEP 3147).

Thay đổi trong phiên bản 3.4: Đã cập nhật để tận dụng tính năng thông số mô-đun được thêm bởi PEP 451. Điều này cho phép __cached__ được đặt chính xác cho các mô-đun chạy theo cách này, cũng như đảm bảo tên mô-đun thực luôn có thể truy cập được là __spec__.name.

Thay đổi trong phiên bản 3.12: Cài đặt __cached__, __loader__ và __package__ không được dùng nữa. Xem ModuleSpec để biết các lựa chọn thay thế.

runpy.run_path(path_name, init_globals=None, run_name=None)

Thực thi mã tại vị trí hệ thống tệp được đặt tên và trả về từ điển toàn cầu của mô-đun kết quả. Giống như tên tập lệnh được cung cấp cho dòng lệnh CPython, file_path có thể đề cập đến tệp nguồn Python, tệp mã byte được biên dịch hoặc mục nhập sys.path hợp lệ chứa mô-đun __main__ (ví dụ: tệp zip chứa tệp __main__.py cấp cao nhất).

Đối với một tập lệnh đơn giản, mã được chỉ định sẽ được thực thi đơn giản trong không gian tên mô-đun mới. Đối với mục nhập sys.path hợp lệ (thường là tệp zip hoặc thư mục), mục nhập này trước tiên sẽ được thêm vào đầu sys.path. Sau đó, hàm này sẽ tìm và thực thi mô-đun __main__ bằng đường dẫn đã cập nhật. Lưu ý rằng không có biện pháp bảo vệ đặc biệt nào chống lại việc gọi mục nhập __main__ hiện có nằm ở nơi khác trên sys.path nếu không có mô-đun như vậy tại vị trí được chỉ định.

Đối số từ điển tùy chọn init_globals có thể được sử dụng để điền trước từ điển toàn cục của mô-đun trước khi mã được thực thi. init_globals sẽ không được sửa đổi. Nếu bất kỳ biến toàn cục đặc biệt nào dưới đây được xác định trong init_globals, thì các định nghĩa đó sẽ bị run_path() ghi đè.

Các biến toàn cục đặc biệt __name__, __spec__, __file__, __cached__, __loader__ và __package__ được đặt trong từ điển toàn cầu trước khi mã mô-đun được thực thi. (Lưu ý rằng đây là tập hợp biến tối thiểu - các biến khác có thể được đặt ngầm dưới dạng chi tiết triển khai trình thông dịch.)

__name__ được đặt thành run_name nếu đối số tùy chọn này không phải là None và nếu không thì là '<run_path>'.

Nếu file_path tham chiếu trực tiếp đến tệp tập lệnh (dù là nguồn hay mã byte được biên dịch trước), thì __file__ sẽ được đặt thành file_path và __spec__, __cached__, __loader__ và __package__ đều sẽ được đặt thành None.

Nếu file_path là tham chiếu đến mục nhập sys.path hợp lệ thì __spec__ sẽ được đặt phù hợp cho mô-đun __main__ đã nhập (nghĩa là __spec__.name sẽ luôn là __main__). __file__, __cached__, __loader__ và __package__ sẽ là set as normal dựa trên thông số kỹ thuật của mô-đun.

Một số thay đổi cũng được thực hiện đối với mô-đun sys. Thứ nhất, sys.path có thể được thay đổi như mô tả ở trên. sys.argv[0] được cập nhật với giá trị của file_path và sys.modules[__name__] được cập nhật với một đối tượng mô-đun tạm thời cho mô-đun đang được thực thi. Tất cả các sửa đổi đối với các mục trong sys đều được hoàn nguyên trước khi hàm trả về.

Lưu ý rằng, không giống như run_module(), những thay đổi được thực hiện đối với sys không phải là tùy chọn trong chức năng này vì những điều chỉnh này là cần thiết để cho phép thực thi các mục sys.path. Vì các giới hạn về an toàn luồng vẫn được áp dụng nên việc sử dụng chức năng này trong mã luồng phải được tuần tự hóa bằng khóa nhập hoặc được ủy quyền cho một quy trình riêng biệt.

Xem thêm

Tùy chọn giao diện để có chức năng tương đương trên dòng lệnh (python path/to/script).

Added in version 3.2.

Thay đổi trong phiên bản 3.4: Đã cập nhật để tận dụng tính năng thông số mô-đun được thêm bởi PEP 451. Điều này cho phép __cached__ được đặt chính xác trong trường hợp __main__ được nhập từ mục nhập sys.path hợp lệ thay vì được thực thi trực tiếp.

Thay đổi trong phiên bản 3.12: Cài đặt __cached__, __loader__ và __package__ không được dùng nữa.

Xem thêm

PEP 338 -- Thực thi các mô-đun dưới dạng tập lệnh

PEP được viết và triển khai bởi Nick Coghlan.

PEP 366 -- Nhập khẩu tương đối rõ ràng của mô-đun chính

PEP được viết và triển khai bởi Nick Coghlan.

PEP 451 -- Loại ModuleSpec cho hệ thống nhập

PEP được viết và triển khai bởi Eric Snow

Dòng lệnh và môi trường - Chi tiết dòng lệnh CPython

Chức năng importlib.import_module()