Utilitários do sistema operacional

PyObject *PyOS_FSPath(PyObject *path)

Retorna valor: Nova referência. Part of the Stable ABI since version 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.

Novo na versão 3.6.

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

Return true (nonzero) if the standard I/O file fp with name filename is deemed interactive. This is the case for files for which isatty(fileno(fp)) is true. If the global flag Py_InteractiveFlag is true, this function also returns true if the filename pointer is NULL or if the name is equal to one of the strings '<stdin>' or '???'.

void PyOS_BeforeFork()

Part of the Stable ABI on platforms with fork() since version 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().

Novo na versão 3.7.

void PyOS_AfterFork_Parent()

Part of the Stable ABI on platforms with fork() since version 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().

Novo na versão 3.7.

void PyOS_AfterFork_Child()

Part of the Stable ABI on platforms with fork() since version 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().

Novo 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()

Part of the Stable ABI 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.

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

int PyOS_CheckStack()

Part of the Stable ABI on platforms with USE_STACKCHECK since version 3.7.

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

PyOS_sighandler_t PyOS_getsig(int i)

Part of the Stable ABI.

Return the current signal handler for signal i. This is a thin wrapper around either sigaction() or signal(). Do not call those functions directly! PyOS_sighandler_t is a typedef alias for void (*)(int).

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Part of the Stable ABI.

Set the signal handler for signal i to be h; return the old signal handler. This is a thin wrapper around either sigaction() or signal(). Do not call those functions directly! PyOS_sighandler_t is a typedef alias for void (*)(int).

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

Part of the Stable ABI since version 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().

Novo 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: The function now uses the UTF-8 encoding on Windows if Py_LegacyWindowsFSEncodingFlag is zero;

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

Part of the Stable ABI since version 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().

Novo 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: The function now uses the UTF-8 encoding on Windows if Py_LegacyWindowsFSEncodingFlag is 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. Part of the Stable ABI.

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)

Part of the Stable ABI.

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

Part of the Stable ABI.

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

void PySys_AddWarnOption(const wchar_t *s)

Part of the Stable ABI.

Append s to sys.warnoptions. This function must be called prior to Py_Initialize() in order to affect the warnings filter list.

void PySys_AddWarnOptionUnicode(PyObject *unicode)

Part of the Stable ABI.

Append unicode to sys.warnoptions.

Note: this function is not currently usable from outside the CPython implementation, as it must be called prior to the implicit import of warnings in Py_Initialize() to be effective, but can’t be called until enough of the runtime has been initialized to permit the creation of Unicode objects.

void PySys_SetPath(const wchar_t *path)

Part of the Stable ABI.

Set sys.path to a list object of paths found in path which should be a list of paths separated with the platform’s search path delimiter (: on Unix, ; on Windows).

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

Part of the Stable ABI.

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, ...)

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

Novo na versão 3.2.

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

Part of the Stable ABI.

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

Novo na versão 3.2.

void PySys_AddXOption(const wchar_t *s)

Part of the Stable ABI since version 3.7.

Parse s as a set of -X options and add them to the current options mapping as returned by PySys_GetXOptions(). This function may be called prior to Py_Initialize().

Novo na versão 3.2.

PyObject *PySys_GetXOptions()

Retorna valor: Referência emprestada. Part of the Stable ABI since version 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.

Novo na versão 3.2.

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

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.

If any hooks have been added, format and other arguments will be used to construct a tuple to pass. Apart from N, the same format characters as used in Py_BuildValue() are available. If the built value is not a tuple, it will be added into a single-element tuple. (The N format option consumes a reference, but since there is no way to know whether arguments to this function will be consumed, using it may cause reference leaks.)

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.

Novo 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_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 of type int (*)(const char *event, PyObject *args, void *userData), where args is guaranteed to be a PyTupleObject. 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.

If the interpreter is initialized, this function raises a auditing event sys.addaudithook with no arguments. If any existing hooks raise an exception derived from Exception, the new hook will not be added and the exception is cleared. As a result, callers cannot assume that their hook has been added unless they control all existing hooks.

Novo na versão 3.8.

Controle de processos

void Py_FatalError(const char *message)

Part of the Stable ABI.

Print a fatal error message and kill the process. No cleanup is performed. This function should only be invoked when a condition is detected that would make it dangerous to continue using the Python interpreter; e.g., when the object administration appears to be corrupted. On Unix, the standard C library function abort() is called which will attempt to produce a core file.

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)

Part of the Stable ABI.

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

Part of the Stable ABI.

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.