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.