Đối tượng tệp

Các API này là một mô phỏng tối thiểu của Python 2 C API dành cho các đối tượng tệp tích hợp, vốn dựa vào hỗ trợ I/O (FILE*) được đệm từ thư viện chuẩn C. Trong Python 3, các tệp và luồng sử dụng mô-đun io mới, mô-đun này xác định một số lớp trên I/O không có bộ đệm cấp thấp của hệ điều hành. Các hàm được mô tả bên dưới là các trình bao bọc C tiện lợi trên các API mới này và chủ yếu dùng để báo cáo lỗi nội bộ trong trình thông dịch; Thay vào đó, mã của bên thứ ba nên truy cập vào API io.

PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)

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

Tạo một đối tượng tệp Python từ bộ mô tả tệp của tệp fd đã mở. Các đối số name, encoding, errors và newline có thể là NULL để sử dụng các giá trị mặc định; buffering có thể là -1 để sử dụng mặc định. name bị bỏ qua và được giữ lại để tương thích ngược. Trả về NULL khi thất bại. Để có mô tả toàn diện hơn về các đối số, vui lòng tham khảo tài liệu về hàm io.open().

Cảnh báo

Vì các luồng Python có lớp đệm riêng nên việc trộn chúng với các bộ mô tả tệp cấp hệ điều hành có thể tạo ra nhiều vấn đề khác nhau (chẳng hạn như thứ tự dữ liệu không mong muốn).

Thay đổi trong phiên bản 3.2: Bỏ qua thuộc tính name.

int PyObject_AsFileDescriptor(PyObject *p)

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

Trả về bộ mô tả tệp được liên kết với p dưới dạng int. Nếu đối tượng là số nguyên thì giá trị của nó sẽ được trả về. Nếu không, phương thức fileno() của đối tượng sẽ được gọi nếu nó tồn tại; phương thức phải trả về một số nguyên, số nguyên này được trả về dưới dạng giá trị mô tả tệp. Đặt một ngoại lệ và trả về -1 khi thất bại.

PyObject *PyFile_GetLine(PyObject *p, int n)

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

Tương đương với p.readline([n]), hàm này đọc một dòng từ đối tượng p. p có thể là một đối tượng tệp hoặc bất kỳ đối tượng nào có phương thức readline(). Nếu n là 0, chính xác một dòng sẽ được đọc, bất kể độ dài của dòng. Nếu n lớn hơn 0, không quá n byte sẽ được đọc từ tệp; một phần dòng có thể được trả lại. Trong cả hai trường hợp, một chuỗi trống sẽ được trả về nếu đến cuối tệp ngay lập tức. Tuy nhiên, nếu n nhỏ hơn 0, một dòng sẽ được đọc bất kể độ dài, nhưng EOFError sẽ được nâng lên nếu đạt đến cuối tệp ngay lập tức.

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

Ghi đè hành vi bình thường của io.open_code() để truyền tham số của nó thông qua trình xử lý được cung cấp.

Zz000zz là một hàm thuộc loại:

typedef PyObject *(*Py_OpenCodeHookFunction)(PyObject*, void*)

Tương đương với PyObject *(*)(PyObject *path, void *userData), trong đó path được đảm bảo là PyUnicodeObject.

Con trỏ userData được truyền vào hàm hook. Vì các hàm hook có thể được gọi từ các thời gian chạy khác nhau nên con trỏ này không được tham chiếu trực tiếp đến trạng thái Python.

Vì hook này được cố ý sử dụng trong quá trình nhập, nên hãy tránh nhập các mô-đun mới trong quá trình thực thi nó trừ khi chúng được xác định là bị đóng băng hoặc có sẵn trong sys.modules.

Khi một hook đã được thiết lập, nó không thể được gỡ bỏ hoặc thay thế và các cuộc gọi sau này tới PyFile_SetOpenCodeHook() sẽ không thành công. Khi thất bại, hàm trả về -1 và đặt ngoại lệ nếu trình thông dịch đã được khởi tạo.

Chức năng này an toàn để gọi trước Py_Initialize().

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

Added in version 3.8.

PyObject *PyFile_OpenCodeObject(PyObject *path)

Mở path với chế độ 'rb'. path phải là đối tượng str của Python. Hoạt động của chức năng này có thể bị PyFile_SetOpenCodeHook() ghi đè để cho phép xử lý trước văn bản.

Điều này tương tự với io.open_code() trong Python.

Nếu thành công, hàm này trả về strong reference cho đối tượng tệp Python. Nếu thất bại, hàm này trả về NULL với một bộ ngoại lệ.

Added in version 3.8.

PyObject *PyFile_OpenCode(const char *path)

Tương tự như PyFile_OpenCodeObject(), nhưng path là const char* được mã hóa UTF-8.

Added in version 3.8.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

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

Viết đối tượng obj vào tệp đối tượng p. Cờ được hỗ trợ duy nhất cho flags là Py_PRINT_RAW; nếu được cung cấp, str() của đối tượng sẽ được viết thay vì repr().

Nếu obj là NULL thì viết chuỗi "<NULL>".

Trả về 0 nếu thành công hoặc -1 nếu thất bại; ngoại lệ thích hợp sẽ được thiết lập.

int PyFile_WriteString(const char *s, PyObject *p)

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

Viết chuỗi s vào tệp đối tượng p. Trả về 0 nếu thành công hoặc -1 nếu thất bại; ngoại lệ thích hợp sẽ được thiết lập.

API không được dùng nữa

Đây là các API soft deprecated được đưa vào C API của Python do nhầm lẫn. Chúng chỉ được ghi lại để đảm bảo tính đầy đủ; thay vào đó hãy sử dụng các API PyFile* khác.

PyObject *PyFile_NewStdPrinter(int fd)

Thay vào đó, hãy sử dụng PyFile_FromFd() với giá trị mặc định (fd, NULL, "w", -1, NULL, NULL, NULL, 0).

PyTypeObject PyStdPrinter_Type

Loại đối tượng giống như tệp được sử dụng nội bộ khi khởi động Python khi io chưa có sẵn. Thay vào đó, hãy sử dụng Python open() hoặc PyFile_FromFd() để tạo các đối tượng tệp.