Lớp cấp độ rất cao

Các hàm trong chương này sẽ cho phép bạn thực thi mã nguồn Python được cung cấp trong một tệp hoặc bộ đệm, nhưng chúng sẽ không cho phép bạn tương tác một cách chi tiết hơn với trình thông dịch.

Một số hàm này chấp nhận ký hiệu bắt đầu từ ngữ pháp làm tham số. Các biểu tượng bắt đầu có sẵn là Py_eval_input, Py_file_input, Py_single_input và Py_func_type_input. Chúng được mô tả theo các hàm chấp nhận chúng làm tham số.

Cũng lưu ý rằng một số hàm này có tham số FILE*. Một vấn đề cụ thể cần được xử lý cẩn thận là cấu trúc FILE cho các thư viện C khác nhau có thể khác nhau và không tương thích. Trong Windows (ít nhất), các tiện ích mở rộng được liên kết động có thể thực sự sử dụng các thư viện khác nhau, vì vậy cần lưu ý rằng các tham số FILE* chỉ được truyền cho các hàm này nếu chắc chắn rằng chúng được tạo bởi cùng một thư viện mà thời gian chạy Python đang sử dụng.

int PyRun_AnyFile(FILE *fp, const char *filename)

Đây là giao diện đơn giản hóa cho PyRun_AnyFileExFlags() bên dưới, để closeit được đặt thành 0 và flags được đặt thành NULL.

int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Đây là giao diện đơn giản hóa cho PyRun_AnyFileExFlags() bên dưới, để đối số closeit được đặt thành 0.

int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

Đây là giao diện đơn giản hóa cho PyRun_AnyFileExFlags() bên dưới, để đối số flags được đặt thành NULL.

int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Nếu fp đề cập đến một tệp được liên kết với một thiết bị tương tác (bàn điều khiển hoặc đầu vào đầu cuối hoặc thiết bị đầu cuối giả Unix), hãy trả về giá trị của PyRun_InteractiveLoop(), nếu không thì trả về kết quả của PyRun_SimpleFile(). filename được giải mã từ mã hóa hệ thống tập tin (sys.getfilesystemencoding()). Nếu filename là NULL thì hàm này sử dụng "???" làm tên tệp. Nếu closeit đúng, tệp sẽ bị đóng trước khi PyRun_SimpleFileExFlags() trả về.

int PyRun_SimpleString(const char *command)

Đây là giao diện đơn giản hóa cho PyRun_SimpleStringFlags() bên dưới, để đối số PyCompilerFlags* được đặt thành NULL.

int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

Thực thi mã nguồn Python từ command trong mô-đun __main__ theo đối số flags. Nếu __main__ chưa tồn tại thì nó sẽ được tạo. Trả về 0 nếu thành công hoặc -1 nếu có ngoại lệ. Nếu có lỗi thì không có cách nào lấy được thông tin ngoại lệ. Để biết ý nghĩa của flags, xem bên dưới.

Lưu ý rằng nếu một SystemExit chưa được xử lý khác được nâng lên, hàm này sẽ không trả về -1 mà thoát khỏi quá trình, miễn là PyConfig.inspect bằng 0.

int PyRun_SimpleFile(FILE *fp, const char *filename)

Đây là giao diện đơn giản hóa cho PyRun_SimpleFileExFlags() bên dưới, để closeit được đặt thành 0 và flags được đặt thành NULL.

int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

Đây là giao diện đơn giản hóa cho PyRun_SimpleFileExFlags() bên dưới, để flags được đặt thành NULL.

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Tương tự như PyRun_SimpleStringFlags(), nhưng mã nguồn Python được đọc từ fp thay vì chuỗi trong bộ nhớ. filename phải là tên của tệp, nó được giải mã từ filesystem encoding and error handler. Nếu closeit đúng, tệp sẽ bị đóng trước khi PyRun_SimpleFileExFlags() trả về.

Ghi chú

Trên Windows, fp phải được mở ở chế độ nhị phân (ví dụ: fopen(filename, "rb")). Nếu không, Python có thể không xử lý được tệp tập lệnh có dòng LF kết thúc chính xác.

int PyRun_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)

Đọc và thực thi một câu lệnh từ một tệp được liên kết với thiết bị tương tác theo đối số flags. Người dùng sẽ được nhắc sử dụng sys.ps1 và sys.ps2. filename phải là đối tượng str của Python.

Trả về 0 khi đầu vào được thực thi thành công, -1 nếu có ngoại lệ hoặc mã lỗi từ errcode.h bao gồm tệp được phân phối như một phần của Python nếu có lỗi phân tích cú pháp. (Lưu ý rằng errcode.h không được bao gồm trong Python.h, do đó phải được bao gồm cụ thể nếu cần.)

int PyRun_InteractiveOne(FILE *fp, const char *filename)

Đây là giao diện đơn giản hóa cho PyRun_InteractiveOneFlags() bên dưới, để flags được đặt thành NULL.

int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Tương tự như PyRun_InteractiveOneObject(), nhưng filename là const char*, được giải mã từ filesystem encoding and error handler.

int PyRun_InteractiveLoop(FILE *fp, const char *filename)

Đây là giao diện đơn giản hóa cho PyRun_InteractiveLoopFlags() bên dưới, để flags được đặt thành NULL.

int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Đọc và thực thi các câu lệnh từ một tệp được liên kết với thiết bị tương tác cho đến khi đạt được EOF. Người dùng sẽ được nhắc sử dụng sys.ps1 và sys.ps2. filename được giải mã từ filesystem encoding and error handler. Trả về 0 ở EOF hoặc số âm khi thất bại.

int (*PyOS_InputHook)(void)

Một phần của ABI ổn định.

Có thể được thiết lập để trỏ tới một hàm với nguyên mẫu int func(void). Hàm này sẽ được gọi khi lời nhắc thông dịch của Python sắp không hoạt động và chờ người dùng nhập từ thiết bị đầu cuối. Giá trị trả về bị bỏ qua. Việc ghi đè hook này có thể được sử dụng để tích hợp lời nhắc của trình thông dịch với các vòng lặp sự kiện khác, như được thực hiện trong Modules/_tkinter.c trong mã nguồn Python.

Thay đổi trong phiên bản 3.12: Chức năng này chỉ được gọi từ main interpreter.

char *(*PyOS_ReadlineFunctionPointer)(FILE*, FILE*, const char*)

Có thể được đặt để trỏ đến một hàm có nguyên mẫu char *func(FILE *stdin, FILE *stdout, char *prompt), ghi đè hàm mặc định được sử dụng để đọc một dòng đầu vào theo lời nhắc của trình thông dịch. Hàm này dự kiến ​​sẽ xuất ra chuỗi prompt nếu nó không phải là NULL, sau đó đọc một dòng đầu vào từ tệp đầu vào tiêu chuẩn được cung cấp, trả về chuỗi kết quả. Ví dụ: Mô-đun readline đặt hook này để cung cấp các tính năng chỉnh sửa dòng và hoàn thành tab.

Kết quả phải là một chuỗi được phân bổ bởi PyMem_RawMalloc() hoặc PyMem_RawRealloc() hoặc NULL nếu xảy ra lỗi.

Thay đổi trong phiên bản 3.4: Kết quả phải được phân bổ theo PyMem_RawMalloc() hoặc PyMem_RawRealloc(), thay vì được phân bổ theo PyMem_Malloc() hoặc PyMem_Realloc().

Thay đổi trong phiên bản 3.12: Chức năng này chỉ được gọi từ main interpreter.

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

Giá trị trả về: Tham chiếu mới.

Đây là giao diện đơn giản hóa cho PyRun_StringFlags() bên dưới, để flags được đặt thành NULL.

PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Giá trị trả về: Tham chiếu mới.

Thực thi mã nguồn Python từ str trong ngữ cảnh được chỉ định bởi các đối tượng globals và locals với các cờ trình biên dịch được chỉ định bởi flags. globals phải là một từ điển; locals có thể là bất kỳ đối tượng nào thực hiện giao thức ánh xạ. Tham số start chỉ định ký hiệu bắt đầu và phải là một trong available start symbols.

Trả về kết quả thực thi mã dưới dạng đối tượng Python hoặc NULL nếu có ngoại lệ được đưa ra.

PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

Giá trị trả về: Tham chiếu mới.

Đây là giao diện đơn giản hóa cho PyRun_FileExFlags() bên dưới, để closeit được đặt thành 0 và flags được đặt thành NULL.

PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

Giá trị trả về: Tham chiếu mới.

Đây là giao diện đơn giản hóa cho PyRun_FileExFlags() bên dưới, để flags được đặt thành NULL.

PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Giá trị trả về: Tham chiếu mới.

Đây là giao diện đơn giản hóa cho PyRun_FileExFlags() bên dưới, để closeit được đặt thành 0.

PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

Giá trị trả về: Tham chiếu mới.

Tương tự như PyRun_StringFlags(), nhưng mã nguồn Python được đọc từ fp thay vì chuỗi trong bộ nhớ. filename phải là tên của tệp, nó được giải mã từ filesystem encoding and error handler. Nếu closeit đúng, tệp sẽ bị đóng trước khi PyRun_FileExFlags() trả về.

PyObject *Py_CompileString(const char *str, const char *filename, int start)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.

Đây là giao diện đơn giản hóa cho Py_CompileStringFlags() bên dưới, để flags được đặt thành NULL.

PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)

Giá trị trả về: Tham chiếu mới.

Đây là giao diện đơn giản hóa cho Py_CompileStringExFlags() bên dưới, với optimize được đặt thành -1.

PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)

Giá trị trả về: Tham chiếu mới.

Phân tích cú pháp và biên dịch mã nguồn Python trong str, trả về đối tượng mã kết quả. Biểu tượng bắt đầu được đưa ra bởi start; điều này có thể được sử dụng để hạn chế mã có thể được biên dịch và phải là available start symbols. Tên tệp được chỉ định bởi filename được sử dụng để xây dựng đối tượng mã và có thể xuất hiện trong các thông báo theo dõi hoặc ngoại lệ SyntaxError. Điều này trả về NULL nếu mã không thể được phân tích cú pháp hoặc biên dịch.

Số nguyên optimize chỉ định mức tối ưu hóa của trình biên dịch; giá trị -1 chọn mức tối ưu hóa của trình thông dịch theo các tùy chọn -O. Các mức rõ ràng là 0 (không tối ưu hóa; __debug__ là đúng), 1 (xác nhận đã bị xóa, __debug__ là sai) hoặc 2 (chuỗi tài liệu cũng bị xóa).

Added in version 3.4.

PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)

Giá trị trả về: Tham chiếu mới.

Giống như Py_CompileStringObject(), nhưng filename là một chuỗi byte được giải mã từ filesystem encoding and error handler.

Added in version 3.2.

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.

Đây là giao diện đơn giản hóa cho PyEval_EvalCodeEx(), chỉ với đối tượng mã và các biến toàn cục và cục bộ. Các đối số khác được đặt thành NULL.

PyObject *PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.

Đánh giá một đối tượng mã được biên dịch trước, dựa trên một môi trường cụ thể để đánh giá nó. Môi trường này bao gồm một từ điển các biến toàn cục, một đối tượng ánh xạ của các biến cục bộ, mảng đối số, từ khóa và giá trị mặc định, một từ điển các giá trị mặc định cho các đối số keyword-only và một bộ ô đóng.

PyObject *PyEval_EvalFrame(PyFrameObject *f)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.

Đánh giá một khung thực hiện. Đây là giao diện đơn giản hóa cho PyEval_EvalFrameEx() để có khả năng tương thích ngược.

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.

Đây là chức năng chính, chưa được chỉnh sửa của việc giải thích Python. Đối tượng mã được liên kết với khung thực thi f được thực thi, diễn giải mã byte và thực hiện các lệnh gọi nếu cần. Tham số throwflag bổ sung hầu hết có thể bị bỏ qua - nếu đúng, thì nó sẽ gây ra một ngoại lệ ngay lập tức; cái này được sử dụng cho các phương thức throw() của các đối tượng trình tạo.

Thay đổi trong phiên bản 3.4: Hàm này hiện bao gồm một xác nhận gỡ lỗi để giúp đảm bảo rằng nó không âm thầm loại bỏ một ngoại lệ đang hoạt động.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

Hàm này thay đổi cờ của khung đánh giá hiện tại và trả về true nếu thành công, sai nếu thất bại.

struct PyCompilerFlags

Đây là cấu trúc được sử dụng để giữ các cờ của trình biên dịch. Trong trường hợp mã chỉ được biên dịch, nó được chuyển dưới dạng int flags và trong trường hợp mã đang được thực thi, nó được chuyển dưới dạng PyCompilerFlags *flags. Trong trường hợp này, from __future__ import có thể sửa đổi flags.

Bất cứ khi nào PyCompilerFlags *flags là NULL, cf_flags được coi là bằng 0 và mọi sửa đổi do from __future__ import đều bị loại bỏ.

int cf_flags

Cờ trình biên dịch.

int cf_feature_version

cf_feature_version là phiên bản Python nhỏ. Nó nên được khởi tạo thành PY_MINOR_VERSION.

Trường này bị bỏ qua theo mặc định, nó được sử dụng khi và chỉ khi cờ PyCF_ONLY_AST được đặt trong cf_flags.

Thay đổi trong phiên bản 3.8: Đã thêm trường cf_feature_version.

Các cờ trình biên dịch có sẵn có thể truy cập được dưới dạng macro:

PyCF_ALLOW_TOP_LEVEL_AWAIT

PyCF_ONLY_AST

PyCF_OPTIMIZED_AST

PyCF_TYPE_COMMENTS

Xem compiler flags trong tài liệu của mô-đun Python ast, xuất các hằng số này dưới cùng tên.

Cờ "PyCF" ở trên có thể được kết hợp với cờ "CO_FUTURE" chẳng hạn như CO_FUTURE_ANNOTATIONS để bật các tính năng thường có thể chọn bằng future statements. Xem Cờ đối tượng mã để biết danh sách đầy đủ.

Biểu tượng bắt đầu có sẵn

int Py_eval_input

Ký hiệu bắt đầu từ ngữ pháp Python cho các biểu thức biệt lập; để sử dụng với Py_CompileString().

int Py_file_input

Ký hiệu bắt đầu từ ngữ pháp Python cho chuỗi câu lệnh được đọc từ một tệp hoặc nguồn khác; để sử dụng với Py_CompileString(). Đây là ký hiệu được sử dụng khi biên dịch mã nguồn Python dài tùy ý.

int Py_single_input

Ký hiệu bắt đầu trong ngữ pháp Python cho một câu lệnh; để sử dụng với Py_CompileString(). Đây là biểu tượng được sử dụng cho vòng lặp thông dịch tương tác.

int Py_func_type_input

Ký hiệu bắt đầu từ ngữ pháp Python cho một loại hàm; để sử dụng với Py_CompileString(). Điều này được sử dụng để phân tích "nhận xét loại chữ ký" từ PEP 484.

Điều này yêu cầu phải đặt cờ PyCF_ONLY_AST.

Xem thêm

• ast.FunctionType

• PEP 484

Added in version 3.8.

Hiệu ứng ngăn xếp

Xem thêm

dis.stack_effect()

PY_INVALID_STACK_EFFECT

Giá trị trọng điểm thể hiện hiệu ứng ngăn xếp không hợp lệ.

Điều này hiện tương đương với INT_MAX.

Added in version 3.8.

int PyCompile_OpcodeStackEffect(int opcode, int oparg)

Tính hiệu ứng ngăn xếp của opcode với đối số oparg.

Nếu thành công, hàm này trả về hiệu ứng ngăn xếp; nếu thất bại, điều này sẽ trả về PY_INVALID_STACK_EFFECT.

Added in version 3.4.

int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)

Tương tự như PyCompile_OpcodeStackEffect(), nhưng không bao gồm hiệu ứng nhảy nếu jump bằng 0.

Nếu jump là 0, điều này sẽ không bao gồm hiệu ứng nhảy, nhưng nếu jump là 1 hoặc -1, điều này sẽ bao gồm nó.

Nếu thành công, hàm này trả về hiệu ứng ngăn xếp; nếu thất bại, điều này sẽ trả về PY_INVALID_STACK_EFFECT.

Added in version 3.8.