Objetos File
************

These APIs are a minimal emulation of the Python 2 C API for built-in
file objects, which used to rely on the buffered I/O ("FILE*") support
from the C standard library.  In Python 3, files and streams use the
new "io" module, which defines several layers over the low-level
unbuffered I/O of the operating system.  The functions described below
are convenience C wrappers over these new APIs, and meant mostly for
internal error reporting in the interpreter; third-party code is
advised to access the "io" APIs instead.

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

   Create a Python file object from the file descriptor of an already
   opened file *fd*.  The arguments *name*, *encoding*, *errors* and
   *newline* can be *NULL* to use the defaults; *buffering* can be
   *-1* to use the default. *name* is ignored and kept for backward
   compatibility. Return *NULL* on failure. For a more comprehensive
   description of the arguments, please refer to the "io.open()"
   function documentation.

   Aviso:

     Como os streams do Python têm sua própria camada de buffer,
     combiná-los com os descritores de arquivo no nível do sistema
     operacional pode produzir vários problemas (como ordenação
     inesperada de dados).

   Alterado na versão 3.2: Ignora atributo *name*.

int PyObject_AsFileDescriptor(PyObject *p)

   Retorna o descritor de arquivo associado a *p* como um "int". Se o
   objeto for um inteiro, seu valor será retornado. Caso contrário, o
   método "fileno()" do objeto será chamado se existir; o método deve
   retornar um inteiro, que é retornado como o valor do descritor de
   arquivo. Define uma exceção e retorna "-1" em caso de falha.

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

   Equivalente a "p.readline([n])", esta função lê uma linha do objeto
   *p*. *p* pode ser um objeto arquivo ou qualquer objeto com um
   método "readline()". Se *n* for "0", exatamente uma linha é lida,
   independentemente do comprimento da linha. Se *n* for maior que
   "0", não mais do que *n* bytes serão lidos do arquivo; uma linha
   parcial pode ser retornada. Em ambos os casos, uma string vazia é
   retornada se o final do arquivo for alcançado imediatamente. Se *n*
   for menor que "0", entretanto, uma linha é lida independentemente
   do comprimento, mas "EOFError" é levantada se o final do arquivo
   for alcançado imediatamente.

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

   Escreve o objeto *obj* no objeto arquivo *p*. O único sinalizador
   suportado para *flags* é "Py_PRINT_RAW"; se fornecido, o "str()" do
   objeto é escrito em vez de "repr()". Retorna "0" em caso de sucesso
   ou "-1" em caso de falha; a exceção apropriada será definida.

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

   Escreve a string *s* no objeto arquivo *p*. Retorna "0" em caso de
   sucesso ou "-1" em caso de falha; a exceção apropriada será
   definida.
