Utilitários do sistema operacional

PyObject *PyOS_FSPath(PyObject *path)

Retorna valor: Nova referência. Parte da ABI Estável desde a versão 3.6.

Retorna a representação do sistema de arquivos para path. Se o objeto for um objeto str ou bytes, então uma nova referência forte é retornada. Se o objeto implementa a interface os.PathLike, então __fspath__() é retornado desde que seja um objeto str ou bytes. Caso contrário, TypeError é levantada e NULL é retornado.

Adicionado na versão 3.6.

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

Retorna verdadeiro (não zero) se o arquivo padrão de E/S fp com o nome filename for considerado interativo. Este é o caso dos arquivos para os quais isatty(fileno(fp)) é verdade. Se PyConfig.interactive for não zero, esta função também retorna true se o ponteiro filename for NULL ou se o nome for igual a uma das strings '<stdin>' ou '???'.

Esta função não deve ser chamada antes da inicialização do Python.

void PyOS_BeforeFork()

Parte da ABI Estável on platforms with fork() desde a versão 3.7.

Função para preparar algum estado interno antes de ser feito um fork do processo. Isso deve ser chamado antes de chamar fork() ou qualquer função semelhante que clone o processo atual. Disponível apenas em sistemas onde fork() é definido.

Aviso

A chamada C fork() só deve ser feita a partir da thread “main” (do interpretador “main”). O mesmo vale para PyOS_BeforeFork().

Adicionado na versão 3.7.

void PyOS_AfterFork_Parent()

Parte da ABI Estável on platforms with fork() desde a versão 3.7.

Função para atualizar algum estado interno depois de ser feito um fork do processo. Isso deve ser chamado a partir do processo pai depois de chamar fork() ou qualquer função semelhante que clone o processo atual, independentemente da clonagem do processo ter sido bem-sucedida ou não. Disponível apenas em sistemas onde fork() é definido.

Aviso

A chamada C fork() só deve ser feita a partir da thread “main” (do interpretador “main”). O mesmo vale para PyOS_AfterFork_Parent().

Adicionado na versão 3.7.

void PyOS_AfterFork_Child()

Parte da ABI Estável on platforms with fork() desde a versão 3.7.

Função para atualizar o estado interno do interpretador depois de ser feito um fork do processo. Isso deve ser chamado a partir do processo filho depois de chamar fork() ou qualquer função semelhante que clone o processo atual, se houver alguma chance do processo ter uma chamada de retorno para o interpretador Python. Disponível apenas em sistemas onde fork() é definido.

Aviso

A chamada C fork() só deve ser feita a partir da thread “main” (do interpretador “main”). O mesmo vale para PyOS_AfterFork_Child().

Adicionado na versão 3.7.

Ver também

os.register_at_fork() permite registrar funções personalizadas do Python para serem chamadas por PyOS_BeforeFork(), PyOS_AfterFork_Parent() e PyOS_AfterFork_Child().

void PyOS_AfterFork()

Parte da ABI Estável on platforms with fork().

Função para atualizar algum estado interno após ser feito um fork de processo; isso deve ser chamado no novo processo se o interpretador do Python continuar a ser usado. Se um novo executável é carregado no novo processo, esta função não precisa ser chamada.

Descontinuado desde a versão 3.7: Esta função foi sucedida por PyOS_AfterFork_Child().

int PyOS_CheckStack()

Parte da ABI Estável on platforms with USE_STACKCHECK desde a versão 3.7.

Retorna verdadeiro quando o interpretador fica sem espaço na pilha. Esta é uma verificação confiável, mas só está disponível quando USE_STACKCHECK é definido (atualmente em certas versões do Windows usando o compilador Microsoft Visual C++). USE_STACKCHECK será definido automaticamente; você nunca deve alterar a definição em seu próprio código.

typedef void (*PyOS_sighandler_t)(int)

Parte da ABI Estável.

PyOS_sighandler_t PyOS_getsig(int i)

Parte da ABI Estável.

Retorna o manipulador de sinal atual para o sinal i. Este é um invólucro fino em torno de sigaction() ou signal(). Não chame essas funções diretamente!

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Parte da ABI Estável.

Define o manipulador de sinal para o sinal i como h; retornar o manipulador de sinal antigo. Este é um invólucro fino em torno de sigaction() ou signal(). Não chame essas funções diretamente!

int PyOS_InterruptOccurred(void)

Parte da ABI Estável.

Verifica se um sinal SIGINT foi recebido.

Retorna 1 se um SIGINT ocorreu e limpa o sinalizador de sinal, ou 0 caso contrário.

Na maioria dos casos, você deve preferir PyErr_CheckSignals() em vez desta função. PyErr_CheckSignals() invoca os manipuladores de sinal apropriados para todos os sinais pendentes, permitindo que o código Python lide com o sinal corretamente. Esta função detecta apenas SIGINT e não invoca nenhum manipulador de sinal do Python.

This function is async-signal-safe and this function cannot fail. The caller must hold an attached thread state.

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)

Parte da ABI Estável desde a versão 3.7.

Aviso

Esta função não deve ser chamada diretamente: use a API PyConfig com a função PyConfig_SetBytesString() que garante que Python esteja pré-inicializado.

Esta função não deve ser chamada antes de Python estar pré-inicializado e para que a localidade LC_CTYPE seja configurada corretamente: consulte a função Py_PreInitialize().

Decodifica uma string de bytes do tratador de erros e codificação do sistema de arquivos. Se o tratador de erros for o tratador de errors surrogateescape, bytes não decodificáveis são decodificados como caracteres no intervalo U+DC80..U+DCFF; e se uma string de bytes puder ser decodificada como um caractere substituto, os bytes são escapados usando o tratador de erros surrogateescape em vez de decodificá-los.

Retorna um ponteiro para uma string de caracteres largos recém-alocada, usa PyMem_RawFree() para liberar a memória. Se o tamanho não for NULL, escreve o número de caracteres largos excluindo o caractere nulo em *size

Retorna NULL em erro de decodificação ou erro de alocação de memória. Se size não for NULL, *size é definido como (size_t)-1 em erro de memória ou definido como (size_t)-2 em erro de decodificação.

tratador de erros e codificação do sistema de arquivos são selecionados por PyConfig_Read(): veja os membros filesystem_encoding e filesystem_errors de PyConfig.

Erros de decodificação nunca devem acontecer, a menos que haja um bug na biblioteca C.

Use a função Py_EncodeLocale() para codificar a string de caracteres de volta para uma string de bytes.

Ver também

As funções PyUnicode_DecodeFSDefaultAndSize() e PyUnicode_DecodeLocaleAndSize().

Adicionado na versão 3.5.

Alterado na versão 3.7: A função agora usa a codificação UTF-8 no Modo UTF-8 do Python.

Alterado na versão 3.8: A função agora usa a codificação UTF-8 no Windows se PyPreConfig.legacy_windows_fs_encoding for zero;

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

Parte da ABI Estável desde a versão 3.7.

Codifica uma string de caracteres largos para o tratador de erros e codificação do sistema de arquivos. Se o tratador de erros for um tratador de erros substituto, os caracteres substitutos no intervalo U+DC80..U+DCFF são convertidos em bytes 0x80..0xFF.

Retorna um ponteiro para uma string de bytes recém-alocada; use PyMem_Free() para liberar a memória. Retorna NULL em caso de erro de codificação ou de erro de alocação de memória.

Se error_pos não for NULL, *error_pos será definido como (size_t)-1 em caso de sucesso, ou definido como o índice do caractere inválido em caso de erro de codificação.

tratador de erros e codificação do sistema de arquivos são selecionados por PyConfig_Read(): veja os membros filesystem_encoding e filesystem_errors de PyConfig.

Use a função Py_DecodeLocale() para decodificar a string de bytes de volta para uma string de caracteres largos.

Aviso

Esta função não deve ser chamada antes de Python estar pré-inicializado e para que a localidade LC_CTYPE seja configurada corretamente: consulte a função Py_PreInitialize().

Ver também

As funções PyUnicode_EncodeFSDefault() e PyUnicode_EncodeLocale().

Adicionado na versão 3.5.

Alterado na versão 3.7: A função agora usa a codificação UTF-8 no Modo UTF-8 do Python.

Alterado na versão 3.8: A função agora usa a codificação UTF-8 no Windows se PyPreConfig.legacy_windows_fs_encoding for zero.

Funções de sistema

Essas são funções utilitárias que tornam a funcionalidade do módulo sys acessível ao código C. Todas elas funcionam com o dicionário do módulo sys da thread do interpretador atual, que está contido na estrutura interna do estado de thread.

PyObject *PySys_GetObject(const char *name)

Retorna valor: Referência emprestada. Parte da ABI Estável.

Retorna o objeto name do módulo sys ou NULL se ele não existir, sem lançar uma exceção.

int PySys_SetObject(const char *name, PyObject *v)

Parte da ABI Estável.

Define name no módulo sys como v, a menos que v seja NULL, caso em que name é excluído do módulo sys. Retorna 0 em caso de sucesso e -1 em caso de erro.

void PySys_ResetWarnOptions()

Parte da ABI Estável.

Redefine sys.warnoptions para uma lista vazia. Esta função pode ser chamada antes de Py_Initialize().

Descontinuado desde a versão 3.13, será removido na versão 3.15: Limpe sys.warnoptions e warnings.filters em vez disso.

void PySys_WriteStdout(const char *format, ...)

Parte da ABI Estável.

Escreve a string de saída descrita por format em sys.stdout. Nenhuma exceção será levantada, mesmo que ocorra truncamento (veja abaixo).

format deve limitar o tamanho total da string de saída formatada a 1000 bytes ou menos – após 1000 bytes, a string de saída é truncada. Em particular, isso significa que não devem ocorrer formatos “%s” irrestritos; estes devem ser limitados usando “%.1s”, onde 2 é um número decimal calculado de forma que 3 mais o tamanho máximo de outros textos formatados não exceda 1000 bytes. Também fique atento a “%f”, que pode exibir centenas de dígitos para números muito grandes.

Se ocorrer um problema, ou se sys.stdout não estiver definido, a mensagem formatada será escrita na saída padrão (nível C) stdout.

void PySys_WriteStderr(const char *format, ...)

Parte da ABI Estável.

Como PySys_WriteStdout(), mas escreve em sys.stderr ou stderr em vez disso.

void PySys_FormatStdout(const char *format, ...)

Parte da ABI Estável.

Função semelhante a PySys_WriteStdout(), mas formata a mensagem usando PyUnicode_FromFormatV() e não trunca a mensagem para um comprimento arbitrário.

Adicionado na versão 3.2.

void PySys_FormatStderr(const char *format, ...)

Parte da ABI Estável.

Como PySys_FormatStdout(), mas escreve em sys.stderr ou stderr em vez disso.

Adicionado na versão 3.2.

PyObject *PySys_GetXOptions()

Retorna valor: Referência emprestada. Parte da ABI Estável desde a versão 3.7.

Retorna o dicionário atual de opções -X, de forma semelhante a sys._xoptions. Em caso de erro, retorna NULL e uma exceção é definida.

Adicionado na versão 3.2.

int PySys_Audit(const char *event, const char *format, ...)

Parte da ABI Estável desde a versão 3.13.

Levanta um evento de auditoria com todos os ganchos ativos. Retorna zero em caso de sucesso e um valor diferente de zero com uma exceção definida em caso de falha.

O argumento de string event não pode ser NULL.

Se algum gancho tiver sido adicionado, o argumento format e outros serão usados para construir uma tupla a ser passada. Além de N, os mesmos caracteres de formatação usados em Py_BuildValue() estão disponíveis. Se o valor construído não for uma tupla, ele será adicionado a uma tupla de um único elemento.

A opção de formato N não deve ser usada. Ela consome uma referência, mas como não há como saber se os argumentos dessa função serão consumidos, usá-la pode causar vazamentos de referência.

Observe que os caracteres de formato # devem sempre ser tratados como Py_ssize_t, independentemente de PY_SSIZE_T_CLEAN ter sido definido.

sys.audit() executa a mesma função a partir do código Python.

Veja também PySys_AuditTuple().

Adicionado na versão 3.8.

Alterado na versão 3.8.2: É necessário o tipo Py_ssize_t para caracteres de formato #. Anteriormente, um aviso de descontinuação era levantado.

int PySys_AuditTuple(const char *event, PyObject *args)

Parte da ABI Estável desde a versão 3.13.

Semelhante a PySys_Audit(), mas passa argumentos como um objeto Python. args deve ser uma tuple. Para não passar argumentos, args pode ser NULL.

Adicionado na versão 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

Adiciona o gancho chamável à lista de ganchos de auditoria ativos. Retorna zero em caso de sucesso e um valor diferente de zero em caso de falha. Se o ambiente de execução já tiver sido inicializado, também define um erro em caso de falha. Os ganchos adicionados por meio desta API são chamados para todos os interpretadores criados pelo ambiente de execução.

O ponteiro userData é passado para a função de gancho. Como as funções de gancho podem ser chamadas de diferentes tempos de execução, esse ponteiro não deve se referir diretamente ao estado do Python.

Esta função pode ser chamada com segurança antes de Py_Initialize(). Quando chamada após a inicialização em tempo de execução, os ganchos de auditoria existentes são notificados e podem abortar silenciosamente a operação, levantando um erro da classe Exception (outros erros não serão silenciados).

The hook function is always called with the GIL held by the Python interpreter that raised the event.

Consulte a PEP 578 para uma descrição detalhada da auditoria. As funções no ambiente de execução e na biblioteca padrão que levantam eventos estão listadas na tabela de eventos de auditoria. Os detalhes estão na documentação de cada função.

Se o interpretador estiver inicializado, esta função levanta um evento de auditoria sys.addaudithook sem argumentos. Se algum gancho existente levantar uma exceção derivada de Exception, o novo gancho não será adicionado e a exceção será tratada. Consequentemente, os chamadores não podem presumir que seu gancho foi adicionado, a menos que controlem todos os ganchos existentes.

typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)

O tipo da função de gancho. event é o argumento de evento em string C passado para PySys_Audit() ou PySys_AuditTuple(). args tem a garantia de ser um PyTupleObject. userData é o argumento passado para PySys_AddAuditHook().

Adicionado na versão 3.8.

Controle de processos

void Py_FatalError(const char *message)

Parte da ABI Estável.

Exibe uma mensagem de erro fatal e encerra forçadamente o processo. Nenhuma limpeza é realizada. Esta função só deve ser invocada quando uma condição for detectada que torne perigoso continuar usando o interpretador Python; por exemplo, quando a administração de objetos parecer estar corrompida. No Unix, a função da biblioteca padrão C abort() é chamada, que tentará produzir um arquivo core.

A função Py_FatalError() é substituída por uma macro que registra automaticamente o nome da função atual, a menos que a macro Py_LIMITED_API esteja definida.

Alterado na versão 3.9: Registra o nome da função automaticamente.

void Py_Exit(int status)

Parte da ABI Estável.

Encerra o processo atual. Isso chama Py_FinalizeEx() e, em seguida, chama a função da biblioteca padrão C exit(status). Se Py_FinalizeEx() indicar um erro, o código de status de saída será definido como 120.

Alterado na versão 3.6: Erros da finalização não são mais ignorados.

int Py_AtExit(void (*func)())

Parte da ABI Estável.

Registra uma função de limpeza para ser chamada por Py_FinalizeEx(). A função de limpeza será chamada sem argumentos e não deve retornar nenhum valor. No máximo 32 funções de limpeza podem ser registradas. Quando o registro for bem-sucedido, Py_AtExit() retorna 0; em caso de falha, retorna -1. A última função de limpeza registrada é chamada primeiro. Cada função de limpeza será chamada no máximo uma vez. Como a finalização interna do Python terá sido concluída antes da função de limpeza, nenhuma API do Python deve ser chamada por func.

Ver também

PyUnstable_AtExit() para passar um argumento void *data.