py_compile --- Biên dịch tập tin nguồn Python

Source code: Lib/py_compile.py

Mô-đun py_compile cung cấp chức năng tạo tệp mã byte từ tệp nguồn và một chức năng khác được sử dụng khi tệp nguồn mô-đun được gọi dưới dạng tập lệnh.

Mặc dù không thường xuyên cần thiết, nhưng chức năng này có thể hữu ích khi cài đặt các mô-đun để sử dụng chung, đặc biệt nếu một số người dùng có thể không có quyền ghi các tệp bộ đệm mã byte vào thư mục chứa mã nguồn.

exception py_compile.PyCompileError

Ngoại lệ nảy sinh khi xảy ra lỗi trong khi cố gắng biên dịch tệp.

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

Biên dịch tệp nguồn thành mã byte và ghi ra tệp bộ đệm mã byte. Mã nguồn được tải từ tệp có tên file. Mã byte được ghi vào cfile, mặc định là đường dẫn PEP 3147/PEP 488, kết thúc bằng .pyc. Ví dụ: nếu file là /foo/bar/baz.py cfile sẽ mặc định là /foo/bar/__pycache__/baz.cpython-32.pyc cho Python 3.2. Nếu dfile được chỉ định, nó sẽ được sử dụng thay vì file làm tên của tệp nguồn mà từ đó các dòng nguồn được lấy để hiển thị trong các dấu vết ngoại lệ. Nếu doraise là đúng, PyCompileError sẽ xuất hiện khi gặp lỗi trong khi biên dịch file. Nếu doraise là sai (mặc định), một chuỗi lỗi sẽ được ghi vào sys.stderr nhưng không có ngoại lệ nào được đưa ra. Hàm này trả về đường dẫn đến tệp được biên dịch theo byte, tức là bất kỳ giá trị cfile nào đã được sử dụng.

Các đối số doraise và quiet xác định cách xử lý lỗi trong khi biên dịch tệp. Nếu quiet là 0 hoặc 1 và doraise là sai thì hành vi mặc định sẽ được bật: một chuỗi lỗi được ghi vào sys.stderr và hàm trả về None thay vì một đường dẫn. Nếu doraise là đúng thì thay vào đó, PyCompileError sẽ được nâng lên. Tuy nhiên, nếu quiet là 2 thì không có thông báo nào được viết và doraise không có hiệu lực.

Nếu đường dẫn mà cfile trở thành (được chỉ định rõ ràng hoặc được tính toán) là một liên kết tượng trưng hoặc tệp không thông thường, FileExistsError sẽ được nâng lên. Điều này nhằm cảnh báo rằng quá trình nhập sẽ biến các đường dẫn đó thành các tệp thông thường nếu được phép ghi các tệp được biên dịch byte vào các đường dẫn đó. Đây là tác dụng phụ của việc nhập bằng cách đổi tên tệp để đặt tệp được biên dịch byte cuối cùng vào vị trí nhằm ngăn chặn các sự cố ghi tệp đồng thời.

optimize kiểm soát mức độ tối ưu hóa và được chuyển đến chức năng compile() tích hợp. Mặc định của -1 chọn mức độ tối ưu hóa của trình thông dịch hiện tại.

invalidation_mode phải là thành viên của enum PycInvalidationMode và kiểm soát cách vô hiệu hóa bộ đệm mã byte được tạo trong thời gian chạy. Mặc định là PycInvalidationMode.CHECKED_HASH nếu biến môi trường SOURCE_DATE_EPOCH được đặt, nếu không thì mặc định là PycInvalidationMode.TIMESTAMP.

Thay đổi trong phiên bản 3.2: Đã thay đổi giá trị mặc định của cfile để tuân thủ PEP 3147. Mặc định trước đó là file + 'c' ('o' nếu bật tối ưu hóa). Cũng đã thêm tham số optimize.

Thay đổi trong phiên bản 3.4: Đã thay đổi mã để sử dụng importlib để ghi tệp bộ nhớ đệm mã byte. Điều này có nghĩa là ngữ nghĩa tạo/ghi tệp hiện khớp với những gì importlib làm, ví dụ: quyền, ngữ nghĩa ghi và di chuyển, v.v. Ngoài ra, còn thêm cảnh báo rằng FileExistsError sẽ được nâng lên nếu cfile là một liên kết tượng trưng hoặc tệp không thông thường.

Thay đổi trong phiên bản 3.7: Tham số invalidation_mode đã được thêm như được chỉ định trong PEP 552. Nếu biến môi trường SOURCE_DATE_EPOCH được đặt, invalidation_mode sẽ bị buộc phải PycInvalidationMode.CHECKED_HASH.

Thay đổi trong phiên bản 3.7.2: Biến môi trường SOURCE_DATE_EPOCH không còn ghi đè giá trị của đối số invalidation_mode và thay vào đó xác định giá trị mặc định của nó.

Thay đổi trong phiên bản 3.8: Tham số quiet đã được thêm vào.

class py_compile.PycInvalidationMode

Một bảng liệt kê các phương pháp có thể có mà trình thông dịch có thể sử dụng để xác định xem tệp mã byte có được cập nhật với tệp nguồn hay không. Tệp .pyc cho biết chế độ vô hiệu hóa mong muốn trong tiêu đề của nó. Xem Vô hiệu hóa mã byte được lưu trong bộ nhớ đệm để biết thêm thông tin về cách Python vô hiệu hóa các tệp .pyc khi chạy.

Added in version 3.7.

TIMESTAMP

Tệp .pyc bao gồm dấu thời gian và kích thước của tệp nguồn mà Python sẽ so sánh với siêu dữ liệu của tệp nguồn trong thời gian chạy để xác định xem tệp .pyc có cần được tạo lại hay không.

CHECKED_HASH

Tệp .pyc bao gồm hàm băm của nội dung tệp nguồn mà Python sẽ so sánh với nguồn trong thời gian chạy để xác định xem tệp .pyc có cần được tạo lại hay không.

UNCHECKED_HASH

Giống như CHECKED_HASH, tệp .pyc bao gồm hàm băm của nội dung tệp nguồn. Tuy nhiên, trong thời gian chạy, Python sẽ cho rằng tệp .pyc đã được cập nhật và hoàn toàn không xác thực .pyc đối với tệp nguồn.

Tùy chọn này hữu ích khi .pycs được cập nhật bởi một số hệ thống bên ngoài Python như hệ thống xây dựng.

Giao diện dòng lệnh

Mô-đun này có thể được gọi dưới dạng tập lệnh để biên dịch một số tệp nguồn. Các tệp có tên trong filenames được biên dịch và mã byte kết quả được lưu vào bộ đệm theo cách thông thường. Chương trình này không tìm kiếm cấu trúc thư mục để định vị các tệp nguồn; nó chỉ biên dịch các tập tin có tên rõ ràng. Trạng thái thoát khác 0 nếu một trong các tệp không thể được biên dịch.

<file> ... <fileN>
-

Đối số vị trí là các tập tin để biên dịch. Nếu - là tham số duy nhất, danh sách các tệp sẽ được lấy từ đầu vào tiêu chuẩn.

-q, --quiet

Ngăn chặn lỗi đầu ra.

Thay đổi trong phiên bản 3.2: Đã thêm hỗ trợ cho -.

Thay đổi trong phiên bản 3.10: Đã thêm hỗ trợ cho -q.

Xem thêm

Mô-đun compileall

Các tiện ích để biên dịch tất cả các tệp nguồn Python trong cây thư mục.