Khởi tạo và hoàn thiện trình thông dịch

Xem Python Initialization Configuration để biết chi tiết về cách định cấu hình trình thông dịch trước khi khởi tạo.

Trước khi khởi tạo Python

Trong ứng dụng nhúng Python, hàm Py_Initialize() phải được gọi trước khi sử dụng bất kỳ hàm API nào khác của Python/C; ngoại trừ một số chức năng và global configuration variables.

Các hàm sau có thể được gọi một cách an toàn trước khi Python được khởi tạo:

Ghi chú

Mặc dù có sự tương đồng rõ ràng với một số hàm được liệt kê ở trên, các hàm sau should not be called trước khi trình thông dịch được khởi tạo: Py_EncodeLocale(), PyEval_InitThreads() và Py_RunMain().

Biến cấu hình toàn cầu

Python có các biến dành cho cấu hình chung để kiểm soát các tính năng và tùy chọn khác nhau. Theo mặc định, các cờ này được điều khiển bởi command line options.

Khi cờ được đặt bởi một tùy chọn, giá trị của cờ là số lần tùy chọn được đặt. Ví dụ: -b đặt Py_BytesWarningFlag thành 1 và -bb đặt Py_BytesWarningFlag thành 2.

int Py_BytesWarningFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.bytes_warning, xem Python Initialization Configuration.

Đưa ra cảnh báo khi so sánh bytes hoặc bytearray với str hoặc bytes với int. Đưa ra lỗi nếu lớn hơn hoặc bằng 2.

Đặt theo tùy chọn -b.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_DebugFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.parser_debug, xem Python Initialization Configuration.

Bật đầu ra gỡ lỗi của trình phân tích cú pháp (chỉ dành cho chuyên gia, tùy thuộc vào các tùy chọn biên dịch).

Được đặt theo tùy chọn -d và biến môi trường PYTHONDEBUG.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_DontWriteBytecodeFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.write_bytecode, xem Python Initialization Configuration.

Nếu được đặt thành khác 0, Python sẽ không cố ghi các tệp .pyc khi nhập mô-đun nguồn.

Được đặt theo tùy chọn -B và biến môi trường PYTHONDONTWRITEBYTECODE.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_FrozenFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.pathconfig_warnings, xem Python Initialization Configuration.

Cờ riêng được sử dụng bởi các chương trình _freeze_module và frozenmain.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_HashRandomizationFlag

Zz003zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.hash_seed và PyConfig.use_hash_seed, xem Python Initialization Configuration.

Đặt thành 1 nếu biến môi trường PYTHONHASHSEED được đặt thành một chuỗi không trống.

Nếu cờ khác 0, hãy đọc biến môi trường PYTHONHASHSEED để khởi tạo hạt băm bí mật.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_IgnoreEnvironmentFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.use_environment, xem Python Initialization Configuration.

Bỏ qua tất cả các biến môi trường PYTHON*, ví dụ: PYTHONPATH và PYTHONHOME, điều đó có thể được đặt.

Được đặt theo tùy chọn -E và -I.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_InspectFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.inspect, xem Python Initialization Configuration.

Khi tập lệnh được truyền làm đối số đầu tiên hoặc tùy chọn -c được sử dụng, hãy vào chế độ tương tác sau khi thực thi tập lệnh hoặc lệnh, ngay cả khi sys.stdin dường như không phải là thiết bị đầu cuối.

Được đặt theo tùy chọn -i và biến môi trường PYTHONINSPECT.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_InteractiveFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.interactive, xem Python Initialization Configuration.

Đặt theo tùy chọn -i.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_IsolatedFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.isolated, xem Python Initialization Configuration.

Chạy Python ở chế độ biệt lập. Ở chế độ biệt lập, sys.path không chứa thư mục của tập lệnh cũng như thư mục gói trang web của người dùng.

Đặt theo tùy chọn -I.

Added in version 3.4.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_LegacyWindowsFSEncodingFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyPreConfig.legacy_windows_fs_encoding, xem Python Initialization Configuration.

Nếu cờ khác 0, hãy sử dụng mã hóa mbcs với trình xử lý lỗi replace, thay vì mã hóa UTF-8 với trình xử lý lỗi surrogatepass cho filesystem encoding and error handler.

Đặt thành 1 nếu biến môi trường PYTHONLEGACYWINDOWSFSENCODING được đặt thành một chuỗi không trống.

Xem PEP 529 để biết thêm chi tiết.

sẵn có: Windows.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_LegacyWindowsStdioFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.legacy_windows_stdio, xem Python Initialization Configuration.

Nếu cờ khác 0, hãy sử dụng io.FileIO thay vì io._WindowsConsoleIO cho luồng tiêu chuẩn sys.

Đặt thành 1 nếu biến môi trường PYTHONLEGACYWINDOWSSTDIO được đặt thành một chuỗi không trống.

Xem PEP 528 để biết thêm chi tiết.

sẵn có: Windows.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_NoSiteFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.site_import, xem Python Initialization Configuration.

Vô hiệu hóa việc nhập mô-đun site và các thao tác phụ thuộc vào trang web của sys.path mà nó đòi hỏi. Đồng thời tắt các thao tác này nếu site được nhập rõ ràng sau này (gọi site.main() nếu bạn muốn chúng được kích hoạt).

Đặt theo tùy chọn -S.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_NoUserSiteDirectory

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.user_site_directory, xem Python Initialization Configuration.

Đừng thêm user site-packages directory vào sys.path.

Được đặt bởi các tùy chọn -s và -I và biến môi trường PYTHONNOUSERSITE.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_OptimizeFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.optimization_level, xem Python Initialization Configuration.

Được đặt theo tùy chọn -O và biến môi trường PYTHONOPTIMIZE.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_QuietFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.quiet, xem Python Initialization Configuration.

Không hiển thị thông báo bản quyền và phiên bản ngay cả trong chế độ tương tác.

Đặt theo tùy chọn -q.

Added in version 3.2.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_UnbufferedStdioFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.buffered_stdio, xem Python Initialization Configuration.

Buộc các luồng stdout và stderr không được đệm.

Được đặt theo tùy chọn -u và biến môi trường PYTHONUNBUFFERED.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

int Py_VerboseFlag

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.verbose, xem Python Initialization Configuration.

In thông báo mỗi khi mô-đun được khởi tạo, hiển thị vị trí (tên tệp hoặc mô-đun tích hợp) mà nó được tải. Nếu lớn hơn hoặc bằng 2, hãy in thông báo cho từng tệp được kiểm tra khi tìm kiếm mô-đun. Cũng cung cấp thông tin về việc dọn dẹp mô-đun khi thoát.

Được đặt theo tùy chọn -v và biến môi trường PYTHONVERBOSE.

Không được dùng nữa kể từ phiên bản 3.12, sẽ bị xóa trong phiên bản 3.15.

Khởi tạo và hoàn thiện trình thông dịch

void Py_Initialize()
Một phần của ABI ổn định.

Khởi tạo trình thông dịch Python. Trong một ứng dụng nhúng Python, lệnh này phải được gọi trước khi sử dụng bất kỳ hàm API Python/C nào khác; xem Before Python Initialization để biết một số trường hợp ngoại lệ.

Thao tác này sẽ khởi tạo bảng các mô-đun đã tải (sys.modules) và tạo các mô-đun cơ bản builtins, __main__ và sys. Nó cũng khởi tạo đường dẫn tìm kiếm mô-đun (sys.path). Nó không đặt sys.argv; sử dụng Python Initialization Configuration API cho việc đó. Đây là lỗi không hoạt động khi được gọi lần thứ hai (không gọi Py_FinalizeEx() trước). Không có giá trị trả về; đó là một lỗi nghiêm trọng nếu việc khởi tạo không thành công.

Sử dụng Py_InitializeFromConfig() để tùy chỉnh Python Initialization Configuration.

Ghi chú

Trên Windows, thay đổi chế độ bảng điều khiển từ O_TEXT thành O_BINARY, điều này cũng sẽ ảnh hưởng đến việc sử dụng bảng điều khiển không phải Python bằng C Runtime.

void Py_InitializeEx(int initsigs)
Một phần của ABI ổn định.

Hàm này hoạt động giống như Py_Initialize() nếu initsigs là 1. Nếu initsigs là 0, nó sẽ bỏ qua việc đăng ký khởi tạo bộ xử lý tín hiệu, điều này có thể hữu ích khi CPython được nhúng như một phần của ứng dụng lớn hơn.

Sử dụng Py_InitializeFromConfig() để tùy chỉnh Python Initialization Configuration.

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Khởi tạo Python từ cấu hình config, như được mô tả trong Khởi tạo với PyConfig.

Xem phần Cấu hình khởi tạo Python để biết chi tiết về cách khởi tạo trước trình thông dịch, điền cấu trúc cấu hình thời gian chạy và truy vấn cấu trúc trạng thái được trả về.

int Py_IsInitialized()
Một phần của ABI ổn định.

Trả về true (khác 0) khi trình thông dịch Python đã được khởi tạo, trả về false (không) nếu không. Sau khi Py_FinalizeEx() được gọi, giá trị này trả về sai cho đến khi Py_Initialize() được gọi lại.

int Py_IsFinalizing()
Một phần của ABI ổn định kể từ phiên bản 3.13.

Trả về true (khác 0) nếu trình thông dịch Python chính là shutting down. Trả về sai (không) nếu không.

Added in version 3.13.

int Py_FinalizeEx()
Một phần của ABI ổn định kể từ phiên bản 3.6.

Hoàn tác tất cả các lần khởi tạo do Py_Initialize() thực hiện và việc sử dụng các hàm API của Python/C sau đó, đồng thời hủy tất cả các trình thông dịch phụ (xem Py_NewInterpreter() bên dưới) đã được tạo và chưa bị hủy kể từ lệnh gọi cuối cùng tới Py_Initialize(). Đây là lỗi không hoạt động khi được gọi lần thứ hai (không gọi lại Py_Initialize() trước).

Vì đây là mặt trái của Py_Initialize() nên nó phải được gọi trong cùng một luồng với cùng một trình thông dịch đang hoạt động. Điều đó có nghĩa là luồng chính và trình thông dịch chính. Điều này không bao giờ được gọi khi Py_RunMain() đang chạy.

Thông thường giá trị trả về là 0. Nếu có lỗi trong quá trình hoàn thiện (xóa dữ liệu được đệm), -1 sẽ được trả về.

Lưu ý rằng Python sẽ nỗ lực hết sức để giải phóng tất cả bộ nhớ do trình thông dịch Python phân bổ. Do đó, mọi Tiện ích mở rộng C phải đảm bảo dọn sạch chính xác tất cả các PyObject được phân bổ trước đó trước khi sử dụng chúng trong các lệnh gọi tiếp theo tới Py_Initialize(). Nếu không, nó có thể gây ra các lỗ hổng và hành vi không chính xác.

Chức năng này được cung cấp vì một số lý do. Một ứng dụng nhúng có thể muốn khởi động lại Python mà không cần phải khởi động lại ứng dụng đó. Một ứng dụng đã tải trình thông dịch Python từ thư viện có thể tải động (hoặc DLL) có thể muốn giải phóng tất cả bộ nhớ do Python phân bổ trước khi dỡ bỏ DLL. Trong quá trình tìm kiếm rò rỉ bộ nhớ trong một ứng dụng, nhà phát triển có thể muốn giải phóng tất cả bộ nhớ do Python cấp phát trước khi thoát khỏi ứng dụng.

Bugs and caveats: Việc phá hủy các mô-đun và đối tượng trong mô-đun được thực hiện theo thứ tự ngẫu nhiên; điều này có thể khiến các hàm hủy (phương thức __del__()) bị lỗi khi chúng phụ thuộc vào các đối tượng khác (thậm chí cả các hàm) hoặc mô-đun. Các mô-đun mở rộng được tải động do Python tải sẽ không được tải xuống. Một lượng nhỏ bộ nhớ do trình thông dịch Python phân bổ có thể không được giải phóng (nếu bạn phát hiện thấy rò rỉ, vui lòng báo cáo). Bộ nhớ bị ràng buộc trong các tham chiếu vòng tròn giữa các đối tượng không được giải phóng. Tất cả các chuỗi được nội bộ sẽ được giải phóng bất kể số lượng tham chiếu của chúng. Một số bộ nhớ được phân bổ bởi các mô-đun mở rộng có thể không được giải phóng. Một số tiện ích mở rộng có thể không hoạt động bình thường nếu quy trình khởi tạo của chúng được gọi nhiều lần; điều này có thể xảy ra nếu một ứng dụng gọi Py_Initialize() và Py_FinalizeEx() nhiều lần. Py_FinalizeEx() không được gọi đệ quy từ bên trong chính nó. Do đó, nó không được gọi bằng bất kỳ mã nào có thể chạy như một phần của quá trình tắt trình thông dịch, chẳng hạn như trình xử lý atexit, trình hoàn thiện đối tượng hoặc bất kỳ mã nào có thể chạy trong khi xóa các tệp stdout và stderr.

Tăng auditing event cpython._PySys_ClearAuditHooks mà không có đối số.

Added in version 3.6.

void Py_Finalize()
Một phần của ABI ổn định.

Đây là phiên bản tương thích ngược của Py_FinalizeEx() và không quan tâm đến giá trị trả về.

int Py_BytesMain(int argc, char **argv)
Một phần của ABI ổn định kể từ phiên bản 3.8.

Tương tự như Py_Main() nhưng argv là một mảng các chuỗi byte, cho phép ứng dụng gọi ủy thác bước giải mã văn bản cho thời gian chạy CPython.

Added in version 3.8.

int Py_Main(int argc, wchar_t **argv)
Một phần của ABI ổn định.

Chương trình chính dành cho trình thông dịch tiêu chuẩn, gói gọn chu trình khởi tạo/hoàn thiện đầy đủ cũng như hành vi bổ sung để triển khai đọc cài đặt cấu hình từ môi trường và dòng lệnh, sau đó thực thi __main__ theo Dòng lệnh.

Tính năng này được cung cấp cho các chương trình muốn hỗ trợ giao diện dòng lệnh CPython đầy đủ, thay vì chỉ nhúng thời gian chạy Python vào một ứng dụng lớn hơn.

Các tham số argc và argv tương tự như các tham số được truyền cho hàm main() của chương trình C, ngoại trừ việc các mục argv trước tiên được chuyển đổi thành wchar_t bằng Py_DecodeLocale(). Điều quan trọng cần lưu ý là các mục trong danh sách đối số có thể được sửa đổi để trỏ đến các chuỗi khác với các chuỗi được truyền vào (tuy nhiên, nội dung của các chuỗi được trỏ đến bởi danh sách đối số không được sửa đổi).

Giá trị trả về là 2 nếu danh sách đối số không biểu thị dòng lệnh Python hợp lệ và nếu không thì giống như Py_RunMain().

Xét về các API cấu hình thời gian chạy CPython được ghi lại trong phần runtime configuration (và không tính đến việc xử lý lỗi), Py_Main gần tương đương với:

Cấu hình PyConfig;
PyConfig_InitPythonConfig(&config);
PyConfig_SetArgv(&config, argc, argv);
Py_InitializeFromConfig(&config);
PyConfig_Clear(&config);

Py_RunMain();

Trong cách sử dụng thông thường, một ứng dụng nhúng sẽ gọi hàm này là instead hoặc gọi trực tiếp Py_Initialize(), Py_InitializeEx() hoặc Py_InitializeFromConfig() và tất cả các cài đặt sẽ được áp dụng như được mô tả ở nơi khác trong tài liệu này. Thay vào đó, nếu hàm này được gọi là after thì lệnh gọi API khởi tạo thời gian chạy trước đó thì cài đặt cấu hình dòng lệnh và môi trường nào sẽ được cập nhật sẽ phụ thuộc vào phiên bản (vì nó phụ thuộc vào cài đặt nào hỗ trợ sửa đổi chính xác sau khi chúng đã được đặt một lần khi thời gian chạy được khởi tạo lần đầu tiên).

int Py_RunMain(void)

Thực thi mô-đun chính trong thời gian chạy CPython được cấu hình đầy đủ.

Thực thi lệnh (PyConfig.run_command), tập lệnh (PyConfig.run_filename) hoặc mô-đun (PyConfig.run_module) được chỉ định trên dòng lệnh hoặc trong cấu hình. Nếu không có giá trị nào trong số này được đặt, hãy chạy dấu nhắc Python tương tác (REPL) bằng cách sử dụng không gian tên chung của mô-đun __main__.

Nếu PyConfig.inspect không được đặt (mặc định), giá trị trả về sẽ là 0 nếu trình thông dịch thoát bình thường (nghĩa là không đưa ra ngoại lệ), trạng thái thoát của SystemExit chưa được xử lý hoặc 1 cho bất kỳ ngoại lệ nào khác chưa được xử lý.

Nếu PyConfig.inspect được đặt (chẳng hạn như khi tùy chọn -i được sử dụng), thay vì quay lại khi trình thông dịch thoát, việc thực thi sẽ tiếp tục trong dấu nhắc Python tương tác (REPL) bằng cách sử dụng không gian tên chung của mô-đun __main__. Nếu trình thông dịch thoát với một ngoại lệ, nó sẽ ngay lập tức được đưa ra trong phiên REPL. Sau đó, giá trị trả về của hàm được xác định theo cách REPL session kết thúc: 0, 1 hoặc trạng thái của SystemExit, như được chỉ định ở trên.

Hàm này luôn hoàn thiện trình thông dịch Python trước khi nó trả về.

Xem Python Configuration để biết ví dụ về Python tùy chỉnh luôn chạy ở chế độ biệt lập bằng Py_RunMain().

int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void*), void *data)
Đây là API không ổn định. Nó có thể thay đổi mà không có cảnh báo trong các bản phát hành nhỏ.

Đăng ký lệnh gọi lại atexit cho trình thông dịch đích interp. Điều này tương tự như Py_AtExit(), nhưng cần có một trình thông dịch và con trỏ dữ liệu rõ ràng để gọi lại.

Phải có attached thread state cho interp.

Added in version 3.13.

Cảnh báo về việc hoàn tất thời gian chạy

Ở giai đoạn cuối của interpreter shutdown, sau khi cố gắng đợi các luồng không phải daemon thoát ra (mặc dù điều này có thể bị gián đoạn bởi KeyboardInterrupt) và chạy các hàm atexit, thời gian chạy được đánh dấu là finalizing: Py_IsFinalizing() và sys.is_finalizing() trả về true. Tại thời điểm này, chỉ finalization thread đã bắt đầu quá trình quyết toán (thường là luồng chính) mới được phép lấy GIL.

Nếu bất kỳ luồng nào, ngoài luồng quyết toán, cố gắng đính kèm thread state trong quá trình hoàn thiện, dù rõ ràng hay ngầm định, thì luồng đó sẽ đi vào a permanently blocked state nơi nó vẫn tồn tại cho đến khi chương trình thoát. Trong hầu hết các trường hợp, điều này vô hại, nhưng điều này có thể dẫn đến bế tắc nếu giai đoạn hoàn thiện sau này cố gắng lấy khóa thuộc sở hữu của luồng bị chặn hoặc chờ đợi trên luồng bị chặn.

Tổng? Đúng. Điều này ngăn chặn các sự cố ngẫu nhiên và/hoặc các bước hoàn thiện C++ bị bỏ qua bất ngờ trong ngăn xếp cuộc gọi khi các chuỗi đó bị buộc phải thoát khỏi đây trong CPython 3.13 trở về trước. API C thread state thời gian chạy CPython chưa bao giờ có bất kỳ lỗi nào được báo cáo hoặc xử lý kỳ vọng tại thời điểm đính kèm thread state mà lẽ ra có thể cho phép thoát khỏi tình huống này một cách nhẹ nhàng. Việc thay đổi điều đó sẽ yêu cầu các API C ổn định mới và viết lại phần lớn mã C trong hệ sinh thái CPython để sử dụng những mã có khả năng xử lý lỗi.

Tham số toàn quy trình

void Py_SetProgramName(const wchar_t *name)
Một phần của ABI ổn định.

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.program_name, xem Python Initialization Configuration.

Hàm này phải được gọi trước khi Py_Initialize() được gọi lần đầu tiên, nếu nó được gọi. Nó cho trình thông dịch biết giá trị của đối số argv[0] đối với hàm main() của chương trình (được chuyển đổi thành ký tự rộng). Điều này được Py_GetPath() và một số hàm khác bên dưới sử dụng để tìm các thư viện thời gian chạy Python liên quan đến trình thông dịch thực thi. Giá trị mặc định là 'python'. Đối số phải trỏ đến một chuỗi ký tự rộng có kết thúc bằng 0 trong bộ nhớ tĩnh có nội dung sẽ không thay đổi trong suốt thời gian thực hiện chương trình. Không có mã nào trong trình thông dịch Python sẽ thay đổi nội dung của bộ lưu trữ này.

Sử dụng Py_DecodeLocale() để giải mã chuỗi byte để lấy chuỗi wchar_t*.

Không được dùng nữa kể từ phiên bản 3.11, sẽ bị xóa trong phiên bản 3.15.

wchar_t *Py_GetProgramName()
Một phần của ABI ổn định.

Trả về tên chương trình được đặt bằng PyConfig.program_name hoặc mặc định. Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó.

Hàm này không nên được gọi trước Py_Initialize(), nếu không nó sẽ trả về NULL.

Thay đổi trong phiên bản 3.10: Bây giờ nó trả về NULL nếu được gọi trước Py_Initialize().

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Thay vào đó hãy sử dụng PyConfig_Get("executable") (sys.executable).

wchar_t *Py_GetPrefix()
Một phần của ABI ổn định.

Trả lại prefix cho các tệp độc lập với nền tảng đã cài đặt. Điều này bắt nguồn từ một số quy tắc phức tạp từ việc đặt tên chương trình với PyConfig.program_name và một số biến môi trường; ví dụ: nếu tên chương trình là '/usr/local/bin/python' thì tiền tố là '/usr/local'. Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Điều này tương ứng với biến prefix trong Makefile cấp cao nhất và đối số --prefix với tập lệnh configure tại thời điểm xây dựng. Giá trị có sẵn cho mã Python là sys.base_prefix. Nó chỉ hữu ích trên Unix. Xem thêm chức năng tiếp theo.

Hàm này không nên được gọi trước Py_Initialize(), nếu không nó sẽ trả về NULL.

Thay đổi trong phiên bản 3.10: Bây giờ nó trả về NULL nếu được gọi trước Py_Initialize().

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Thay vào đó hãy sử dụng PyConfig_Get("base_prefix") (sys.base_prefix). Sử dụng PyConfig_Get("prefix") (sys.prefix) nếu cần xử lý virtual environments.

wchar_t *Py_GetExecPrefix()
Một phần của ABI ổn định.

Trả lại exec-prefix cho các tệp platform-dependent đã cài đặt. Điều này bắt nguồn từ một số quy tắc phức tạp từ việc đặt tên chương trình với PyConfig.program_name và một số biến môi trường; ví dụ: nếu tên chương trình là '/usr/local/bin/python' thì tiền tố thực thi là '/usr/local'. Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Điều này tương ứng với biến exec_prefix trong Makefile cấp cao nhất và đối số --exec-prefix với tập lệnh configure tại thời điểm xây dựng. Giá trị có sẵn cho mã Python là sys.base_exec_prefix. Nó chỉ hữu ích trên Unix.

Bối cảnh: Tiền tố thực thi khác với tiền tố khi các tệp phụ thuộc nền tảng (chẳng hạn như tệp thực thi và thư viện dùng chung) được cài đặt trong cây thư mục khác. Trong cài đặt thông thường, các tệp phụ thuộc nền tảng có thể được cài đặt trong cây con /usr/local/plat trong khi nền tảng độc lập có thể được cài đặt trong /usr/local.

Nói chung, một nền tảng là sự kết hợp của họ phần cứng và phần mềm, ví dụ: Các máy Sparc chạy hệ điều hành Solaris 2.x được coi là cùng một nền tảng, nhưng các máy Intel chạy Solaris 2.x là một nền tảng khác và các máy Intel chạy Linux lại là một nền tảng khác. Các phiên bản chính khác nhau của cùng một hệ điều hành thường tạo thành các nền tảng khác nhau. Hệ điều hành không phải Unix lại là một câu chuyện khác; các chiến lược cài đặt trên các hệ thống đó khác nhau đến mức tiền tố và tiền tố thực thi là vô nghĩa và được đặt thành chuỗi trống. Lưu ý rằng các tệp mã byte Python được biên dịch độc lập với nền tảng (nhưng không độc lập với phiên bản Python mà chúng được biên dịch!).

Quản trị viên hệ thống sẽ biết cách định cấu hình chương trình mount hoặc automount để chia sẻ /usr/local giữa các nền tảng trong khi /usr/local/plat là một hệ thống tệp khác nhau cho mỗi nền tảng.

Hàm này không nên được gọi trước Py_Initialize(), nếu không nó sẽ trả về NULL.

Thay đổi trong phiên bản 3.10: Bây giờ nó trả về NULL nếu được gọi trước Py_Initialize().

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Thay vào đó hãy sử dụng PyConfig_Get("base_exec_prefix") (sys.base_exec_prefix). Sử dụng PyConfig_Get("exec_prefix") (sys.exec_prefix) nếu cần xử lý virtual environments.

wchar_t *Py_GetProgramFullPath()
Một phần của ABI ổn định.

Trả về tên chương trình đầy đủ của tệp thực thi Python; điều này được tính là tác dụng phụ của việc lấy đường dẫn tìm kiếm mô-đun mặc định từ tên chương trình (do PyConfig.program_name đặt). Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Giá trị có sẵn cho mã Python là sys.executable.

Hàm này không nên được gọi trước Py_Initialize(), nếu không nó sẽ trả về NULL.

Thay đổi trong phiên bản 3.10: Bây giờ nó trả về NULL nếu được gọi trước Py_Initialize().

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Thay vào đó hãy sử dụng PyConfig_Get("executable") (sys.executable).

wchar_t *Py_GetPath()
Một phần của ABI ổn định.

Trả về đường dẫn tìm kiếm mô-đun mặc định; điều này được tính toán từ tên chương trình (do PyConfig.program_name đặt) và một số biến môi trường. Chuỗi trả về bao gồm một loạt tên thư mục được phân tách bằng ký tự phân cách phụ thuộc vào nền tảng. Ký tự phân cách là ':' trên Unix và macOS, ';' trên Windows. Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Danh sách sys.path được khởi tạo với giá trị này khi khởi động trình thông dịch; nó có thể được (và thường là) được sửa đổi sau này để thay đổi đường dẫn tìm kiếm để tải các mô-đun.

Hàm này không nên được gọi trước Py_Initialize(), nếu không nó sẽ trả về NULL.

Thay đổi trong phiên bản 3.10: Bây giờ nó trả về NULL nếu được gọi trước Py_Initialize().

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Thay vào đó hãy sử dụng PyConfig_Get("module_search_paths") (sys.path).

const char *Py_GetVersion()
Một phần của ABI ổn định.

Trả về phiên bản của trình thông dịch Python này. Đây là một chuỗi trông giống như

"3.0a5+ (py3k:63103M, ngày 12 tháng 5 năm 2008, 00:53:55) \n[GCC 4.2.3]"

Từ đầu tiên (tối đa ký tự khoảng trắng đầu tiên) là phiên bản Python hiện tại; các ký tự đầu tiên là phiên bản chính và phụ cách nhau bằng dấu chấm. Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Giá trị có sẵn cho mã Python là sys.version.

Xem thêm hằng số Py_Version.

const char *Py_GetPlatform()
Một phần của ABI ổn định.

Trả về mã định danh nền tảng cho nền tảng hiện tại. Trên Unix, tên này được hình thành từ tên "chính thức" của hệ điều hành, được chuyển thành chữ thường, theo sau là số sửa đổi chính; ví dụ: đối với Solaris 2.x, còn được gọi là SunOS 5.x, giá trị là 'sunos5'. Trên macOS thì là 'darwin'. Trên Windows, đó là 'win'. Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Giá trị có sẵn cho mã Python là sys.platform.

const char *Py_GetCopyright()
Một phần của ABI ổn định.

Trả về chuỗi bản quyền chính thức cho phiên bản Python hiện tại chẳng hạn

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Giá trị có sẵn cho mã Python là sys.copyright.

const char *Py_GetCompiler()
Một phần của ABI ổn định.

Trả về dấu hiệu của trình biên dịch được sử dụng để xây dựng phiên bản Python hiện tại, trong dấu ngoặc vuông, ví dụ:

"[GCC 2.7.2.2]"

Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Giá trị có sẵn cho mã Python như một phần của biến sys.version.

const char *Py_GetBuildInfo()
Một phần của ABI ổn định.

Trả về thông tin về số thứ tự cũng như ngày giờ xây dựng của phiên bản trình thông dịch Python hiện tại, ví dụ

"#67, ngày 1 tháng 8 năm 1997, 22:34:28"

Chuỗi trả về trỏ vào bộ lưu trữ tĩnh; người gọi không nên sửa đổi giá trị của nó. Giá trị có sẵn cho mã Python như một phần của biến sys.version.

void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
Một phần của ABI ổn định.

Zz004zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.argv, PyConfig.parse_argv và PyConfig.safe_path, xem Python Initialization Configuration.

Đặt sys.argv dựa trên argc và argv. Các tham số này tương tự như các tham số được truyền cho hàm main() của chương trình với điểm khác biệt là mục nhập đầu tiên phải đề cập đến tệp tập lệnh sẽ được thực thi thay vì tệp thực thi lưu trữ trình thông dịch Python. Nếu không có tập lệnh nào được chạy thì mục nhập đầu tiên trong argv có thể là một chuỗi trống. Nếu chức năng này không khởi tạo được sys.argv, một tình trạng nghiêm trọng sẽ được báo hiệu bằng Py_FatalError().

Nếu updatepath bằng 0 thì đây là tất cả những gì chức năng thực hiện. Nếu updatepath khác 0 thì hàm cũng sửa đổi sys.path theo thuật toán sau:

  • Nếu tên của tập lệnh hiện có được chuyển vào argv[0], thì đường dẫn tuyệt đối của thư mục chứa tập lệnh sẽ được thêm vào sys.path.

  • Mặt khác (tức là, nếu argc là 0 hoặc argv[0] không trỏ đến tên tệp hiện có), một chuỗi trống sẽ được thêm vào trước sys.path, tương tự như thêm vào trước thư mục làm việc hiện tại (".").

Sử dụng Py_DecodeLocale() để giải mã chuỗi byte để lấy chuỗi wchar_t*.

Xem thêm các thành viên PyConfig.orig_argv và PyConfig.argv của Python Initialization Configuration.

Ghi chú

Chúng tôi khuyên các ứng dụng nhúng trình thông dịch Python cho các mục đích khác ngoài việc thực thi một tập lệnh duy nhất nên chuyển 0 dưới dạng updatepath và tự cập nhật sys.path nếu muốn. Xem CVE 2008-5983.

Trên các phiên bản trước 3.1.3, bạn có thể đạt được hiệu ứng tương tự bằng cách bật thủ công phần tử sys.path đầu tiên sau khi gọi PySys_SetArgv(), ví dụ: sử dụng:

PyRun_SimpleString("nhập sys; sys.path.pop(0)\n");

Added in version 3.1.3.

Không được dùng nữa kể từ phiên bản 3.11, sẽ bị xóa trong phiên bản 3.15.

void PySys_SetArgv(int argc, wchar_t **argv)
Một phần của ABI ổn định.

Zz003zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.argv và PyConfig.parse_argv, xem Python Initialization Configuration.

Hàm này hoạt động giống như PySys_SetArgvEx() với updatepath được đặt thành 1 trừ khi trình thông dịch python được khởi động bằng -I.

Sử dụng Py_DecodeLocale() để giải mã chuỗi byte để lấy chuỗi wchar_t*.

Xem thêm các thành viên PyConfig.orig_argv và PyConfig.argv của Python Initialization Configuration.

Thay đổi trong phiên bản 3.4: Giá trị updatepath phụ thuộc vào -I.

Không được dùng nữa kể từ phiên bản 3.11, sẽ bị xóa trong phiên bản 3.15.

void Py_SetPythonHome(const wchar_t *home)
Một phần của ABI ổn định.

Zz002zz này được giữ lại để tương thích ngược: thay vào đó, nên sử dụng cài đặt PyConfig.home, xem Python Initialization Configuration.

Đặt thư mục "nhà" mặc định, nghĩa là vị trí của các thư viện Python tiêu chuẩn. Xem PYTHONHOME để biết ý nghĩa của chuỗi đối số.

Đối số phải trỏ đến chuỗi ký tự kết thúc bằng 0 trong bộ lưu trữ tĩnh có nội dung sẽ không thay đổi trong suốt thời gian thực hiện chương trình. Không có mã nào trong trình thông dịch Python sẽ thay đổi nội dung của bộ lưu trữ này.

Sử dụng Py_DecodeLocale() để giải mã chuỗi byte để lấy chuỗi wchar_t*.

Không được dùng nữa kể từ phiên bản 3.11, sẽ bị xóa trong phiên bản 3.15.

wchar_t *Py_GetPythonHome()
Một phần của ABI ổn định.

Trả về "home" mặc định, nghĩa là giá trị được đặt bởi PyConfig.home hoặc giá trị của biến môi trường PYTHONHOME nếu nó được đặt.

Hàm này không nên được gọi trước Py_Initialize(), nếu không nó sẽ trả về NULL.

Thay đổi trong phiên bản 3.10: Bây giờ nó trả về NULL nếu được gọi trước Py_Initialize().

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15: Thay vào đó, hãy sử dụng PyConfig_Get("home") hoặc biến môi trường PYTHONHOME.