A camada de nível muito alto
****************************

As funções neste capítulo permitirão que você execute um código-fonte
Python fornecido em um arquivo ou buffer, mas não permitirão que você
interaja de forma mais detalhada com o interpretador.

Várias dessas funções aceitam um símbolo de início da gramática como
parâmetro. Os símbolos de início disponíveis são "Py_eval_input",
"Py_file_input" e "Py_single_input". Eles são descritos seguindo as
funções que os aceitam como parâmetros.

Note também que várias dessas funções aceitam parâmetros FILE*. Um
problema específico que precisa ser tratado com cuidado é que a
estrutura "FILE" para diferentes bibliotecas C pode ser diferente e
incompatível. No Windows (pelo menos), é possível que extensões
vinculadas dinamicamente usem bibliotecas diferentes, então deve-se
tomar cuidado para que os parâmetros FILE* sejam passados para essas
funções somente se for certo que elas foram criadas pela mesma
biblioteca que o tempo de execução do Python está usando.

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

   Esta é uma interface simplificada para "PyRun_AnyFileExFlags()"
   abaixo, deixando *closeit* definido como "0" e *flags* definido
   como "NULL".

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

   Esta é uma interface simplificada para "PyRun_AnyFileExFlags()"
   abaixo, deixando o argumento *closeit* definido como "0".

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

   Esta é uma interface simplificada para "PyRun_AnyFileExFlags()"
   abaixo, deixando o argumento *flags* definido como "NULL".

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

   Se *fp* se referir a um arquivo associado a um dispositivo
   interativo (entrada de console ou terminal ou pseudo-terminal
   Unix), retorna o valor de "PyRun_InteractiveLoop()", caso
   contrário, retorna o resultado de "PyRun_SimpleFile()". *filename*
   é decodificado da codificação do sistema de arquivos
   ("sys.getfilesystemencoding()"). Se *filename* for "NULL", esta
   função usa ""???"" como o nome do arquivo. Se *closeit* for
   verdadeiro, o arquivo será fechado antes de
   "PyRun_SimpleFileExFlags()" retornar.

int PyRun_SimpleString(const char *command)

   Esta é uma interface simplificada para "PyRun_SimpleStringFlags()"
   abaixo, deixando o argumento "PyCompilerFlags"* definido como
   "NULL".

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

   Executa o código-fonte Python de *command* no módulo "__main__" de
   acordo com o argumento *flags*. Se "__main__" ainda não existir,
   ele será criado. Retorna "0" em caso de sucesso ou "-1" se uma
   exceção foi gerada. Se houve um erro, não há como obter as
   informações da exceção. Para o significado de *flags*, veja abaixo.

   Observe que se uma exceção "SystemExit" não tratada for levantada,
   esta função não retornará "-1", mas sairá do processo, desde que
   "PyConfig.inspect" seja zero.

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

   Esta é uma interface simplificada para "PyRun_SimpleFileExFlags()"
   abaixo, deixando *closeit* definido como "0" e *flags* definido
   como "NULL".

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

   Esta é uma interface simplificada para "PyRun_SimpleFileExFlags()"
   abaixo, deixando o *flags* definido como "NULL".

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

   Semelhante a "PyRun_SimpleStringFlags()", mas o código-fonte Python
   é lido de *fp* em vez de uma string na memória. *filename* deve ser
   o nome do arquivo, ele é decodificado a partir do *tratador de
   erros e codificação do sistema de arquivos*. Se *closeit* for true,
   o arquivo será fechado antes que "PyRun_SimpleFileExFlags()"
   retorne.

   Nota:

     No Windows, *fp* deve ser aberto como modo binário (por exemplo,
     "fopen(filename, "rb")"). Caso contrário, o Python pode não
     manipular corretamente o arquivo de script com final de linha LF.

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

   Esta é uma interface simplificada para
   "PyRun_InteractiveOneFlags()" abaixo, deixando *flags* definido
   como "NULL".

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

   Lê e executa uma única instrução de um arquivo associado a um
   dispositivo interativo de acordo com o argumento *flags*. O usuário
   será solicitado usando "sys.ps1" e "sys.ps2". *filename* é
   decodificado a partir do *tratador de erros e codificação do
   sistema de arquivos*.

   Retorna "0" quando a entrada foi executada com sucesso, "-1" se
   houve uma exceção ou um código de erro do arquivo de inclusão
   "errcode.h" distribuído como parte do Python se houve um erro de
   análise. (Observe que "errcode.h" não é incluído por "Python.h",
   então deve ser incluído especificamente se necessário.)

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

   Esta é uma interface simplificada para
   "PyRun_InteractiveLoopFlags()" abaixo, deixando *flags* definido
   como "NULL".

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

   Lê e executa instruções de um arquivo associado a um dispositivo
   interativo até que o EOF seja atingido. O usuário será consultado
   usando "sys.ps1" e "sys.ps2". *filename* é decodificado a partir do
   *tratador de erros e codificação do sistema de arquivos*. Retorna
   "0" no EOF ou um número negativo em caso de falha.

int (*PyOS_InputHook)(void)
    * Parte da ABI Estável.*

   Pode ser definido para apontar para uma função com o protótipo "int
   func(void)". A função será chamada quando o prompt do interpretador
   do Python estiver prestes a ficar ocioso e aguardar a entrada do
   usuário no terminal. O valor de retorno é ignorado. A substituição
   deste hook pode ser usada para integrar o prompt do interpretador
   com outros laços de eventos, como feito em "Modules/_tkinter.c" no
   código-fonte do Python.

   Alterado na versão 3.12: Esta função só é chamada pelo
   interpretador principal.

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

   Pode ser definido para apontar para uma função com o protótipo
   "char *func(FILE *stdin, FILE *stdout, char *prompt)", substituindo
   a função padrão usada para ler uma única linha de entrada no prompt
   do interpretador. Espera-se que a função produza a string *prompt*
   se não for "NULL" e, em seguida, leia uma linha de entrada do
   arquivo de entrada padrão fornecido, retornando a string
   resultante. Por exemplo, o módulo "readline" define este gancho
   para fornecer recursos de edição de linha e preenchimento de
   tabulação.

   O resultado deve ser uma string alocada por "PyMem_RawMalloc()" ou
   "PyMem_RawRealloc()", ou "NULL" se ocorrer um erro.

   Alterado na versão 3.4: O resultado deve ser alocado por
   "PyMem_RawMalloc()" ou "PyMem_RawRealloc()", em vez de ser alocado
   por "PyMem_Malloc()" ou "PyMem_Realloc()".

   Alterado na versão 3.12: Esta função só é chamada pelo
   interpretador principal.

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
    *Retorna valor: Nova referência.*

   Esta é uma interface simplificada para "PyRun_StringFlags()"
   abaixo, deixando *flags* definido como "NULL".

PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    *Retorna valor: Nova referência.*

   Executa o código-fonte Python de *str* no contexto especificado
   pelos objetos *globals* e *locals* com os sinalizadores do
   compilador especificados por *flags*. *globals* deve ser um
   dicionário; *locals* pode ser qualquer objeto que implemente o
   protocolo de mapeamento. O parâmetro *start* especifica o símbolo
   inicial e deve ser um dos seguintes: "Py_eval_input",
   "Py_file_input" ou "Py_single_input".

   Retorna o resultado da execução do código como um objeto Python, ou
   "NULL" se uma exceção foi levantada.

PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
    *Retorna valor: Nova referência.*

   Esta é uma interface simplificada para "PyRun_FileExFlags()"
   abaixo, deixando *closeit* definido como "0" e *flags* definido
   como "NULL".

PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
    *Retorna valor: Nova referência.*

   Esta é uma interface simplificada para "PyRun_FileExFlags()"
   abaixo, deixando *flags* definido como "NULL".

PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    *Retorna valor: Nova referência.*

   Esta é uma interface simplificada para "PyRun_FileExFlags()"
   abaixo, deixando *closeit* definido como "0".

PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
    *Retorna valor: Nova referência.*

   Semelhante a "PyRun_StringFlags()", mas o código-fonte Python é
   lido de *fp* em vez de uma string na memória. *filename* deve ser o
   nome do arquivo, ele é decodificado a partir do *tratador de erros
   e codificação do sistema de arquivos*. Se *closeit* for true, o
   arquivo será fechado antes que "PyRun_FileExFlags()" retorne.

PyObject *Py_CompileString(const char *str, const char *filename, int start)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Esta é uma interface simplificada para "Py_CompileStringFlags()"
   abaixo, deixando *flags* definido como "NULL".

PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
    *Retorna valor: Nova referência.*

   Esta é uma interface simplificada para "Py_CompileStringExFlags()"
   abaixo, com *optimize* definido como "-1".

PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
    *Retorna valor: Nova referência.*

   Analisa e compila o código-fonte Python em *str*, retornando o
   objeto de código resultante. O símbolo inicial é fornecido por
   *start*; isso pode ser usado para restringir o código que pode ser
   compilado e deve ser "Py_eval_input", "Py_file_input" ou
   "Py_single_input". O nome do arquivo especificado por *filename* é
   usado para construir o objeto de código e pode aparecer em
   tracebacks ou mensagens de exceção "SyntaxError". Isso retorna
   "NULL" se o código não puder ser analisado ou compilado.

   O inteiro *optimize* especifica o nível de otimização do
   compilador; um valor de "-1" seleciona o nível de otimização do
   interpretador dado pela opção "-O". Níveis explícitos são "0"
   (nenhuma otimização; "__debug__" é verdadeiro), "1" (instruções
   "assert" são removidas, "__debug__" é falso) ou "2" (strings de
   documentação também são removidas).

   Adicionado na versão 3.4.

PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
    *Retorna valor: Nova referência.*

   Como "Py_CompileStringObject()", mas *filename* é uma string de
   bytes decodificada a partir do *tratador de erros e codificação do
   sistema de arquivos*.

   Adicionado na versão 3.2.

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Esta é uma interface simplificada para "PyEval_EvalCodeEx()", com
   apenas o objeto código e variáveis locais e globais. Os outros
   argumentos são definidos como "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)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Avalia um objeto código pré-compilado, dado um ambiente particular
   para sua avaliação. Este ambiente consiste em um dicionário de
   variáveis globais, um objeto mapeamento de variáveis locais,
   vetores de argumentos, nomeados e padrões, um dicionário de valores
   padrões para argumentos somente-nomeados e uma tupla de clausura de
   células.

PyObject *PyEval_EvalFrame(PyFrameObject *f)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Avalia um quadro de execução. Esta é uma interface simplificada
   para "PyEval_EvalFrameEx()", para retrocompatibilidade.

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Esta é a função principal e sem retoques da interpretação Python. O
   objeto código associado ao quadro de execução *f* é executado,
   interpretando bytecode e executando chamadas conforme necessário. O
   parâmetro adicional *throwflag* pode ser ignorado na maioria das
   vezes - se verdadeiro, ele faz com que uma exceção seja levantada
   imediatamente; isso é usado para os métodos "throw()" de objetos
   geradores.

   Alterado na versão 3.4: Essa função agora inclui uma asserção de
   depuração para ajudar a garantir que ela não descarte
   silenciosamente uma exceção ativa.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

   Esta função altera os sinalizadores do quadro de avaliação atual e
   retorna verdadeiro em caso de sucesso e falso em caso de falha.

int Py_eval_input

   O símbolo inicial da gramática Python para expressões isoladas;
   para uso com "Py_CompileString()".

int Py_file_input

   O símbolo de início da gramática Python para sequências de
   instruções conforme lidas de um arquivo ou outra fonte; para uso
   com "Py_CompileString()". Este é o símbolo a ser usado ao compilar
   código-fonte Python arbitrariamente longo.

int Py_single_input

   O símbolo de início da gramática Python para uma única declaração;
   para uso com "Py_CompileString()". Este é o símbolo usado para o
   laço do interpretador interativo.

struct PyCompilerFlags

   Esta é a estrutura usada para manter os sinalizadores do
   compilador. Em casos onde o código está apenas sendo compilado, ele
   é passado como "int flags", e em casos onde o código está sendo
   executado, ele é passado como "PyCompilerFlags *flags". Neste caso,
   "from __future__ import" pode modificar *flags*.

   Sempre que "PyCompilerFlags *flags" for "NULL", "cf_flags" é
   tratado como igual a "0", e qualquer modificação devido a "from
   __future__ import" é descartada.

   int cf_flags

      Sinalizadores do compilador.

   int cf_feature_version

      *cf_feature_version* é a versão secundária do Python. Deve ser
      inicializada como "PY_MINOR_VERSION".

      O campo é ignorado por padrão, ele é usado se e somente se o
      sinalizador "PyCF_ONLY_AST" estiver definido em "cf_flags".

   Alterado na versão 3.8: Adicionado campo *cf_feature_version*.

   Os sinalizadores do compilador disponíveis são acessíveis como
   macros:

   PyCF_ALLOW_TOP_LEVEL_AWAIT
   PyCF_ONLY_AST
   PyCF_OPTIMIZED_AST
   PyCF_TYPE_COMMENTS

      Veja sinalizadores do compilador na documentação do módulo
      Python "ast", que exporta essas constantes com os mesmos nomes.

   Os sinalizadores ""PyCF"" acima podem ser combinados com
   sinalizadores ""CO_FUTURE"", como "CO_FUTURE_ANNOTATIONS", para
   habilitar recursos normalmente selecionáveis usando instruções
   future. Consulte Sinalizadores de objetos código para obter uma
   lista completa.
