Configuração de Inicialização do Python¶

Novo na versão 3.8.

Estruturas:

PyConfig
PyPreConfig
PyStatus
PyWideStringList

Funções:

A pré-configuração (tipo PyPreConfig) é armazenado em _PyRuntime.preconfig e a configuração (tipo PyConfig) é armazenado em PyInterpreterState.config.

Veja também Inicialização, Finalização e Threads.

Ver também

PEP 587 “Configuração da inicialização do Python”.

PyWideStringList¶

PyWideStringList¶

Lista de strings wchar_t*.

Se length é diferente de zero, items deve ser diferente de NULL e todas as strings devem ser diferentes de NULL.

Métodos:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)¶

Anexa item a list.

Python deve ser inicializado previamente antes de chamar essa função.

PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)¶

Insere item na list na posição index.

Se index for maior ou igual ao comprimento da list, anexa o item a list.

index deve ser maior que ou igual a 0.

Python deve ser inicializado previamente antes de chamar essa função.

Campos de estrutura

Py_ssize_t length¶: Comprimento da lista.

wchar_t** items¶: Itens da lista.

PyStatus¶

PyStatus¶

Estrutura para armazenar o status de uma função de inicialização: sucesso, erro ou saída.

Para um erro, ela pode armazenar o nome da função C que criou o erro.

Campos de estrutura

int exitcode¶: Código de saída. Argumento passado para exit().

const char *err_msg¶: Mensagem de erro.

const char *func¶: Nome da função que criou um erro. Pode ser NULL.

Funções para criar um status:

PyStatus PyStatus_Ok(void)¶: Sucesso.

PyStatus PyStatus_Error(const char *err_msg)¶: Erro de inicialização com uma mensagem.

PyStatus PyStatus_NoMemory(void)¶: Falha de alocação de memória (sem memória).

PyStatus PyStatus_Exit(int exitcode)¶: Sai do Python com o código de saída especificado.

Funções para manipular um status:

int PyStatus_Exception(PyStatus status)¶: O status é um erro ou uma saída? Se verdadeiro, a exceção deve ser tratada; chamando Py_ExitStatusException(), por exemplo.

int PyStatus_IsError(PyStatus status)¶: O resultado é um erro?

int PyStatus_IsExit(PyStatus status)¶: O resultado é uma saída?

void Py_ExitStatusException(PyStatus status)¶: Chama exit(exitcode) se status for uma saída. Exibe a mensagem de erro e sai com um código de saída diferente de zero se status for um erro. Deve ser chamado apenas se PyStatus_Exception(status) for diferente de zero.

Nota

Internamente, Python usa macros que definem PyStatus.func, enquanto funções para criar um status definem func para NULL.

Exemplo:

PyStatus alloc(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) {
        return PyStatus_NoMemory();
    }
    return PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    PyStatus status = alloc(&ptr, 16);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
    PyMem_Free(ptr);
    return 0;
}

PyPreConfig¶

PyPreConfig¶

Estrutura usada para pré-inicializar o Python:

Define o alocador de memória do Python
Configura a localidade LC_CTYPE
Define o modo UTF-8

A função para inicializar uma pré-configuração:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶: Inicializa a pré-configuração com Configuração do Python.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶: Inicializa a pré-configuração com Configuração isolada.

Campos de estrutura

int allocator¶

Nome do alocador de memória:

PYMEM_ALLOCATOR_NOT_SET (0): não altera os alocadores de memória (usa o padrão)
PYMEM_ALLOCATOR_DEFAULT (1): alocadores de memória padrão
PYMEM_ALLOCATOR_DEBUG (2): alocadores de memória padrão com ganchos de depuração
PYMEM_ALLOCATOR_MALLOC (3): força o uso de malloc()
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): força o uso de malloc() com ganchos de depuração
PYMEM_ALLOCATOR_PYMALLOC (5): Alocador de memória do Python pymalloc
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): alocador de memória do Python pymalloc com ganchos de depuração

PYMEM_ALLOCATOR_PYMALLOC e PYMEM_ALLOCATOR_PYMALLOC_DEBUG não são suportados se Python estiver configurado usando --without-pymalloc

Veja Gerenciamento de memória.

int configure_locale¶: Definir a localidade LC_CTYPE para a localidade preferida do usuário? Se for igual a 0, define coerce_c_locale e coerce_c_locale_warn para 0.

int coerce_c_locale¶: Se for igual a 2, força a localidade C; se for igual a 1, lê a localidade LC_CTYPE para decidir se deve ser forçado.

int coerce_c_locale_warn¶: Se diferente de zero, emite um aviso se a localidade C for forçada.

int dev_mode¶: Veja PyConfig.dev_mode.

int isolated¶: Veja PyConfig.isolated.

int legacy_windows_fs_encoding(Windows only)¶

Se diferente de zero, desabilita o modo UTF-8, define a codificação do sistema de arquivos Python para mbcs, define o tratador de erros do sistema de arquivos para replace.

Disponível apenas no Windows. A macro #ifdef MS_WINDOWS pode ser usada para código específico do Windows.

int parse_argv¶: Se diferente de zero, Py_PreInitializeFromArgs() e Py_PreInitializeFromBytesArgs() analisam seu argumento argv da mesma forma que o Python regular analisa argumentos de linha de comando: vej Argumentos de linha de comando.

int use_environment¶: Veja PyConfig.use_environment.

int utf8_mode¶: Se não zero, habilita o modo UTF-8.

Preinitialization with PyPreConfig¶

Functions to preinitialize Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶: Preinitialize Python from preconfig preconfiguration.

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)¶: Preinitialize Python from preconfig preconfiguration and command line arguments (bytes strings).

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)¶: Preinitialize Python from preconfig preconfiguration and command line arguments (wide strings).

The caller is responsible to handle exceptions (error or exit) using PyStatus_Exception() and Py_ExitStatusException().

For Python Configuration (PyPreConfig_InitPythonConfig()), if Python is initialized with command line arguments, the command line arguments must also be passed to preinitialize Python, since they have an effect on the pre-configuration like encodings. For example, the -X utf8 command line option enables the UTF-8 Mode.

PyMem_SetAllocator() can be called after Py_PreInitialize() and before Py_InitializeFromConfig() to install a custom memory allocator. It can be called before Py_PreInitialize() if PyPreConfig.allocator is set to PYMEM_ALLOCATOR_NOT_SET.

Python memory allocation functions like PyMem_RawMalloc() must not be used before Python preinitialization, whereas calling directly malloc() and free() is always safe. Py_DecodeLocale() must not be called before the preinitialization.

Example using the preinitialization to enable the UTF-8 Mode:

PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

/* at this point, Python will speak UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();

PyConfig¶

PyConfig¶

Structure containing most parameters to configure Python.

Structure methods:

void PyConfig_InitPythonConfig(PyConfig *config)¶: Initialize configuration with Python Configuration.

void PyConfig_InitIsolatedConfig(PyConfig *config)¶: Initialize configuration with Isolated Configuration.

PyStatus PyConfig_SetString(PyConfig *config, wchar_t * const *config_str, const wchar_t *str)¶

Copy the wide character string str into *config_str.