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" e "Py_func_type_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_InteractiveOneObject(FILE *fp, PyObject *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* deve ser
   um objeto "str" Python.

   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_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)

   Semelhante a "PyRun_InteractiveOneObject()", mas *filename* é um
   const char*, que é decodificado a partir do *tratador de erros e
   codificação do sistema de arquivos*.

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.*

   Execut 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 símbolos iniciais disponíveis.

   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 símbolos iniciais disponíveis. 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.

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.


Símbolos iniciais disponíveis
=============================

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.

int Py_func_type_input

   O símbolo inicial da gramática Python para um tipo de função; para
   uso com "Py_CompileString()". É usado para analisar "comentários de
   tipo de assinatura" de **PEP 484**.

   Isso requer que o sinalizador "PyCF_ONLY_AST" seja definido.

   Ver também:

     * "ast.FunctionType"

     * **PEP 484**

   Adicionado na versão 3.8.


Stack Effects
=============

Ver também: "dis.stack_effect()"

PY_INVALID_STACK_EFFECT

   Sentinel value representing an invalid stack effect.

   This is currently equivalent to "INT_MAX".

   Adicionado na versão 3.8.

int PyCompile_OpcodeStackEffect(int opcode, int oparg)

   Calcula o efeito que o *opcode* com argumento *oparg* tem na pilha.

   On success, this function returns the stack effect; on failure,
   this returns "PY_INVALID_STACK_EFFECT".

   Adicionado na versão 3.4.

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

   Similar to "PyCompile_OpcodeStackEffect()", but don't include the
   stack effect of jumping if *jump* is zero.

   If *jump* is "0", this will not include the stack effect of
   jumping, but if *jump* is "1" or "-1", this will include it.

   On success, this function returns the stack effect; on failure,
   this returns "PY_INVALID_STACK_EFFECT".

   Adicionado na versão 3.8.
