compileall --- Thư viện Python biên dịch byte

Source code: Lib/compileall.py

Mô-đun này cung cấp một số chức năng tiện ích hỗ trợ cài đặt thư viện Python. Các hàm này biên dịch các tệp nguồn Python trong cây thư mục. Mô-đun này có thể được sử dụng để tạo các tệp mã byte được lưu trong bộ nhớ đệm tại thời điểm cài đặt thư viện, giúp chúng có sẵn để sử dụng ngay cả với những người dùng không có quyền ghi vào thư mục thư viện.

sẵn có: not WASI.

Mô-đun này không hoạt động hoặc không có trên WebAssembly. Xem Nền tảng WebAssugging để biết thêm thông tin.

Sử dụng dòng lệnh

Mô-đun này có thể hoạt động như một tập lệnh (sử dụng python -m compileall) để biên dịch các nguồn Python.

directory ...
file ...

Đối số vị trí là các tệp để biên dịch hoặc các thư mục chứa tệp nguồn, được duyệt đệ quy. Nếu không có đối số nào được đưa ra, hãy xử lý như thể dòng lệnh là -l <directories from sys.path>.

-l

Không lặp lại vào các thư mục con, chỉ biên dịch các tệp mã nguồn có chứa trực tiếp trong các thư mục được đặt tên hoặc ngụ ý.

-f

Buộc xây dựng lại ngay cả khi dấu thời gian được cập nhật.

-q

Không in danh sách các tập tin được biên dịch. Nếu vượt qua một lần, thông báo lỗi sẽ vẫn được in. Nếu được truyền hai lần (-qq), tất cả đầu ra sẽ bị chặn.

-d destdir

Thư mục được thêm vào trước đường dẫn đến mỗi tệp đang được biên dịch. Điều này sẽ xuất hiện trong các lần theo dõi thời gian biên dịch và cũng được biên dịch vào tệp mã byte, nơi nó sẽ được sử dụng trong các lần theo dõi và các thông báo khác trong trường hợp tệp nguồn không tồn tại tại thời điểm tệp mã byte được thực thi.

-s strip_prefix

Xóa tiền tố đã cho khỏi các đường dẫn được ghi trong tệp .pyc. Đường dẫn được thực hiện liên quan đến tiền tố.

Tùy chọn này có thể được sử dụng với -p nhưng không dùng được với -d.

-p prepend_prefix

Thêm tiền tố đã cho vào các đường dẫn được ghi trong tệp .pyc. Sử dụng -p / để tạo đường dẫn tuyệt đối.

Tùy chọn này có thể được sử dụng với -s nhưng không dùng được với -d.

-x regex

biểu thức chính quy được sử dụng để tìm kiếm đường dẫn đầy đủ đến từng tệp được xem xét để biên dịch và nếu biểu thức chính quy tạo ra kết quả khớp thì tệp sẽ bị bỏ qua.

-i list

Đọc tệp list và thêm từng dòng chứa trong đó vào danh sách các tệp và thư mục cần biên dịch. Nếu list là -, hãy đọc các dòng từ stdin.

-b

Ghi các tệp mã byte vào vị trí và tên cũ của chúng, những tệp này có thể ghi đè lên các tệp mã byte được tạo bởi một phiên bản Python khác. Mặc định là ghi tệp vào vị trí và tên PEP 3147 của chúng, điều này cho phép các tệp mã byte từ nhiều phiên bản Python cùng tồn tại.

-r

Kiểm soát mức đệ quy tối đa cho các thư mục con. Nếu điều này được đưa ra thì tùy chọn -l sẽ không được tính đến. python -m compileall <directory> -r 0 tương đương với python -m compileall <directory> -l.

-j N

Sử dụng công nhân N để biên dịch các tệp trong thư mục đã cho. Nếu 0 được sử dụng thì kết quả của os.process_cpu_count() sẽ được sử dụng.

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

Kiểm soát cách các tệp mã byte được tạo bị vô hiệu hóa khi chạy. Giá trị timestamp, có nghĩa là các tệp .pyc có dấu thời gian nguồn và kích thước được nhúng sẽ được tạo. Các giá trị checked-hash và unchecked-hash khiến pycs dựa trên hàm băm được tạo ra. Pycs dựa trên hàm băm nhúng hàm băm của nội dung tệp nguồn thay vì dấu thời gian. 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 xác thực các tệp bộ đệm mã byte trong thời gian chạy. Mặc định là timestamp nếu biến môi trường SOURCE_DATE_EPOCH không được đặt và checked-hash nếu biến môi trường SOURCE_DATE_EPOCH được đặt.

-o level

Biên dịch với mức tối ưu hóa nhất định. Có thể được sử dụng nhiều lần để biên dịch cho nhiều cấp độ cùng một lúc (ví dụ: compileall -o 1 -o 2).

-e dir

Bỏ qua các liên kết tượng trưng trỏ ra ngoài thư mục đã cho.

Nếu hai tệp .pyc có mức tối ưu hóa khác nhau có cùng nội dung, hãy sử dụng liên kết cứng để hợp nhất các tệp trùng lặp.

Thay đổi trong phiên bản 3.2: Đã thêm các tùy chọn -i, -b và -h.

Thay đổi trong phiên bản 3.5: Đã thêm các tùy chọn -j, -r và -qq. Tùy chọn -q đã được thay đổi thành giá trị đa cấp. -b sẽ luôn tạo tệp mã byte kết thúc bằng .pyc, không bao giờ .pyo.

Thay đổi trong phiên bản 3.7: Đã thêm tùy chọn --invalidation-mode.

Thay đổi trong phiên bản 3.9: Đã thêm các tùy chọn -s, -p, -e và --hardlink-dupes. Đã tăng giới hạn đệ quy mặc định từ 10 lên sys.getrecursionlimit(). Đã thêm khả năng chỉ định tùy chọn -o nhiều lần.

Không có tùy chọn dòng lệnh nào để kiểm soát mức tối ưu hóa được hàm compile() sử dụng vì bản thân trình thông dịch Python đã cung cấp tùy chọn: python -O -m compileall.

Tương tự, hàm compile() tôn trọng cài đặt sys.pycache_prefix. Bộ đệm mã byte được tạo sẽ chỉ hữu ích nếu compile() được chạy với cùng sys.pycache_prefix (nếu có) sẽ được sử dụng trong thời gian chạy.

Chức năng công cộng

compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

Đệ quy xuống cây thư mục được đặt tên bởi dir, biên dịch tất cả các tệp .py trong suốt quá trình. Trả về giá trị đúng nếu tất cả các tệp được biên dịch thành công và nếu không thì trả về giá trị sai.

Tham số maxlevels được sử dụng để giới hạn độ sâu của đệ quy; nó mặc định là sys.getrecursionlimit().

Nếu ddir được cung cấp, nó sẽ được thêm vào trước đường dẫn đến từng tệp đang được biên dịch để sử dụng trong quá trình theo dõi thời gian biên dịch và cũng được biên dịch vào tệp mã byte, nơi nó sẽ được sử dụng trong các lần truy nguyên và các thông báo khác trong trường hợp tệp nguồn không tồn tại tại thời điểm tệp mã byte được thực thi.

Nếu force đúng, các mô-đun sẽ được biên dịch lại ngay cả khi dấu thời gian được cập nhật.

Nếu rx được cung cấp, phương thức search của nó sẽ được gọi trên đường dẫn đầy đủ đến từng tệp được xem xét để biên dịch và nếu nó trả về giá trị đúng thì tệp sẽ bị bỏ qua. Điều này có thể được sử dụng để loại trừ các tệp khớp với biểu thức chính quy, được cung cấp dưới dạng đối tượng re.Pattern.

Nếu quiet là False hoặc 0 (mặc định), tên tệp và thông tin khác sẽ được in ra theo tiêu chuẩn. Đặt thành 1, chỉ có lỗi được in. Đặt thành 2, tất cả đầu ra đều bị chặn.

Nếu legacy là đúng, các tệp mã byte sẽ được ghi vào vị trí và tên cũ của chúng, các tệp này có thể ghi đè lên các tệp mã byte được tạo bởi một phiên bản Python khác. Mặc định là ghi tệp vào vị trí và tên PEP 3147 của chúng, điều này cho phép các tệp mã byte từ nhiều phiên bản Python cùng tồn tại.

optimize chỉ định mức tối ưu hóa cho trình biên dịch. Nó được chuyển đến chức năng compile() tích hợp. Cũng chấp nhận một chuỗi các mức tối ưu hóa dẫn đến nhiều lần tổng hợp một tệp .py trong một lệnh gọi.

Đối số workers chỉ định số lượng công nhân được sử dụng để biên dịch các tệp song song. Mặc định là không sử dụng nhiều công nhân. Nếu nền tảng không thể sử dụng nhiều trình chạy và đối số workers được đưa ra thì quá trình biên dịch tuần tự sẽ được sử dụng làm phương án dự phòng. Nếu workers bằng 0 thì số lõi trong hệ thống sẽ được sử dụng. Nếu workers thấp hơn 0 thì ValueError sẽ được nâng lên.

invalidation_mode phải là thành viên của enum py_compile.PycInvalidationMode và kiểm soát cách các pycs được tạo bị vô hiệu hóa trong thời gian chạy.

Các đối số stripdir, prependdir và limit_sl_dest tương ứng với các tùy chọn -s, -p và -e được mô tả ở trên. Chúng có thể được chỉ định là str hoặc os.PathLike.

Nếu hardlink_dupes là đúng và hai tệp .pyc có mức tối ưu hóa khác nhau có cùng nội dung, hãy sử dụng liên kết cứng để hợp nhất các tệp trùng lặp.

Thay đổi trong phiên bản 3.2: Đã thêm tham số legacy và optimize.

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

Thay đổi trong phiên bản 3.5: Tham số quiet đã được thay đổi thành giá trị đa cấp.

Thay đổi trong phiên bản 3.5: Tham số legacy chỉ ghi ra các tệp .pyc chứ không phải các tệp .pyo bất kể giá trị của optimize là bao nhiêu.

Thay đổi trong phiên bản 3.6: Chấp nhận path-like object.

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

Thay đổi trong phiên bản 3.7.2: Giá trị mặc định của tham số invalidation_mode được cập nhật thành None.

Thay đổi trong phiên bản 3.8: Đặt workers thành 0 bây giờ sẽ chọn số lõi tối ưu.

Thay đổi trong phiên bản 3.9: Đã thêm các đối số stripdir, prependdir, limit_sl_dest và hardlink_dupes. Giá trị mặc định của maxlevels đã được thay đổi từ 10 thành sys.getrecursionlimit()

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

Biên dịch file với đường dẫn fullname. Trả về giá trị đúng nếu tệp được biên dịch thành công và trả về giá trị sai nếu ngược lại.

Nếu ddir được cung cấp, nó sẽ được thêm vào trước đường dẫn đến tệp đang được biên dịch để sử dụng trong quá trình truy ngược thời gian biên dịch và cũng được biên dịch vào tệp mã byte, nơi nó sẽ được sử dụng trong truy nguyên và các thông báo khác trong trường hợp tệp nguồn không tồn tại tại thời điểm tệp mã byte được thực thi.

Nếu rx được cung cấp, phương thức search của nó sẽ được chuyển tên đường dẫn đầy đủ đến tệp đang được biên dịch và nếu nó trả về giá trị đúng, tệp sẽ không được biên dịch và True được trả về. Điều này có thể được sử dụng để loại trừ các tệp khớp với biểu thức chính quy, được cung cấp dưới dạng đối tượng re.Pattern.

Nếu quiet là False hoặc 0 (mặc định), tên tệp và thông tin khác sẽ được in ra theo tiêu chuẩn. Đặt thành 1, chỉ có lỗi được in. Đặt thành 2, tất cả đầu ra đều bị chặn.

Nếu legacy là đúng, các tệp mã byte sẽ được ghi vào vị trí và tên cũ của chúng, các tệp này có thể ghi đè lên các tệp mã byte được tạo bởi một phiên bản Python khác. Mặc định là ghi tệp vào vị trí và tên PEP 3147 của chúng, điều này cho phép các tệp mã byte từ nhiều phiên bản Python cùng tồn tại.

optimize chỉ định mức tối ưu hóa cho trình biên dịch. Nó được chuyển đến chức năng compile() tích hợp. Cũng chấp nhận một chuỗi các mức tối ưu hóa dẫn đến nhiều lần tổng hợp một tệp .py trong một lệnh gọi.

invalidation_mode phải là thành viên của enum py_compile.PycInvalidationMode và kiểm soát cách các pycs được tạo bị vô hiệu hóa trong thời gian chạy.

Các đối số stripdir, prependdir và limit_sl_dest tương ứng với các tùy chọn -s, -p và -e được mô tả ở trên. Chúng có thể được chỉ định là str hoặc os.PathLike.

Nếu hardlink_dupes là đúng và hai tệp .pyc có mức tối ưu hóa khác nhau có cùng nội dung, hãy sử dụng liên kết cứng để hợp nhất các tệp trùng lặp.

Added in version 3.2.

Thay đổi trong phiên bản 3.5: Tham số quiet đã được thay đổi thành giá trị đa cấp.

Thay đổi trong phiên bản 3.5: Tham số legacy chỉ ghi ra các tệp .pyc chứ không phải các tệp .pyo bất kể giá trị của optimize là bao nhiêu.

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

Thay đổi trong phiên bản 3.7.2: Giá trị mặc định của tham số invalidation_mode được cập nhật thành None.

Thay đổi trong phiên bản 3.9: Đã thêm các đối số stripdir, prependdir, limit_sl_dest và hardlink_dupes.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

Biên dịch byte tất cả các tệp .py được tìm thấy dọc theo sys.path. Trả về giá trị đúng nếu tất cả các tệp được biên dịch thành công và nếu không thì trả về giá trị sai.

Nếu skip_curdir là true (mặc định), thư mục hiện tại sẽ không được đưa vào tìm kiếm. Tất cả các tham số khác được chuyển đến hàm compile_dir(). Lưu ý rằng không giống như các hàm biên dịch khác, maxlevels mặc định là 0.

Thay đổi trong phiên bản 3.2: Đã thêm tham số legacy và optimize.

Thay đổi trong phiên bản 3.5: Tham số quiet đã được thay đổi thành giá trị đa cấp.

Thay đổi trong phiên bản 3.5: Tham số legacy chỉ ghi ra các tệp .pyc chứ không phải các tệp .pyo bất kể giá trị của optimize là bao nhiêu.

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

Thay đổi trong phiên bản 3.7.2: Giá trị mặc định của tham số invalidation_mode được cập nhật thành None.

Để buộc biên dịch lại tất cả các tệp .py trong thư mục con Lib/ và tất cả các thư mục con của nó:

tổng hợp nhập khẩu

biên dịch.compile_dir('Lib/', Force=True)

# Perform biên dịch tương tự, ngoại trừ các tập tin trong thư mục .svn.
nhập lại
biên dịch.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), Force=True)

Các đối tượng # pathlib.Path cũng có thể được sử dụng.
nhập đường dẫn
biên dịch.compile_dir(pathlib.Path('Lib/'), Force=True)

Xem thêm

Mô-đun py_compile

Byte-biên dịch một tập tin nguồn duy nhất.