Objek File
**********

API ini adalah emulasi minimal Python 2 C API untuk objek file bawaan,
yang biasanya mengandalkan dukungan I/O ("FILE*") yang di-buffer dari
pustaka standar C. Dalam Python 3, file dan aliran menggunakan modul
baru "io", yang mendefinisikan beberapa lapisan di atas I/O tanpa
buffer dari sistem operasi tingkat rendah . Fungsi yang dijelaskan di
bawah ini adalah pembungkus kenyamanan C atas API baru ini, dan
sebagian besar dimaksudkan untuk pelaporan kesalahan internal di
interpreter; kode pihak ketiga disarankan untuk mengakses "io" APIs
sebagai gantinya.

PyObject* PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
    *Return value: New reference.*

   Membuat objek file Python dari deskriptor file dari file yang sudah
   dibuka *fd*. Argumen *name*, *encoding*, *errors* dan * newline*
   bisa "NULL" untuk menggunakan nilai default; *buffering* bisa *-1*
   untuk menggunakan default. *name* diabaikan dan disimpan untuk
   kompatibilitas ke belakang. Mengembalikan "NULL" jika gagal. Untuk
   penjelasan yang lebih lengkap tentang argumen, silakan merujuk ke
   dokumentasi fungsi  "io.open()".

   Peringatan:

     Karena aliran Python memiliki lapisan penyangga sendiri,
     mencampurnya dengan deskriptor file tingkat OS dapat menghasilkan
     berbagai masalah (seperti pengurutan data yang tidak terduga).

   Berubah pada versi 3.2: Abaikan atribut *name*.

int PyObject_AsFileDescriptor(PyObject *p)

   Mengembalikan deskriptor file yang terkait dengan *p* sebagai
   "int". Jika objek adalah bilangan bulat, nilainya dikembalikan.
   Jika tidak, metode objek "fileno()" akan dipanggil jika ada; metode
   harus mengembalikan bilangan bulat, yang dikembalikan sebagai nilai
   deskriptor file. Menetapkan pengecualian dan mengembalikan "-1"
   jika gagal.

PyObject* PyFile_GetLine(PyObject *p, int n)
    *Return value: New reference.*

   Setara dengan "p.readline([n])", fungsi ini membaca satu baris dari
   objek *p*. *p* dapat berupa objek file atau objek apa pun dengan
   metode "readline()". Jika *n* adalah "0", tepat satu baris terbaca,
   berapa pun panjang barisnya. Jika *n* lebih besar dari "0", tidak
   lebih dari *n* byte yang akan dibaca dari file; garis parsial dapat
   dikembalikan. Dalam kedua kasus, string kosong dikembalikan jika
   akhir file dicapai dengan segera. Jika *n* lebih kecil dari "0",
   bagaimanapun, satu baris dibaca berapa pun panjangnya, tapi
   "EOFError" dimunculkan jika akhir file dicapai dengan segera.

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

   Mengganti perilaku normal "io.open_code()" untuk meneruskan
   parameternya melalui penangan yang disediakan.

   Handler adalah fungsi dari tipe "PyObject *(*)(PyObject *path, void
   *userData)", di mana *path* dijamin menjadi "PyUnicodeObject".

   Pointer *userData* diteruskan ke fungsi hook. Karena fungsi hook
   dapat dipanggil dari runtime yang berbeda, pointer ini tidak boleh
   merujuk langsung ke status Python.

   Karena hook ini sengaja digunakan selama impor, hindari mengimpor
   modul baru selama eksekusinya kecuali jika mereka diketahui telah
   dibekukan atau tersedia di "sys.modules".

   Setelah hook diatur, hook tidak dapat dilepas atau diganti, dan
   panggilan ke "PyFile_SetOpenCodeHook()" akan gagal. Jika gagal,
   fungsi mengembalikan -1 dan mengatur pengecualian jika interpreter
   telah diinisialisasi.

   Fungsi ini aman untuk dipanggil sebelum "Py_Initialize()".

   Raises an auditing event "setopencodehook" with no arguments.

   Baru pada versi 3.8.

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

   Menulis objek *obj* ke file objek *p*. Satu-satunya tanda yang
   didukung untuk *flags* adalah "Py_PRINT_RAW"; jika diberikan,
   fungsi "str()" dari objek akan dituliskan sebagai pengganti
   "repr()". Mengembalikan "0" saat sukses atau "-1" saat gagal;
   pengecualian yang sesuai akan ditetapkan.

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

   Menulis string *s* ke file objek *p*. Mengembalikan "0" saat sukses
   atau "-1" saat gagal; pengecualian yang sesuai akan ditetapkan.
