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 como0
e flags definido comoNULL
.
-
int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
Esta é uma interface simplificada para
PyRun_AnyFileExFlags()
abaixo, deixando o argumento closeit definido como0
.
-
int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)¶
Esta é uma interface simplificada para
PyRun_AnyFileExFlags()
abaixo, deixando o argumento flags definido comoNULL
.
-
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 dePyRun_SimpleFile()
. filename é decodificado da codificação do sistema de arquivos (sys.getfilesystemencoding()
). Se filename forNULL
, esta função usa"???"
como o nome do arquivo. Se closeit for true, o arquivo será fechado antes dePyRun_SimpleFileExFlags()
retornar.
-
int PyRun_SimpleString(const char *command)¶
Esta é uma interface simplificada para
PyRun_SimpleStringFlags()
abaixo, deixando o argumentoPyCompilerFlags
* definido comoNULL
.
-
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. Retorna0
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 quePyConfig.inspect
seja zero.
-
int PyRun_SimpleFile(FILE *fp, const char *filename)¶
Esta é uma interface simplificada para
PyRun_SimpleFileExFlags()
abaixo, deixando closeit definido como0
e flags definido comoNULL
.
-
int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)¶
Esta é uma interface simplificada para
PyRun_SimpleFileExFlags()
abaixo, deixando o flags definido comoNULL
.
-
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 quePyRun_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 comoNULL
.
-
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
esys.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ãoerrcode.h
distribuído como parte do Python se houve um erro de análise. (Observe queerrcode.h
não é incluído porPython.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 comoNULL
.
-
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
esys.ps2
. filename é decodificado a partir do tratador de erros e codificação do sistema de arquivos. Retorna0
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 emModules/_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 forNULL
e, em seguida, leia uma linha de entrada do arquivo de entrada padrão fornecido, retornando a string resultante. Por exemplo, o móduloreadline
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()
ouPyMem_RawRealloc()
, ouNULL
se ocorrer um erro.Alterado na versão 3.4: O resultado deve ser alocado por
PyMem_RawMalloc()
ouPyMem_RawRealloc()
, em vez de ser alocado porPyMem_Malloc()
ouPyMem_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 comoNULL
.
-
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 token de início que deve ser usado para analisar o código-fonte.
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 como0
e flags definido comoNULL
.
-
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 comoNULL
.
-
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 como0
.
-
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 quePyRun_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 comoNULL
.
-
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 compil o código-fonte Python em str, retornando o objeto de código resultante. O token 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
ouPy_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çãoSyntaxError
. Isso retornaNULL
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ão0
(nenhuma otimização;__debug__
é verdadeiro),1
(instruçõesassert
são removidas,__debug__
é falso) ou2
(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 comoNULL
.
-
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 comoPyCompilerFlags *flags
. Neste caso,from __future__ import
pode modificar flags.Sempre que
PyCompilerFlags *flags
forNULL
,cf_flags
é tratado como igual a0
, e qualquer modificação devido afrom __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 emcf_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.
-
int cf_flags¶