1. Linha de comando e ambiente

O interpretador do CPython verifica a linha de comando e o ambiente em busca de várias configurações.

CPython implementation detail: Os esquemas de linha de comando de outras implementações podem ser diferentes. Consulte Implementações Alternativas para mais recursos.

1.1. Linha de comando

Ao invocar o Python, você pode especificar qualquer uma destas opções:

python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]

O caso de uso mais comum é, obviamente, uma simples invocação de um script:

python myscript.py

1.1.1. Opções de interface

A interface do interpretador é semelhante à do console do UNIX, mas fornece alguns métodos adicionais de chamada:

  • Quando chamado com a entrada padrão conectada a um dispositivo tty, ele solicita comandos e os executa até um EOF (um caractere de fim de arquivo, você pode produzi-lo com Ctrl-D no UNIX ou Ctrl-Z, Enter no Windows) ser lido.

  • Quando chamado com um argumento de nome de arquivo ou com um arquivo como entrada padrão, ele lê e executa um script desse arquivo.

  • Quando chamado com um argumento de nome de diretório, ele lê e executa um script nomeado adequadamente desse diretório.

  • Quando chamado com -c command, ele executa as instruções Python fornecidas como command. Aqui command pode conter várias instruções separadas por novas linhas. O espaço em branco à esquerda é significativo nas instruções do Python!

  • Quando chamado com -m module-name, o módulo fornecido está localizado no caminho do módulo Python e é executado como um script.

No modo não interativo, toda a entrada é analisada antes de ser executada.

Uma opção de interface termina a lista de opções consumidas pelo interpretador, todos os argumentos consecutivos terminam em sys.argv – observe que o primeiro elemento, subscrito zero (sys.argv[0]) , é uma string que reflete a fonte do programa.

-c <command>

Executa o código Python em command. command pode ser uma ou mais instruções separadas por novas linhas, com espaços em branco à esquerda significativos, como no código normal do módulo.

Se esta opção for fornecida, o primeiro elemento de sys.argv será "-c" e o diretório atual será adicionado ao início de sys.path (permitindo módulos nesse diretório para ser importado como módulos de nível superior).

Levanta um evento de auditoria cpython.run_command com o argumento command.

-m <module-name>

Procura sys.path pelo módulo nomeado e executa seu conteúdo como o módulo __main__.

Como o argumento é um nome de module, você não deve fornecer uma extensão de arquivo (.py). O nome do módulo deve ser um nome de módulo Python absoluto válido, mas a implementação nem sempre pode impor isso (por exemplo, pode permitir que você use um nome que inclua um hífen).

Nomes de pacotes (incluindo pacotes de espaço de nomes) também são permitidos. Quando um nome de pacote é fornecido ao invés de um módulo normal, o interpretador irá executar <pkg>.__main__ como o módulo principal. Esse comportamento é deliberadamente semelhante ao tratamento de diretórios e arquivos zip que são passados para o interpretador como o argumento do script.

Nota

Esta opção não pode ser usada com módulos embutidos e módulos de extensão escritos em C, uma vez que eles não possuem arquivos de módulo Python. No entanto, ele ainda pode ser usado para módulos pré-compilados, mesmo se o arquivo fonte original não estiver disponível.

Se esta opção for fornecida, o primeiro elemento de sys.argv será o caminho completo para o arquivo do módulo (enquanto o arquivo do módulo está sendo localizado, o primeiro elemento será definido como "-m"). Como com a opção -c, o diretório atual será adicionado ao início de sys.path.

A opção -I pode ser usada para executar o script em modo isolado onde sys.path não contém nem o diretório atual nem o diretório de pacotes de sites do usuário. Todas as variáveis de ambiente PYTHON* são ignoradas também.

Muitos módulos de biblioteca padrão contêm código que é chamado em sua execução como um script. Um exemplo é o módulo timeit:

python -m timeit -s 'setup here' 'benchmarked code here'
python -m timeit -h # for details

Levanta um evento de auditoria cpython.run_module com o argumento module-name.

Ver também

runpy.run_module()

Funcionalidade equivalente diretamente disponível para o código Python

PEP 338 – Executando módulos como scripts

Alterado na versão 3.1: Forneça o nome do pacote para executar um submódulo __main__.

Alterado na versão 3.4: pacotes de espaço de nomes também são suportados

-

Lê os comandos da entrada padrão (sys.stdin). Se a entrada padrão for um terminal, -i está implícito.

Se esta opção for fornecida, o primeiro elemento de sys.argv será "-" e o diretório atual será adicionado ao início de sys.path.

Levanta um evento de auditoria cpython.run_stdin sem argumentos.

<script>

Executa o código Python contido em script, que deve ser um caminho do sistema de arquivos (absoluto ou relativo) referindo-se a um arquivo Python, um diretório contendo um arquivo __main__.py, ou um arquivo zip contendo um arquivo __main__.py.

Se esta opção for fornecida, o primeiro elemento de sys.argv será o nome do script conforme fornecido na linha de comando.

Se o nome do script se referir diretamente a um arquivo Python, o diretório que contém esse arquivo é adicionado ao início de sys.path, e o arquivo é executado como o módulo __main__.

Se o nome do script se referir a um diretório ou arquivo zip, o nome do script será adicionado ao início de sys.path e o arquivo __main__.py nesse local será executado como o módulo __main__.

A opção -I pode ser usada para executar o script em modo isolado onde sys.path não contém nem o diretório do script nem o diretório de pacotes de sites do usuário. Todas as variáveis de ambiente PYTHON* são ignoradas também.

Levanta um evento de auditoria cpython.run_file com o argumento filename.

Ver também

runpy.run_path()

Funcionalidade equivalente diretamente disponível para o código Python

Se nenhuma opção de interface for fornecida, -i está implícito, sys.argv[0] é uma string vazia ("") e o diretório atual será adicionado ao início de sys.path. Além disso, o preenchimento por tab e a edição do histórico são habilitados automaticamente, se disponíveis em sua plataforma (veja Configuração Readline).

Ver também

Chamando o interpretador

Alterado na versão 3.4: Ativação automática de preenchimento com tab e edição de histórico.

1.1.2. Opções genéricas

-?
-h
--help

Exibe uma breve descrição de todas as opções de linha de comando.

-V
--version

Exibe o número da versão do Python e saia. O exemplo de saída poderia ser:

Python 3.8.0b2+

Quando fornecido duas vezes, exibe mais informações sobre a construção, como:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

Novo na versão 3.6: A opção -VV.

1.1.3. Opções diversas

-b

Emite um aviso ao comparar bytes ou bytearray com str ou bytes com int. Emite um erro quando a opção é fornecida duas vezes (-bb).

Alterado na versão 3.5: Afeta comparações de bytes com int.

-B

Se fornecido, Python não tentará escrever arquivos .pyc na importação de módulos fonte. Veja também PYTHONDONTWRITEBYTECODE.

--check-hash-based-pycs default|always|never

Controla o comportamento de validação de arquivos .pyc baseados em hash. Veja Invalidação de bytecode em cache. Quando definido como default, os arquivos de cache bytecode baseados em hash verificados e não verificados são validados de acordo com sua semântica padrão. Quando definido como always, todos os arquivos .pyc baseados em hash, sejam verificados ou não verificados, são validados para seus arquivos fonte correspondentes. Quando definido como never, os arquivos .pyc baseados em hash não são validados para seus arquivos fonte correspondentes.

A semântica dos arquivos .pyc baseados em marca de tempo não é afetada por esta opção.

-d

Ativa a saída de depuração do analisador sintático (apenas para especialistas, dependendo das opções de compilação). Veja também PYTHONDEBUG.

-E

Ignora todas as variáveis de ambiente PYTHON*, por exemplo PYTHONPATH e PYTHONHOME, que pode ser definido.

-i

Quando um script é passado como primeiro argumento ou a opção -c é usada, entre no modo interativo depois de executar o script ou o comando, mesmo quando sys.stdin não parece ser um terminal. O arquivo PYTHONSTARTUP não foi lido.

Isso pode ser útil para inspecionar variáveis globais ou um stack trace (situação da pilha de execução) quando um script levanta uma exceção. Veja também PYTHONINSPECT.

-I

Executa o Python no modo isolado. Isso também implica -E e -s. No modo isolado sys.path não contém o diretório do script nem o diretório de pacotes do site do usuário. Todas as variáveis de ambiente PYTHON* são ignoradas também. Outras restrições podem ser impostas para evitar que o usuário injete código malicioso.

Novo na versão 3.4.

-O

Remova as instruções de asserção e qualquer código condicional ao valor de __debug__. Aumenta o nome do arquivo para arquivos compilados (bytecode) adicionando .opt-1 antes da extensão .pyc (veja PEP 488). Veja também PYTHONOPTIMIZE.

Alterado na versão 3.5: Modifica nomes de arquivos .pyc conforme a PEP 488.

-OO

Faz o mesmo que -O e também descarta docstrings. Aumenta o nome do arquivo para arquivos compilados (bytecode) adicionando .opt-2 antes da extensão .pyc (veja PEP 488).

Alterado na versão 3.5: Modifica nomes de arquivos .pyc conforme a PEP 488.

-q

Não exibe as mensagens de direitos autorais e de versão nem mesmo no modo interativo.

Novo na versão 3.2.

-R

Habilita a aleatorização com hash. Esta opção só tem efeito se a variável de ambiente PYTHONHASHSEED estiver configurada para 0, uma vez que a aleatorização com hash é habilitada por padrão.

Em versões anteriores do Python, esta opção ativa a aleatorização com hash, para que os valores __hash__() dos objetos str e bytes sejam “salgados” com um valor aleatório imprevisível. Embora permaneçam constantes em um processo Python individual, eles não são previsíveis entre invocações repetidas de Python.

A aleatorização com hash se destina a fornecer proteção contra uma negação de serviço causada por entradas cuidadosamente escolhidas que exploram o pior caso de desempenho de uma inserção de dicionário, complexidade O(n^2). Consulte http://www.ocert.org/advisories/ocert-2011-003.html para obter detalhes.

PYTHONHASHSEED permite que você defina um valor fixo para o segredo da semente de hash.

Alterado na versão 3.7: A opção não é mais ignorada.

Novo na versão 3.2.3.

-s

Não adiciona o diretório site-packages de usuário a sys.path.

Ver também

PEP 370 – Diretório site-packages por usuário.

-S

Desabilita a importação do módulo site e as manipulações dependentes do site de sys.path que isso acarreta. Também desabilita essas manipulações se site for explicitamente importado mais tarde (chame site.main() se você quiser que eles sejam acionados).

-u

Força os fluxos stdout e stderr a serem sem buffer. Esta opção não tem efeito no fluxo stdin.

Veja também PYTHONUNBUFFERED.

Alterado na versão 3.7: A camada de texto dos fluxos stdout e stderr agora é sem buffer.

-v

Exibe uma mensagem cada vez que um módulo é inicializado, mostrando o local (nome do arquivo ou módulo embutido) de onde ele é carregado. Quando fornecido duas vezes (-vv), imprime uma mensagem para cada arquivo que é verificado durante a busca por um módulo. Também fornece informações sobre a limpeza do módulo na saída. Veja também PYTHONVERBOSE.

-W arg

Controle de aviso. O mecanismo de aviso do Python por padrão exibe mensagens de aviso para sys.stderr. Uma mensagem de aviso típica tem o seguinte formato:

file:line: category: message

Por padrão, cada aviso é exibido uma vez para cada linha fonte onde ocorre. Esta opção controla a frequência com que os avisos são exibidos.

Várias opções -W podem ser fornecidas; quando um aviso corresponde a mais de uma opção, a ação para a última opção correspondente é executada. As opções -W inválidas são ignoradas (embora, uma mensagem de aviso seja impressa sobre opções inválidas quando o primeiro aviso for emitido).

Os avisos também podem ser controlados usando a variável de ambiente PYTHONWARNINGS e de dentro de um programa Python usando o módulo warnings.

As configurações mais simples aplicam uma determinada ação incondicionalmente a todos os avisos emitidos por um processo (mesmo aqueles que são ignorados por padrão):

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

Os nomes das ações podem ser abreviados conforme desejado (por exemplo, -Wi, -Wd, -Wa, -We) e o interpretador irá resolvê-los para o nome de ação apropriado.

Veja O filtro de avisos e Describing Warning Filters para mais detalhes.

-x

Pula a primeira linha do código-fonte, permitindo o uso de formas não-Unix de #!cmd. Isso se destina apenas a um hack específico do DOS.

-X

Reservado para várias opções específicas de implementação. CPython atualmente define os seguintes valores possíveis:

  • -X faulthandler para habilitar faulthandler;

  • -X showrefcount para produzir a contagem de referências total e o número de blocos de memória usados ​​quando o programa termina ou após cada instrução no interpretador interativo. Isso só funciona em compilações de depuração.

  • -X tracemalloc para começar a rastrear alocações de memória do Python usando o módulo tracemalloc. Por padrão, apenas o quadro mais recente é armazenado no traceback (situação da pilha de execução) de um rastro. Use -X tracemalloc=NFRAME para iniciar o rastreamento com um limite de traceback de quadros NFRAME. Veja o tracemalloc.start() para mais informações.

  • -X showalloccount to output the total count of allocated objects for each type when the program finishes. This only works when Python was built with COUNT_ALLOCS defined.

  • -X int_max_str_digits configura a limitação de comprimento de string na conversão para inteiro. Veja também PYTHONINTMAXSTRDIGITS.

  • -X importtime para mostrar quanto tempo leva cada importação. Mostra o nome do módulo, tempo cumulativo (incluindo importações aninhadas) e tempo próprio (excluindo importações aninhadas). Observe que sua saída pode ser interrompida em aplicações multithread. O uso típico é python3 -X importtime -c 'import asyncio'. Veja também PYTHONPROFILEIMPORTTIME.

  • -X dev: enable CPython’s “development mode”, introducing additional runtime checks which are too expensive to be enabled by default. It should not be more verbose than the default if the code is correct: new warnings are only emitted when an issue is detected. Effect of the developer mode:

  • -X utf8 habilita o modo UTF-8 para interfaces do sistema operacional, substituindo o modo com reconhecimento de localidade padrão. -X utf8=0 desabilita explicitamente o modo UTF-8 (mesmo quando de outra forma seria ativado automaticamente). Veja PYTHONUTF8 para mais detalhes.

  • -X pycache_prefix=PATH permite a escrita de arquivos .pyc em uma árvore paralela enraizada em um determinado diretório em vez de na árvore de código. Veja também PYTHONPYCACHEPREFIX.

Também permite passar valores arbitrários e recuperá-los através do dicionário sys._xoptions.

Alterado na versão 3.2: A opção -X foi adicionada.

Novo na versão 3.3: A opção -X faulthandler.

Novo na versão 3.4: As opções -X showrefcount e -X tracemalloc.

Novo na versão 3.6: A opção -X showalloccount.

Novo na versão 3.7: As opções -X importtime, -X dev e -X utf8.

Novo na versão 3.8: A opção -X pycache_prefix. A opção -X dev agora registra exceções de close() no destruidor de io.IOBase.

Novo na versão 3.8.14: A opção -X int_max_str_digits.

1.1.4. Opções que você não deve usar

-J

Reservado para uso pelo Jython.

1.2. Variáveis de ambiente

Essas variáveis de ambiente influenciam o comportamento do Python, elas são processadas antes das opções de linha de comando diferentes de -E ou -I. É comum que as opções de linha de comando substituam as variáveis ambientais onde há um conflito.

PYTHONHOME

Altera a localização das bibliotecas Python padrão. Por padrão, as bibliotecas são pesquisadas em prefix/lib/pythonversion e exec_prefix/lib/pythonversion, onde prefix e exec_prefix são diretórios dependentes da instalação, ambos padronizando para /usr/local.

Quando PYTHONHOME é definido como um único diretório, seu valor substitui prefix e exec_prefix. Para especificar valores diferentes para estes, defina PYTHONHOME para prefix:exec_prefix.

PYTHONPATH

Aumenta o caminho de pesquisa padrão para arquivos de módulo. O formato é o mesmo PATH do shell: um ou mais caminhos de diretório separados por os.pathsep (por exemplo, dois pontos no Unix ou ponto e vírgula no Windows). Os diretórios inexistentes são ignorados silenciosamente.

Além dos diretórios normais, entradas individuais PYTHONPATH podem referir-se a arquivos zip contendo módulos Python puros (tanto no código-fonte quanto na forma compilada). Módulos de extensão não podem ser importados de arquivos zip.

O caminho de pesquisa padrão depende da instalação, mas geralmente começa com prefix/lib/pythonversion (veja PYTHONHOME acima). É sempre anexado a PYTHONPATH.

Um diretório adicional será inserido no caminho de pesquisa antes de PYTHONPATH como descrito acima em Opções de interface. O caminho de pesquisa pode ser manipulado de dentro de um programa Python como a variável sys.path.

PYTHONSTARTUP

Se este for o nome de um arquivo legível, os comandos Python nesse arquivo serão executados antes que o primeiro prompt seja exibido no modo interativo. O arquivo é executado no mesmo espaço de nomes onde os comandos interativos são executados para que os objetos definidos ou importados nele possam ser usados sem qualificação na sessão interativa. Você também pode alterar os prompts sys.ps1 e sys.ps2 e o gancho sys.__interactivehook__ neste arquivo.

Levanta um evento de auditoria cpython.run_startup com argumento filename.

PYTHONOPTIMIZE

Se for definido como uma string não vazia, é equivalente a especificar a opção -O. Se definido como um inteiro, é equivalente a especificar -O várias vezes.

PYTHONBREAKPOINT

Se estiver definida, ela nomeia um chamável usando a notação de caminho com pontos. O módulo que contém o chamável será importado e então o chamável será executado pela implementação padrão de sys.breakpointhook() que é chamado pelo breakpoint() embutido. Se não for definido, ou definido como uma string vazia, é equivalente ao valor “pdb.set_trace”. Definir isso para a string “0” faz com que a implementação padrão de sys.breakpointhook() não faça nada além de retornar imediatamente.

Novo na versão 3.7.

PYTHONDEBUG

Se for definido como uma string não vazia, é equivalente a especificar a opção -d. Se definido como um inteiro, é equivalente a especificar -d várias vezes.

PYTHONINSPECT

Se for definido como uma string não vazia, é equivalente a especificar a opção -i.

Esta variável também pode ser modificada pelo código Python usando os.environ para forçar o modo de inspeção no encerramento do programa.

Levanta um evento de auditoria cpython.run_stdin sem argumentos.

Alterado na versão 3.8.20: Emits audit events.

PYTHONUNBUFFERED

Se for definido como uma string não vazia, é equivalente a especificar a opção -u.

PYTHONVERBOSE

Se for definido como uma string não vazia, é equivalente a especificar a opção -v. Se definido como um inteiro, é equivalente a especificar -v várias vezes.

PYTHONCASEOK

Se estiver definido, Python não diferencia letras maiúsculas e minúsculas nas instruções import. Isso só funciona no Windows e OS X.

PYTHONDONTWRITEBYTECODE

Se for definido como uma string não vazia, o Python não tentará escrever arquivos .pyc na importação de módulos fonte. Isso é equivalente a especificar a opção -B.

PYTHONPYCACHEPREFIX

Se estiver definido, o Python escreverá os arquivos .pyc em uma árvore de diretório espelho neste caminho, em vez de nos diretórios __pycache__ dentro da árvore de fontes. Isso é equivalente a especificar a opção -X pycache_prefix=PATH.

Novo na versão 3.8.

PYTHONHASHSEED

Se esta variável não for definida ou definida como random, um valor aleatório é usado para semear os hashes de objetos str e bytes.

Se PYTHONHASHSEED for definido como um valor inteiro, ele é usado como uma semente fixa para gerar o hash() dos tipos cobertos pela aleatorização do hash.

Sua finalidade é permitir hash repetível, como autotestes do próprio interpretador, ou permitir que um cluster de processos Python compartilhe valores de hash.

O número inteiro deve ser um número decimal no intervalo [0,4294967295]. Especificar o valor 0 desabilitará a aleatorização de hash.

Novo na versão 3.2.3.

PYTHONINTMAXSTRDIGITS

Se esta variável estiver definida para um inteiro, é usada para configurar a limitação de comprimento de string na conversão para inteiro global do interpretador.

Novo na versão 3.8.14.

PYTHONIOENCODING

Se for definido antes de executar o interpretador, ele substitui a codificação usada para stdin/stdout/stderr, na sintaxe encodingname:errorhandler. Ambas as partes encodingname e :errorhandler são opcionais e têm o mesmo significado que em str.encode().

Para stderr, a parte :errorhandler é ignorada; o tratador sempre será 'backslashreplace'.

Alterado na versão 3.4: A parte encodingname é agora opcional.

Alterado na versão 3.6: No Windows, a codificação especificada por esta variável é ignorada para buffers de console interativo, a menos que PYTHONLEGACYWINDOWSSTDIO também seja especificado. Arquivos e canais redirecionados por meio de fluxos padrão não são afetados.

PYTHONNOUSERSITE

Se estiver definido, o Python não adicionará o diretório site-packages do usuário a sys.path.

Ver também

PEP 370 – Diretório site-packages por usuário.

PYTHONUSERBASE

Define o diretório base do usuário, que é usado para calcular o caminho do diretório site-packages do usuário e caminhos de instalação do Distutils para python setup.py install --user.

Ver também

PEP 370 – Diretório site-packages por usuário.

PYTHONEXECUTABLE

Se esta variável de ambiente for definida, sys.argv[0] será definido com seu valor em vez do valor obtido através do tempo de execução C. Funciona apenas no Mac OS X.

PYTHONWARNINGS

Isso é equivalente à opção -W. Se definido como uma string separada por vírgulas, é equivalente a especificar -W várias vezes, com os filtros posteriores na lista tendo precedência sobre os anteriores na lista.

As configurações mais simples aplicam uma determinada ação incondicionalmente a todos os avisos emitidos por um processo (mesmo aqueles que são ignorados por padrão):

PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn

Veja O filtro de avisos e Describing Warning Filters para mais detalhes.

PYTHONFAULTHANDLER

Se esta variável de ambiente for definida como uma string não vazia, faulthandler.enable() é chamado na inicialização: instale um tratador para os sinais SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL para despejar o traceback (situação da pilha de execução) do Python. Isso é equivalente à opção -X faulthandler.

Novo na versão 3.3.

PYTHONTRACEMALLOC

Se esta variável de ambiente for definida como uma string não vazia, começa a rastrear as alocações de memória Python usando o módulo tracemalloc. O valor da variável é o número máximo de quadros armazenados em um traceback de um rastreamento. Por exemplo, PYTHONTRACEMALLOC=1 armazena apenas o quadro mais recente. Veja o tracemalloc.start() para mais informações.

Novo na versão 3.4.

PYTHONPROFILEIMPORTTIME

Se esta variável de ambiente for definida como uma string não vazia, o Python mostrará quanto tempo leva cada importação. Isso é exatamente equivalente a definir -X importtime na linha de comando.

Novo na versão 3.7.

PYTHONASYNCIODEBUG

Se esta variável de ambiente for definida como uma string não vazia, habilita o modo de depuração do módulo asyncio.

Novo na versão 3.4.

PYTHONMALLOC

Define os alocadores de memória Python e/ou instale ganchos de depuração.

Define a família de alocadores de memória usados ​​pelo Python:

Instala os ganchos de depuração:

  • debug: instala os ganchos de depuração sobre os alocadores padrão de memória.

  • malloc_debug: o mesmo que malloc, mas também instala ganchos de depuração.

  • pymalloc_debug: o mesmo que pymalloc, mas também instala ganchos de depuração.

Veja os alocadores de memória padrão e a função PyMem_SetupDebugHooks() (instala ganchos de depuração em alocadores de memória Python).

Alterado na versão 3.7: Adicionado o alocador "default".

Novo na versão 3.6.

PYTHONMALLOCSTATS

Se definido como uma string não vazia, o Python exibe estatísticas do alocador de memória pymalloc toda vez que uma nova arena de objeto pymalloc for criada e ao no desligamento.

Esta variável é ignorada se a variável de ambiente PYTHONMALLOC é usada para forçar o alocador malloc() da biblioteca C, ou se Python está configurado sem suporte a pymalloc.

Alterado na versão 3.6: Esta variável agora também pode ser usada em Python compilado no modo de lançamento. Agora não tem efeito se definido como uma string vazia.

PYTHONLEGACYWINDOWSFSENCODING

Se definido como uma string não vazia, a codificação do sistema de arquivos padrão e o modo de erros serão revertidos para seus valores pré-3.6 de “mbcs” e “replace”, respectivamente. Caso contrário, os novos padrões “utf-8” e “surrogatepass” serão usados.

Isso também pode ser habilitado em tempo de execução com sys._enablelegacywindowsfsencoding().

Disponibilidade: Windows.

Novo na versão 3.6: Veja PEP 529 para mais detalhes.

PYTHONLEGACYWINDOWSSTDIO

Se definido como uma string não vazia, não usa o novo leitor e escritor de console. Isso significa que os caracteres Unicode serão codificados de acordo com a página de código do console ativo, em vez de usar utf-8.

Esta variável é ignorada se os fluxos padrão forem redirecionados (para arquivos ou canais) em vez de se referir aos buffers do console.

Disponibilidade: Windows.

Novo na versão 3.6.

PYTHONCOERCECLOCALE

Se definido com o valor 0, faz com que a aplicação principal de linha de comando Python ignore a coerção dos códigos de idioma legados C e POSIX baseados em ASCII para uma alternativa baseada em UTF-8 mais capaz.

Se esta variável não estiver definida (ou estiver definida para um valor diferente de 0), a variável de ambiente de substituição de localidade LC_ALL também não será definida, e a localidade atual relatada para a categoria LC_CTYPE é a localidade C padrão, ou então a localidade POSIX explicitamente baseada em ASCII, então a CLI do Python tentará configurar as seguintes localidades para a categoria LC_CTYPE na ordem listada antes de carregar o tempo de execução do interpretador:

  • C.UTF-8

  • C.utf8

  • UTF-8

Se a configuração de uma dessas categorias de local for bem-sucedida, a variável de ambiente LC_CTYPE também será configurada de acordo no ambiente de processo atual antes que o tempo de execução do Python seja inicializado. Isso garante que, além de ser visto pelo próprio interpretador e outros componentes com reconhecimento de localidade em execução no mesmo processo (como a biblioteca GNU readline), a configuração atualizada também é vista em subprocessos (independentemente de ou não esses processos estão executando um interpretador Python), bem como em operações que consultam o ambiente em vez da localidade C atual (como o locale.getdefaultlocale() do próprio Python).

Configurar uma dessas localidades (explicitamente ou por meio da coerção de localidade implícita acima) habilita automaticamente o tratador de erros surrogateescape para sys.stdin e sys.stdout (sys.stderr continua a usar backslashreplace como faz em qualquer outra localidade). Este comportamento de tratamento de fluxo pode ser substituído usando PYTHONIOENCODING como de costume.

Para fins de depuração, definir PYTHONCOERCECLOCALE=warn fará com que o Python emita mensagens de aviso em stderr se a coerção de localidade for ativada ou se uma localidade que teria acionado a coerção ainda estiver ativa quando o Python o tempo de execução é inicializado.

Observe também que mesmo quando a coerção de localidade está desabilitada, ou quando não consegue encontrar uma localidade de destino adequada, PYTHONUTF8 ainda será ativado por padrão em localidades baseadas em ASCII legadas. Ambos os recursos devem ser desabilitados para forçar o interpretador a usar ASCII ao invés de UTF-8 para interfaces de sistema.

Disponível: *nix.

Novo na versão 3.7: Veja PEP 538 para mais detalhes.

PYTHONDEVMODE

If this environment variable is set to a non-empty string, enable the CPython “development mode”. See the -X dev option.

Novo na versão 3.7.

PYTHONUTF8

Se definido como 1, habilita o modo UTF-8 do interpretador, onde UTF-8 é usado como a codificação de texto para interfaces do sistema, independentemente da configuração da localidade atual.

Isso significa que:

Como consequência das mudanças nessas APIs de baixo nível, outras APIs de alto nível também exibem comportamentos padrões diferentes:

  • Argumentos de linha de comando, variáveis de ambiente e nomes de arquivos são decodificados em texto usando a codificação UTF-8.

  • os.fsdecode() e os.fsencode() usam a codificação UTF-8.

  • open(), io.open() e codecs.open() usam a codificação UTF-8 por padrão. No entanto, elas ainda usam o tratador de erros estrito por padrão, de modo que a tentativa de abrir um arquivo binário no modo de texto provavelmente levantará uma exceção em vez de produzir dados sem sentido.

Observe que as configurações de fluxo padrão no modo UTF-8 podem ser substituídas por PYTHONIOENCODING (assim como podem estar no modo com reconhecimento de localidade padrão).

Se definido como 0, o interpretador executa em seu modo com reconhecimento de localidade padrão.

Definir qualquer outra string não vazia causa um erro durante a inicialização do interpretador.

Se esta variável de ambiente não for definida, o interpretador assume como padrão o uso das configurações de localidade atuais, a menos que a localidade atual seja identificada como uma localidade baseada em ASCII legada (conforme descrito para PYTHONCOERCECLOCALE), e localidade a coerção está desabilitada ou falha. Nessas localidades legadas, o interpretador assumirá como padrão a ativação do modo UTF-8, a menos que seja explicitamente instruído a não fazê-lo.

Também disponível como a opção -X utf8.

Novo na versão 3.7: Veja PEP 540 para mais detalhes.

1.2.1. Variáveis de modo de depuração

Definir essas variáveis só tem efeito em uma construção de depuração do Python.

PYTHONTHREADDEBUG

Se definido, Python exibirá informações de depuração de threads.

Necessita do Python configurado com a opção de construção --with-pydebug.

PYTHONDUMPREFS

Se definido, Python irá despejar objetos e contagens de referências ainda vivas após desligar o interpretador.

Necessita do Python configurado com a opção de construção --with-trace-refs.