sys
— Parâmetros e funções específicas do sistema¶
Este módulo fornece acesso a algumas variáveis usadas ou mantidas pelo interpretador e a funções que interagem fortemente com o interpretador. Sempre disponível.
- sys.abiflags¶
Em sistemas POSIX onde Python foi construído com o script
configure
padrão, ele contém os sinalizadores ABI conforme especificado por PEP 3149.Adicionado na versão 3.2.
Alterado na versão 3.8: Os sinalizadores padrões se tornaram uma string vazia (o sinalizador
m
para pymalloc foi removido).Disponibilidade: Unix.
- sys.addaudithook(hook)¶
Anexa o hook chamável à lista de ganchos de auditoria ativos para o (sub)interpretador atual.
Quando um evento de auditoria é levantado através da função
sys.audit()
, cada gancho será chamado na ordem em que foi adicionado com o nome do evento e a tupla de argumentos. Ganchos nativos adicionados porPySys_AddAuditHook()
são chamados primeiro, seguidos por ganchos adicionados no (sub)interpretador atual. Os ganchos podem registrar o evento, levantar uma exceção para cancelar a operação ou encerrar o processo completamente.Observe que os ganchos de auditoria são principalmente para coletar informações sobre ações internas ou não observáveis, seja por Python ou bibliotecas escritas em Python. Eles não são adequados para implementar um ambiente isolado estilo “sandbox”. Em particular, o código malicioso pode desabilitar ou ignorar os ganchos adicionados usando esta função. No mínimo, quaisquer ganchos sensíveis à segurança devem ser adicionados usando a API C
PySys_AddAuditHook()
antes de inicializar o tempo de execução, e quaisquer módulos que permitam modificação arbitrária da memória (comoctypes
) devem ser completamente removidos ou monitorados de perto.Chamar
sys.addaudithook()
levantará um evento de auditoria denominadosys.addaudithook
sem argumentos. Se qualquer gancho existente levantar uma exceção derivada deRuntimeError
, o novo gancho não será adicionado e a exceção será suprimida. Como resultado, os chamadores não podem presumir que seu gancho foi adicionado, a menos que controlem todos os ganchos existentes.Veja tabela de eventos de auditoria para todos os eventos levantados pelo CPython, e PEP 578 para a discussão do projeto original.
Adicionado na versão 3.8.
Alterado na versão 3.8.1: Exceções derivadas de
Exception
, mas não deRuntimeError
, não são mais suprimidas.Detalhes da implementação do CPython: Quando o rastreamento está ativado (consulte
settrace()
), os ganchos do Python são rastreados apenas se o chamável tiver um membro__cantrace__
definido como um valor verdadeiro. Caso contrário, as funções de rastreamento ignorarão o gancho.
- sys.argv¶
A lista de argumentos de linha de comando passados para um script Python.
argv[0]
é o nome do script (depende do sistema operacional se este é um nome de caminho completo ou não). Se o comando foi executado usando a opção de linha de comando-c
para o interpretador,argv[0]
é definido como a string'-c'
. Se nenhum nome de script foi passado para o interpretador Python,argv[0]
é a string vazia.Para percorrer a entrada padrão ou a lista de arquivos fornecida na linha de comando, consulte o módulo
fileinput
.Veja também
sys.orig_argv
.Nota
No Unix, os argumentos da linha de comando são passados por bytes do sistema operacional. O Python os decodifica com a codificação do sistema de arquivos e o tratador de erros “surrogateescape”. Quando você precisar de bytes originais, você pode obtê-los por
[os.fsencode(arg) for arg in sys.argv]
.
- sys.audit(event, *args)¶
Levanta um evento de auditoria e aciona quaisquer ganchos de auditoria ativos. event é uma string que identifica o evento e args pode conter argumentos opcionais com mais informações sobre o evento. O número e os tipos de argumentos para um determinado evento são considerados uma API pública e estável e não devem ser modificados entre as versões.
Por exemplo, um evento de auditoria é denominado
os.chdir
. Este evento tem um argumento chamado path que conterá o novo diretório de trabalho solicitado.sys.audit()
chamará os ganchos de auditoria existentes, passando o nome do evento e os argumentos, e levantará novamente a primeira exceção de qualquer gancho. Em geral, se uma exceção for levantada, ela não deve ser tratada e o processo deve ser encerrado o mais rápido possível. Isso permite que as implementações de gancho decidam como responder a eventos específicos: elas podem simplesmente registrar o evento ou abortar a operação levantando uma exceção.Ganchos são adicionados usando as funções
sys.addaudithook()
ouPySys_AddAuditHook()
.O equivalente nativo desta função é
PySys_Audit()
. Usar a função nativa é preferível quando possível.Veja tabela de eventos de auditoria para todos os eventos levantados pelo CPython.
Adicionado na versão 3.8.
- sys.base_exec_prefix¶
Definido durante a inicialização do Python, antes de
site.py
ser executado, para o mesmo valor queexec_prefix
. Se não estiver executando em um ambiente virtual, os valores permanecerão os mesmos; sesite.py
descobrir que um ambiente virtual está em uso, os valores deprefix
eexec_prefix
serão alterados para apontar para o ambiente virtual, enquantobase_prefix
ebase_exec_prefix
permanecerá apontando para a instalação base do Python (aquela a partir da qual o ambiente virtual foi criado).Adicionado na versão 3.3.
- sys.base_prefix¶
Definido durante a inicialização do Python, antes de
site.py
ser executado, para o mesmo valor queprefix
. Se não estiver executando em um ambiente virtual, os valores permanecerão os mesmos; sesite.py
descobrir que um ambiente virtual está em uso, os valores deprefix
eexec_prefix
serão alterados para apontar para o ambiente virtual, enquantobase_prefix
ebase_exec_prefix
permanecerá apontando para a instalação base do Python (aquela a partir da qual o ambiente virtual foi criado).Adicionado na versão 3.3.
- sys.byteorder¶
Um indicador da ordem nativa de bytes. Isso terá o valor
'big'
em plataformas big endian (byte mais significativo primeiro) e'little'
em plataformas little endian (byte menos significativo primeiro).
- sys.builtin_module_names¶
Uma tupla de strings contendo os nomes de todos os módulos compilados neste interpretador Python. (Esta informação não está disponível de nenhuma outra forma —
modules.keys()
apenas lista os módulos importados.)Veja também a lista de
sys.stdlib_module_names
.
- sys.call_tracing(func, args)¶
Chama
func(*args)
, enquanto o rastreamento está habilitado. O estado de rastreamento é salvo e restaurado posteriormente. Isso deve ser chamado de um depurador de um ponto de verificação, para depurar ou analisar o desempenho recursivamente algum outro código.O rastreamento é suspenso ao chamar uma função de rastreamento definida por
settrace()
ousetprofile()
para evitar recursão infinita.call_tracing()
habilita a recursão explícita da função de rastreamento.
- sys.copyright¶
Uma string contendo os direitos autorais pertencentes ao interpretador Python.
- sys._clear_type_cache()¶
Limpa o cache de tipo interno. O cache de tipo é usado para acelerar pesquisas de atributos e métodos. Use a função apenas para descartar referências desnecessárias durante a depuração de vazamento de referência.
Esta função deve ser usada apenas para fins internos e especializados.
Obsoleto desde a versão 3.13: Em vez disso, use a função mais geral
_clear_internal_caches()
.
- sys._clear_internal_caches()¶
Limpa todos os caches internos relacionados ao desempenho. Use esta função somente para liberar referências e blocos de memória desnecessários ao procurar por vazamentos.
Adicionado na versão 3.13.
- sys._current_frames()¶
Retorna um dicionário mapeando o identificador de cada encadeamento (thread) para o quadro de pilha mais alto atualmente ativo nesse encadeamento no momento em que a função é chamada. Observe que as funções no módulo
traceback
podem construir a pilha de chamadas dado tal quadro.Isso é mais útil para fazer a depuração de impasses: esta função não requer a cooperação das threads em impasse e as pilhas de chamadas de tais threads são congeladas enquanto permanecerem em impasse (deadlock). O quadro retornado para uma thread sem impasse pode não ter nenhuma relação com a atividade atual da thread no momento em que o código de chamada examina o quadro.
Esta função deve ser usada apenas para fins internos e especializados.
Levanta um evento de auditoria
sys._current_frames
sem argumentos.
- sys._current_exceptions()¶
Retorna um dicionário mapeando o identificador de cada encadeamento (thread) para a exceção mais alta atualmente ativo nesse encadeamento no momento em que a função é chamada. Se um encadeamento não estiver manipulando uma exceção no momento, ele não será incluído no dicionário de resultados.
Isso é mais útil para criação de perfil estatístico.
Esta função deve ser usada apenas para fins internos e especializados.
Levanta um evento de auditoria
sys._current_exceptions
sem argumentos.Alterado na versão 3.12: Cada valor no dicionário agora é uma única instância de exceção, em vez de uma tupla de 3 elementos, como retornado de
sys.exc_info()
.
- sys.breakpointhook()¶
Esta função de gancho é chamada pela função embutida
breakpoint()
. Por padrão, ela leva você ao depuradorpdb
, mas pode ser configurado para qualquer outra função para que você possa escolher qual depurador será usado.A assinatura dessa função depende do que ela chama. Por exemplo, a ligação padrão (por exemplo,
pdb.set_trace()
) não espera nenhum argumento, mas você pode vinculá-la a uma função que espera argumentos adicionais (posicionais e/ou nomeados). A função embutidabreakpoint()
passa seus*args
e**kws
diretamente. O que quer quebreakpointhooks()
retorne é retornado debreakpoint()
.A implementação padrão primeiro consulta a variável de ambiente
PYTHONBREAKPOINT
. Se for definido como"0"
, então esta função retorna imediatamente; ou seja, é um no-op. Se a variável de ambiente não for definida, ou for definida como uma string vazia,pdb.set_trace()
será chamado. Caso contrário, essa variável deve nomear uma função a ser executada, usando a nomenclatura de importação pontilhada do Python, por exemplopackage.subpackage.module.function
. Neste caso,package.subpackage.module
seria importado e o módulo resultante deve ter um chamável chamadofunction()
. Isso é executado, passando*args
e**kws
, e qualquer que seja o retorno defunction()
,sys.breakpointhook()
retorna para a função embutidabreakpoint()
.Observe que se algo der errado ao importar o chamável nomeado por
PYTHONBREAKPOINT
, umaRuntimeWarning
é relatado e o ponto de interrupção é ignorado.Observe também que se
sys.breakpointhook()
for sobrescrito programaticamente,PYTHONBREAKPOINT
não será consultado.Adicionado na versão 3.7.
- sys._debugmallocstats()¶
Imprima informações de baixo nível para stderr sobre o estado do alocador de memória do CPython.
Se o Python for compilado no modo de depuração (
opção --with-pydebug do configure
), ele também executa algumas verificações de consistência interna custosas.Adicionado na versão 3.3.
Detalhes da implementação do CPython: Esta função é específica para CPython. O formato de saída exato não é definido aqui e pode mudar.
- sys.dllhandle¶
Número inteiro que especifica o identificador da DLL do Python.
Disponibilidade: Windows.
- sys.displayhook(value)¶
Se value não for
None
, esta função imprimerepr(value)
emsys.stdout
, e salva value embuiltins._
. Serepr(value)
não for codificável parasys.stdout.encoding
com o tratador de errossys.stdout.errors
(que provavelmente é'strict'
), codifica-o parasys.stdout.encoding
com tratador de erros'backslashreplace'
.sys.displayhook
é chamado no resultado da avaliação de uma expressão inserida em uma sessão interativa do Python. A exibição desses valores pode ser personalizada atribuindo outra função de um argumento asys.displayhook
.Pseudocódigo:
def displayhook(value): if value is None: return # Set '_' to None to avoid recursion builtins._ = None text = repr(value) try: sys.stdout.write(text) except UnicodeEncodeError: bytes = text.encode(sys.stdout.encoding, 'backslashreplace') if hasattr(sys.stdout, 'buffer'): sys.stdout.buffer.write(bytes) else: text = bytes.decode(sys.stdout.encoding, 'strict') sys.stdout.write(text) sys.stdout.write("\n") builtins._ = value
Alterado na versão 3.2: Usa o tratador de erros
'backslashreplace'
ao ser levantadaUnicodeEncodeError
.
- sys.dont_write_bytecode¶
Se isso for true, o Python não tentará escrever arquivos
.pyc
na importação de módulos fonte. Este valor é inicialmente definido comoTrue
ouFalse
dependendo da opção de linha de comando-B
e da variável de ambientePYTHONDONTWRITEBYTECODE
, mas você mesmo pode configurá-lo para controlar geração de arquivo bytecode.
- sys._emscripten_info¶
Um tupla nomeada contendo informações sobre o ambiente na plataforma wasm32-emscripten. A tupla nomeada é provisória e pode mudar no futuro.
- _emscripten_info.emscripten_version¶
Versão emscripten como tupla de ints (maior, menor, micro), por exemplo
(3, 1, 8)
.
- _emscripten_info.runtime¶
String em tempo de execução; por exemplo, user-agent do navegador,
'Node.js v14.18.2'
, ou'UNKNOWN'
.
- _emscripten_info.pthreads¶
True
se o Python for compilado com suporte a pthreads do Emscripten.
True
se o Python for compilado com suporte a memória compartilhada.
Disponibilidade: Emscripten.
Adicionado na versão 3.11.
- sys.pycache_prefix¶
Se for definido (não
None
), o Python escreverá arquivos de cache de bytecode.pyc
para (e os lerá de) uma árvore de diretórios paralela com raiz neste diretório, em vez de diretórios__pycache__
na árvore de código-fonte. Quaisquer diretórios__pycache__
na árvore de código-fonte serão ignorados e novos arquivos.pyc
gravados dentro do prefixo pycache. Portanto, se você usarcompileall
como uma etapa de pré-compilação, certifique-se de executá-lo com o mesmo prefixo pycache (se houver) que usará em tempo de execução.Um caminho relativo é interpretado em relação ao diretório de trabalho atual.
Este valor é definido inicialmente com base no valor da opção de linha de comando
-X
pycache_prefix=PATH
ou na variável de ambientePYTHONPYCACHEPREFIX
(a linha de comando tem precedência). Se nenhum estiver definido, éNone
.Adicionado na versão 3.8.
- sys.excepthook(type, value, traceback)¶
Esta função imprime um determinado traceback (situação da pilha de execução) e exceção para
sys.stderr
.Quando uma exceção além da
SystemExit
é levantada e não capturada, o interpretador chamasys.excepthook
com três argumentos, a classe de exceção, a instância de exceção e um objeto traceback. Em uma sessão interativa, isso acontece logo antes de o controle retornar ao prompt; em um programa Python, isso acontece pouco antes de o programa ser encerrado. A manipulação de tais exceções de nível superior pode ser personalizada atribuindo outra função de três argumentos asys.excepthook
.Levanta um evento de auditoria
sys.excepthook
com os argumentoshook
,type
,value
,traceback
quando ocorre uma exceção não capturada. Se nenhum gancho foi definido,hook
pode serNone
. Se algum gancho gerar uma exceção derivada deRuntimeError
, a chamada para o gancho será suprimida. Caso contrário, a exceção de gancho de auditoria será relatada como não aumentável esys.excepthook
será chamado.Ver também
A função
sys.unraisablehook()
lida com exceções que não podem ser levantadas e a funçãothreading.excepthook()
trata exceções levantadas porthreading.Thread.run()
.
- sys.__breakpointhook__¶
- sys.__displayhook__¶
- sys.__excepthook__¶
- sys.__unraisablehook__¶
Esses objetos contêm os valores originais de
breakpointhook
,displayhook
,excepthook
eunraisablehook
no início do programa. Eles são salvos para quebreakpointhook
,displayhook
eexcepthook
,unraisablehook
possam ser restaurados caso sejam substituídos por objetos quebrados ou alternativos.Adicionado na versão 3.7: __breakpointhook__
Adicionado na versão 3.8: __unraisablehook__
- sys.exception()¶
Esta função, quando chamada enquanto um tratador de exceção está em execução (como uma cláusula
except
ouexcept*
), retorna a instância da exceção que foi capturada por este tratador. Quando os manipuladores de exceção estão aninhados um dentro do outro, apenas a exceção tratada pelo tratador mais interno é acessível.Se nenhum tratador de exceções estiver em execução, esta função retornará
None
.Adicionado na versão 3.11.
- sys.exc_info()¶
Essa função retorna a representação de estilo antigo da exceção tratada. Se uma exceção
e
é tratada atualmente (de forma queexception()
retornariae
),exc_info()
retorna a tupla(type(e), e, e.__traceback__)
. Ou seja, uma tupla contendo o tipo da exceção (uma subclasse deBaseException
), a própria exceção e um objeto de traceback que normalmente encapsula a pilha de chamadas no ponto em que a última exceção ocorreu.Se nenhuma exceção estiver sendo tratada em qualquer lugar da pilha, esta função retornará uma tupla contendo três valores
None
.Alterado na versão 3.11: Os campos
type
etraceback
agora são derivados dovalue
(a instância da exceção), portanto, quando uma exceção é modificada enquanto está sendo tratada, as alterações são refletidas nos resultados das subsequentes chamadas paraexc_info()
.
- sys.exec_prefix¶
Uma string que fornece o prefixo do diretório específico do site onde os arquivos Python dependentes da plataforma são instalados; por padrão, também é
'/usr/local'
. Isso pode ser definido em tempo de compilação com o argumento--exec-prefix
para o script configure. Especificamente, todos os arquivos de configuração (por exemplo, o arquivo de cabeçalhopyconfig.h
) são instalados no diretórioexec_prefix/lib/pythonX.Y/config
, e os módulos da biblioteca compartilhada são instalados emexec_prefix/lib/pythonX.Y/lib-dynload
, onde X.Y é o número da versão do Python, por exemplo3.2
.Nota
Se um ambiente virtual estiver em vigor, este valor será alterado em
site.py
para apontar para o ambiente virtual. O valor para a instalação do Python ainda estará disponível, viabase_exec_prefix
.
- sys.executable¶
Uma string que fornece o caminho absoluto do binário executável para o interpretador Python, em sistemas onde isso faz sentido. Se o Python não conseguir recuperar o caminho real para seu executável,
sys.executable
será uma string vazia ouNone
.
- sys.exit([arg])¶
Levanta uma exceção
SystemExit
, sinalizando a intenção de sair do interpretador.O argumento opcional arg pode ser um número inteiro dando o status de saída (o padrão é zero) ou outro tipo de objeto. Se for um número inteiro, zero é considerado “terminação bem-sucedida” e qualquer valor diferente de zero é considerado “terminação anormal” por shells e similares. A maioria dos sistemas exige que ele esteja no intervalo de 0 a 127 e, caso contrário, produz resultados indefinidos. Alguns sistemas têm uma convenção para atribuir significados específicos a códigos de saída específicos, mas estes são geralmente subdesenvolvidos; Programas Unix geralmente usam 2 para erros de sintaxe de linha de comando e 1 para todos os outros tipos de erros. Se outro tipo de objeto for passado,
None
é equivalente a passar zero, e qualquer outro objeto é impresso emstderr
e resulta em um código de saída de 1. Em particular,sys.exit( "alguma mensagem de erro")
é uma maneira rápida de sair de um programa quando ocorre um erro.Uma vez que
exit()
em última análise, “apenas” gera uma exceção, ele só sairá do processo quando chamado do thread principal e a exceção não é interceptada. As ações de limpeza especificadas pelas cláusulas finally de instruçõestry
são honradas e é possível interceptar a tentativa de saída em um nível externo.Alterado na versão 3.6: Se ocorrer um erro na limpeza após o interpretador Python ter capturado
SystemExit
(como um erro ao liberar dados em buffer nos fluxos padrão), o status de saída é alterado para 120.
- sys.flags¶
A tupla nomeada flags expõe o status dos sinalizadores de linha de comando. Os atributos são somente leitura.
- flags.debug¶
- flags.inspect¶
- flags.interactive¶
- flags.isolated¶
- flags.optimize¶
- flags.dont_write_bytecode¶
- flags.no_user_site¶
- flags.no_site¶
- flags.ignore_environment¶
- flags.verbose¶
- flags.bytes_warning¶
- flags.quiet¶
- flags.hash_randomization¶
- flags.dev_mode¶
- flags.utf8_mode¶
- flags.safe_path¶
- flags.int_max_str_digits¶
-X int_max_str_digits
(limitação de comprimento de string na conversão para inteiro)- flags.warn_default_encoding¶
Alterado na versão 3.2: Adicionado o atributo
quiet
para o novo sinalizador-q
.Adicionado na versão 3.2.3: O atributo
hash_randomization
.Alterado na versão 3.3: Removido o atributo obsoleto
division_warning
.Alterado na versão 3.4: Adicionado o atributo
isolated
para o sinalizador-I
isolated
.Alterado na versão 3.7: Adicionado o atributo
dev_mode
para o novo Modo de Desenvolvimento do Python e o atributoutf8_mode
para o novo sinalizador-X
utf8
.Alterado na versão 3.10: Adicionado o atributo
warn_default_encoding
para o sinalizador-X
warn_default_encoding
.Alterado na versão 3.11: Adicionado o atributo
safe_path
para a opção-P
.Alterado na versão 3.11: Adicionado o atributo
int_max_str_digits
.
- sys.float_info¶
Uma tupla nomeada contendo informações sobre o tipo float, ponto flutuante. Ele contém informações de baixo nível sobre a precisão e a representação interna. Os valores correspondem às várias constantes de ponto flutuante definidas no arquivo de cabeçalho padrão
float.h
para a linguagem de programação ‘C’; consulte a seção 5.2.4.2.2 do padrão ISO/IEC C de 1999 [C99], ‘Características dos tipos flutuantes’, para obter detalhes.Atributos da tupla nomeada float_info
¶atributo
macro em float.h
explicação
- float_info.epsilon¶
DBL_EPSILON
diferença entre 1,0 e o menor valor maior que 1,0 que pode ser representado como ponto flutuante.
Veja também
math.ulp.()
- float_info.dig¶
DBL_DIG
O número máximo de dígitos decimais que podem ser fielmente representados em um ponto flutuante; veja abaixo.
- float_info.mant_dig¶
DBL_MANT_DIG
Precisão do ponto flutuante: o número de dígitos de base
radix
no significando de um ponto flutuante.- float_info.max¶
DBL_MAX
O ponto flutuante finito positivo máximo representável.
- float_info.max_exp¶
DBL_MAX_EXP
O inteiro máximo e de tal modo que
radix**(e-1)
é um ponto flutuante finito representável.- float_info.max_10_exp¶
DBL_MAX_10_EXP
O inteiro máximo e de tal modo que
10**e
é um intervalo de pontos flutuantes finitos representáveis.- float_info.min¶
DBL_MIN
O ponto flutuante normalizado positivo mínimo representável.
Use
math.ulp(0.0)
para obter o menor ponto flutuante representável positivo desnormalizado.- float_info.min_exp¶
DBL_MIN_EXP
O inteiro mínimo e de tal modo que
radix**(e-1)
é um ponto flutuante normalizado.- float_info.min_10_exp¶
DBL_MIN_10_EXP
O inteiro mínimo e de tal modo que
10**e
é um ponto flutuante normalizado.- float_info.radix¶
FLT_RADIX
A raiz da representação do expoente.
- float_info.rounds¶
FLT_ROUNDS
Um inteiro representando o modo de arredondamento para aritmética de ponto flutuante. Isso reflete o valor da macro do sistema
FLT_ROUNDS
no momento da inicialização do interpretador:-1
: indeterminável0
: em direção a zero1
: para o mais próximo2
: em direção ao infinito positivo3
: em direção ao infinito negativo
Todos os outros valores para
FLT_ROUNDS
caracterizam o comportamento de arredondamento definido pela implementação.O atributo
sys.float_info.dig
precisa de mais explicações. Ses
for qualquer string representando um número decimal com no máximosys.float_info.dig
dígitos significativos, então converters
para ponto flutuante e vice-versa recuperará uma string representando o mesmo decimal valor:>>> import sys >>> sys.float_info.dig 15 >>> s = '3.14159265358979' # decimal string with 15 significant digits >>> format(float(s), '.15g') # convert to float and back -> same value '3.14159265358979'
Mas para strings com mais de
sys.float_info.dig
dígitos significativos, isso nem sempre é verdade:>>> s = '9876543211234567' # 16 significant digits is too many! >>> format(float(s), '.16g') # conversion changes value '9876543211234568'
- sys.float_repr_style¶
Uma string indicando como a função
repr()
se comporta para floats. Se a string tem valor'short'
então para um ponto flutuante finitox
,repr(x)
visa produzir uma string curta com a propriedade quefloat(repr(x)) == x
. Este é o comportamento usual no Python 3.1 e posterior. Caso contrário,float_repr_style
tem valor'legacy'
erepr(x)
se comporta da mesma forma que nas versões do Python anteriores a 3.1.Adicionado na versão 3.1.
- sys.getallocatedblocks()¶
Return the number of memory blocks currently allocated by the interpreter, regardless of their size. This function is mainly useful for tracking and debugging memory leaks. Because of the interpreter’s internal caches, the result can vary from call to call; you may have to call
_clear_internal_caches()
andgc.collect()
to get more predictable results.If a Python build or implementation cannot reasonably compute this information,
getallocatedblocks()
is allowed to return 0 instead.Adicionado na versão 3.4.
- sys.getunicodeinternedsize()¶
Retorna o número de objetos unicode que foram internalizados.
Adicionado na versão 3.12.
- sys.getandroidapilevel()¶
Retorna o nível de API de tempo de construção do Android como um inteiro. Isso representa a versão mínima do Android em que esta construção do Python pode ser executada. Para obter informações sobre a versão de tempo de execução, consulte
platform.android_ver()
.Disponibilidade: Android.
Adicionado na versão 3.7.
- sys.getdefaultencoding()¶
Retorna o nome da codificação de string padrão atual usada pela implementação Unicode.
- sys.getdlopenflags()¶
Retorna o valor atual dos sinalizadores que são usados para chamadas
dlopen()
. Nomes simbólicos para os valores dos sinalizadores podem ser encontrados no móduloos
(constantesRTLD_xxx
, por exemploos.RTLD_LAZY
).Disponibilidade: Unix.
- sys.getfilesystemencoding()¶
Obtém o codificação do sistema de arquivos: a codificação usada com o manipulador de erros do sistema de arquivos para converter entre nomes de arquivos Unicode e nomes de arquivos de bytes. O manipulador de erros do sistema de arquivos é retornado de
getfilesystemencodeerrors()
.Para melhor compatibilidade, str deve ser usado para nomes de arquivos em todos os casos, embora a representação de nomes de arquivos como bytes também seja suportada. As funções que aceitam ou retornam nomes de arquivo devem suportar str ou bytes e converter internamente para a representação preferencial do sistema.
os.fsencode()
eos.fsdecode()
devem ser usados para garantir que a codificação correta e o modo de erros sejam usados.O tratador de erros e codificação do sistema de arquivos são configurados na inicialização do Python pela função
PyConfig_Read()
: veja os membrosfilesystem_encoding
efilesystem_errors
doPyConfig
.Alterado na versão 3.2: O resultado de
getfilesystemencoding()
não pode mais serNone
.Alterado na versão 3.6: O Windows não tem mais garantia de retornar
'mbcs'
. Veja PEP 529 e_enablelegacywindowsfsencoding()
para mais informações.Alterado na versão 3.7: Retorna
'utf-8'
se o Modo UTF-8 do Python estiver ativado.
- sys.getfilesystemencodeerrors()¶
Obtém o manipulador de erros do sistema de arquivos: o manipulador de erros usado com a codificação do sistema de arquivos para converter entre nomes de arquivos Unicode e nomes de arquivos de bytes. A codificação do sistema de arquivos é retornado de
getfilesystemencoding()
.os.fsencode()
eos.fsdecode()
devem ser usados para garantir que a codificação correta e o modo de erros sejam usados.O tratador de erros e codificação do sistema de arquivos são configurados na inicialização do Python pela função
PyConfig_Read()
: veja os membrosfilesystem_encoding
efilesystem_errors
doPyConfig
.Adicionado na versão 3.6.
- sys.get_int_max_str_digits()¶
Retorna o valor atual para a limitação de comprimento de string na conversão para inteiro. Veja também
set_int_max_str_digits()
.Adicionado na versão 3.11.
- sys.getrefcount(object)¶
Retorna a contagem de referências do object. A contagem retornada é geralmente um valor maior do que o esperado, porque inclui a referência (temporária) como um argumento para
getrefcount()
.Observe que o valor retornado pode não refletir realmente quantas referências ao objeto são realmente mantidas. Por exemplo, alguns objetos são imortais e têm uma refcount muito alta que não reflete o número real de referências. Consequentemente, não confie no valor retornado para ser preciso, exceto um valor de 0 ou 1.
Alterado na versão 3.12: Objetos imortais têm contagens de referência muito grandes que não correspondem ao número real de referências ao objeto.
- sys.getrecursionlimit()¶
Retorna o valor atual do limite de recursão, a profundidade máxima da pilha do interpretador Python. Esse limite evita que a recursão infinita cause um estouro da pilha C e falhe o Python. Pode ser definido por
setrecursionlimit()
.
- sys.getsizeof(object[, default])¶
Retorna o tamanho de um objeto em bytes. O objeto pode ser qualquer tipo de objeto. Todos os objetos embutidos retornarão resultados corretos, mas isso não precisa ser verdadeiro para extensões de terceiros, pois é específico da implementação.
Apenas o consumo de memória diretamente atribuído ao objeto é contabilizado, não o consumo de memória dos objetos a que ele se refere.
Se fornecido, default será retornado se o objeto não fornecer meios para recuperar o tamanho. Caso contrário, uma exceção
TypeError
será levantada.getsizeof()
chama o método__sizeof__
do objeto e adiciona uma sobrecarga adicional do coletor de lixo se o objeto for gerenciado pelo coletor de lixo.Consulte receita de tamanho recursivo para obter um exemplo de uso de
getsizeof()
recursivamente para encontrar o tamanho dos contêineres e todo o seu conteúdo.
- sys.getswitchinterval()¶
Retorna o “intervalo de troca de thread” do interpretador; veja
setswitchinterval()
.Adicionado na versão 3.2.
- sys._getframe([depth])¶
Retorna um objeto quadro da pilha de chamadas. Se o inteiro opcional depth for fornecido, retorna o objeto de quadro que muitos chamam abaixo do topo da pilha. Se for mais profundo do que a pilha de chamadas,
ValueError
é levantada. O padrão para depth é zero, retornando o quadro no topo da pilha de chamadas.Levanta um evento de auditoria
sys._getframe
com o argumentoframe
.Detalhes da implementação do CPython: Esta função deve ser usada apenas para fins internos e especializados. Não é garantido que exista em todas as implementações do Python.
- sys._getframemodulename([depth])¶
Retorna o nome de um módulo da pilha de chamadas. Se o inteiro opcional depth for fornecido, retorna o módulo que muitas chamadas abaixo do topo da pilha. Se for mais profundo do que a pilha de chamadas, ou se o módulo não for identificável,
None
é retornado. O padrão para depth é zero, retornando o módulo no topo da pilha de chamadas.Levanta um evento de auditoria
sys._getframemodulename
com o argumentodepth
.Detalhes da implementação do CPython: Esta função deve ser usada apenas para fins internos e especializados. Não é garantido que exista em todas as implementações do Python.
- sys.getprofile()¶
Obtém a função do criador de perfil conforme definido por
setprofile()
.
- sys.gettrace()¶
Obtém a função trace conforme definido por
settrace()
.Detalhes da implementação do CPython: A função
gettrace()
destina-se apenas à implementação de depuradores, perfiladores, ferramentas de cobertura e similares. Seu comportamento faz parte da plataforma de implementação, e não da definição da linguagem e, portanto, pode não estar disponível em todas as implementações do Python.
- sys.getwindowsversion()¶
Retorna uma tupla nomeada que descreve a versão do Windows em execução no momento. Os elementos nomeados são major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type e platform_version. service_pack contém uma string, platform_version uma tupla de 3 elementos e todos os outros valores são inteiros. Os componentes também podem ser acessados pelo nome, então
sys.getwindowsversion()[0]
é equivalente asys.getwindowsversion().major
. Para compatibilidade com versões anteriores, apenas os primeiros 5 elementos são recuperáveis por indexação.platform será
2
(VER_PLATFORM_WIN32_NT).product_type pode ser um dos seguintes valores:
Constante
Significado
1
(VER_NT_WORKSTATION)O sistema é uma estação de trabalho
2
(VER_NT_DOMAIN_CONTROLLER)O sistema é um controlador de domínio.
3
(VER_NT_SERVER)O sistema é um servidor, mas não um controlador de domínio.
Esta função atua como um envólucro em volta da função Win32
GetVersionEx()
; consulte a documentação da Microsoft emOSVERSIONINFOEX()
para obter mais informações sobre esses campos.platform_version retorna a versão principal, a versão secundária e o número de compilação do sistema operacional atual, em vez da versão que está sendo emulada para o processo. Destina-se a ser usado no registro, e não na detecção de recursos.
Nota
platform_version deriva a versão de kernel32.dll que pode ser de uma versão diferente da versão do sistema operacional. Use o módulo
platform
para obter a versão precisa do sistema operacional.Disponibilidade: Windows.
Alterado na versão 3.2: Alterado para uma tupla nomeada e adicionado service_pack_minor, service_pack_major, suite_mask e product_type.
Alterado na versão 3.6: Adicionado platform_version
- sys.get_asyncgen_hooks()¶
Retorna um objeto asyncgen_hooks, que é semelhante a um
namedtuple
no formato(firstiter, finalizer)
, onde firstiter e finalizer devem serNone
ou funções que recebem um iterador gerador assíncrono como argumento e são usadas para agendar a finalização de um gerador assíncrono por um laço de eventos.Adicionado na versão 3.6: Veja PEP 525 para mais detalhes.
Nota
Esta função foi adicionada provisoriamente (veja PEP 411 para detalhes.)
- sys.get_coroutine_origin_tracking_depth()¶
Obtém a profundidade de rastreamento da origem da corrotina atual, conforme definido por
set_coroutine_origin_tracking_depth()
.Adicionado na versão 3.7.
Nota
Esta função foi adicionada provisoriamente (veja PEP 411 para detalhes.) Use-a apenas para propósitos de depuração.
- sys.hash_info¶
Uma tupla nomeada fornecendo parâmetros da implementação de hash numérico. Para mais detalhes sobre hashing de tipos numéricos, veja Hashing de tipos numéricos.
- hash_info.width¶
A largura em bits usada para fazer hash de valores
- hash_info.modulus¶
O módulo primo P usado para esquema de hash numérico
- hash_info.inf¶
O valor de hash retornado para um infinito positivo
- hash_info.nan¶
(Este atributo não é mais usado)
- hash_info.imag¶
O multiplicador usado para a parte imaginária de um número complexo
- hash_info.algorithm¶
O nome do algoritmo para hash de str, bytes e memoryview
- hash_info.hash_bits¶
O tamanho da saída interna do algoritmo de hash
- hash_info.seed_bits¶
O tamanho da chave semente do algoritmo hash
Adicionado na versão 3.2.
Alterado na versão 3.4: Adicionado algorithm, hash_bits e seed_bits
- sys.hexversion¶
O número da versão codificado como um único inteiro. Isso é garantido para aumentar com cada versão, incluindo suporte adequado para lançamentos de não produção. Por exemplo, para testar se o interpretador Python é pelo menos a versão 1.5.2, use:
if sys.hexversion >= 0x010502F0: # use some advanced feature ... else: # use an alternative implementation or warn the user ...
Isso é chamado
hexversion
já que só parece realmente significativo quando visto como o resultado de passá-lo para a função embutidahex()
. A tupla nomeadasys.version_info
pode ser usada para uma codificação mais amigável das mesmas informações.Mais detalhes sobre
hexversion
podem ser encontrados em API e Versionamento de ABI.
- sys.implementation¶
Um objeto que contém informações sobre a implementação do interpretador Python em execução no momento. Os atributos a seguir devem existir em todas as implementações do Python.
name é o identificador da implementação, por exemplo
'cpython'
. A string real é definida pela implementação do Python, mas é garantido que seja minúscula.version é uma tupla nomeada, no mesmo formato que
sys.version_info
. Ela representa a versão da implementação Python em implementation. Isso tem um significado distinto da versão específica da linguagem Python à qual o interpretador em execução no momento está em conformidade, quesys.version_info
representa. Por exemplo, para PyPy 1.8sys.implementation.version
pode sersys.version_info(1, 8, 0, 'final', 0)
, enquantosys.version_info
seriasys.version_info(2, 7, 2, 'final', 0)
. Para CPython, eles são o mesmo valor, pois é a implementação de referência.hexversion é a versão de implementação em formato hexadecimal, como
sys.hexversion
.cache_tag é a tag usada pelo mecanismo de importação nos nomes de arquivo dos módulos em cache. Por convenção, seria um composto do nome e da versão da implementação, como
'cpython-33'
. No entanto, uma implementação Python pode usar algum outro valor, se apropriado. Secache_tag
for definido comoNone
, isso indica que o cache do módulo deve ser desabilitado.sys.implementation
pode conter atributos adicionais específicos para a implementação do Python. Esses atributos não padrão devem começar com um sublinhado e não são descritos aqui. Independentemente do seu conteúdo,sys.implementation
não mudará durante uma execução do interpretador, nem entre versões de implementação. (No entanto, ele pode mudar entre versões da linguagem Python.) Veja a PEP 421 para mais informações.Adicionado na versão 3.3.
Nota
A adição de novos atributos obrigatórios deve passar pelo processo normal de PEPs. Veja a PEP 421 para mais informações.
- sys.int_info¶
Uma tupla nomeada que contém informações sobre a representação interna de inteiros do Python. Os atributos são somente leitura.
- int_info.bits_per_digit¶
O número de bits mantidos em cada dígito. Os inteiros do Python são armazenados internamente na base
2**int_info.bits_per_digit
.
- int_info.sizeof_digit¶
O tamanho em bytes do tipo C usado para representar um dígito.
- int_info.default_max_str_digits¶
O valor padrão para
sys.get_int_max_str_digits()
quando não estiver explicitamente configurado.
- int_info.str_digits_check_threshold¶
O valor mínimo diferente de zero para
sys.set_int_max_str_digits()
,PYTHONINTMAXSTRDIGITS
ou-X int_max_str_digits
.
Adicionado na versão 3.1.
Alterado na versão 3.11: Adicionados
default_max_str_digits
estr_digits_check_threshold
.
- sys.__interactivehook__¶
Quando esse atributo existe, seu valor é chamado automaticamente (sem argumentos) quando o interpretador é iniciado em modo interativo. Isso é feito após o arquivo
PYTHONSTARTUP
ser lido, para que você possa definir esse gancho lá. O módulosite
define isso.Levanta um evento de auditoria
cpython.run_interactivehook
com o objeto gancho como o argumento quando o gancho é chamado na inicialização.Adicionado na versão 3.4.
- sys.intern(string)¶
Insere string na tabela de strings “internalizadas” e retorna a string internalizada – que é a própria string ou uma cópia. Strings internalizadas são úteis para obter um pouco de desempenho na pesquisa de dicionário – se as chaves em um dicionário foram internalizadas, e a chave de pesquisa para internalizada, já que comparações de chaves (após o hash) podem ser feitas por uma comparação de ponteiros em vez de uma comparação de strings. Normalmente, os nomes usados em programas Python são internalizados automaticamente, e os dicionários usados para armazenar atributos de módulo, classe ou instância têm chaves internalizadas.
Strings internalizadas não são imortais; você deve manter uma referência ao valor de retorno de
intern()
para se beneficiar dela.
- sys._is_gil_enabled()¶
Retorna
True
se a GIL estiver habiltada eFalse
caso contrário.Adicionado na versão 3.13.
- sys.is_finalizing()¶
Retorna
True
se o interpretador Python principal estiver desligando. RetornaFalse
caso contrário.Veja também a exceção
PythonFinalizationError
.Adicionado na versão 3.5.
- sys.last_exc¶
Esta variável nem sempre está definida; ela é definida para a instância de exceção quando uma exceção não é tratada e o interpretador imprime uma mensagem de erro e um stack traceback. Seu uso pretendido é permitir que um usuário interativo importe um módulo depurador e se envolva na depuração post-mortem sem ter que reexecutar o comando que causou o erro. (O uso típico é
import pdb; pdb.pm()
para entrar no depurador post-mortem; veja o módulopdb
para mais informações.)Adicionado na versão 3.12.
- sys._is_interned(string)¶
Retorna
True
se a string fornecida for “internalizada”,False
caso contrário.Adicionado na versão 3.13.
Detalhes da implementação do CPython: Não há garantia de que exista em todas as implementações do Python.
- sys.last_type¶
- sys.last_value¶
- sys.last_traceback¶
Essas três variáveis estão descontinuadas; use
sys.last_exc
em vez disso. Elas mantêm a representação legada desys.last_exc
, conforme retornada deexc_info()
acima.
- sys.maxsize¶
Um inteiro que fornece o valor máximo que uma variável do tipo
Py_ssize_t
pode assumir. Geralmente é2**31 - 1
em uma plataforma de 32 bits e2**63 - 1
em uma plataforma de 64 bits.
- sys.maxunicode¶
Um inteiro que fornece o valor do maior ponto de código Unicode, ou seja,
1114111
(0x10FFFF
em hexadecimal).Alterado na versão 3.3: Antes da PEP 393,
sys.maxunicode
costumava ser0xFFFF
ou0x10FFFF
, dependendo da opção de configuração que especificava se os caracteres Unicode eram armazenados como UCS-2 ou UCS-4.
- sys.meta_path¶
Uma lista de objetos localizador de metacaminho que têm seus métodos
find_spec()
chamados para ver se um dos objetos consegue encontrar o módulo a ser importado. Por padrão, ele contém entradas que implementam a semântica de importação padrão do Python. O métodofind_spec()
é chamado com pelo menos o nome absoluto do módulo que está sendo importado. Se o módulo a ser importado estiver contido em um pacote, o atributo__path__
do pacote pai é passado como um segundo argumento. O método retorna uma especificação do módulo, ouNone
se o módulo não puder ser encontrado.Ver também
importlib.abc.MetaPathFinder
A classe base abstrata que define a interface dos objetos localizadores em
meta_path
.importlib.machinery.ModuleSpec
A classe concreta da qual
find_spec()
deve retornar instâncias.
Alterado na versão 3.4: Especificações de módulo foram introduzidas no Python 3.4, pela PEP 451.
Alterado na versão 3.12: Foi removido o alternativa que procurava um método
find_module()
se uma entradameta_path
não tivesse um métodofind_spec()
.
- sys.modules¶
Este é um dicionário que mapeia nomes de módulos para módulos que já foram carregados. Isso pode ser manipulado para forçar o recarregamento de módulos e outros truques. No entanto, substituir o dicionário não vai funcionar necessariamente como esperado e excluir itens essenciais do dicionário pode fazer com que o Python falhe. Se você quiser iterar sobre este dicionário global, sempre use
sys.modules.copy()
outuple(sys.modules)
para evitar exceções, pois seu tamanho pode mudar durante a iteração como um efeito colateral do código ou atividade em outros threads.
- sys.orig_argv¶
A lista dos argumentos originais da linha de comando passados para o executável Python.
Os elementos de
sys.orig_argv
são os argumentos para o interpretador Python, enquanto os elementos desys.argv
são os argumentos para o programa do usuário. Os argumentos consumidos pelo próprio interpretador estarão presentes emsys.orig_argv
e ausentes emsys.argv
.Adicionado na versão 3.10.
- sys.path¶
Uma lista de strings que especifica o caminho de pesquisa para módulos. Inicializado a partir da variável de ambiente
PYTHONPATH
, mais um padrão dependente da instalação.Por padrão, conforme inicializado na inicialização do programa, um caminho potencialmente inseguro é adicionado ao
sys.path
(antes das entradas inseridas como resultado dePYTHONPATH
):A linha de comando
python -m módulo
: adiciona o diretório de trabalho atualA linha de comando
python script.py
: prefixa o diretório do script. Se for um link simbólico, resolve links simbólicos.As linhas de comando
python -c código
epython
(REPL): adiciona uma string vazia, que indica o diretório de trabalho atual.
Para não acrescentar esse caminho potencialmente inseguro, use a opção de linha de comando
-P
ou a variável de ambientePYTHONSAFEPATH
.Um programa é livre para modificar esta lista para seus próprios propósitos. Somente strings devem ser adicionadas a
sys.path
; todos os outros tipos de dados são ignorados durante a importação.
- sys.path_hooks¶
Uma lista de chamáveis que recebem um argumento de caminho para tentar criar um localizador para o caminho. Se um localizador puder ser criado, ele deve ser retornado pelo chamável, senão, ele levanta
ImportError
.Originalmente especificado na PEP 302.
- sys.path_importer_cache¶
Um dicionário atuando como um cache para objetos do localizador. As chaves são caminhos que foram passados para
sys.path_hooks
e os valores são os localizadores que são encontrados. Se um caminho for um caminho de sistema de arquivo válido, mas nenhum localizador for encontrado emsys.path_hooks
, entãoNone
é armazenado.Originalmente especificado na PEP 302.
- sys.platform¶
Uma string contendo um identificador da plataforma. Valores conhecidos são:
Sistema
Valor de
platform
AIX
'aix'
Android
'android'
Emscripten
'emscripten'
iOS
'ios'
Linux
'linux'
macOS
'darwin'
Windows
'win32'
Windows/Cygwin
'cygwin'
WASI
'wasi'
Em sistemas Unix não listados na tabela, o valor é o nome do sistema operacional em letras minúsculas, conforme retornado por
uname -s
, com a primeira parte da versão, conforme retornado poruname -r
anexada, por exemplo,'sunos5'
ou'freebsd8'
, no momento em que o Python foi construído. A menos que você queira testar uma versão específica do sistema, é recomendável usar o seguinte idioma:if sys.platform.startswith('freebsd'): # FreeBSD-specific code here...
Alterado na versão 3.3: No Linux,
sys.platform
não contém mais a versão principal. É sempre'linux'
, em vez de'linux2'
ou'linux3'
.Alterado na versão 3.8: No AIX,
sys.platform
não contém mais a versão principal. É sempre'aix'
, em vez de'aix5'
ou'aix7'
.Alterado na versão 3.13: No Android,
sys.platform
agora retorna'android'
em vez de'linux'
.Ver também
os.name
tem uma granularidade mais substancial.os.uname()
fornece informações de versão dependentes do sistema.O módulo
platform
fornece verificações detalhadas sobre a identificação do sistema.
- sys.platlibdir¶
Nome do diretório da biblioteca específica da plataforma. É usado para construir o caminho da biblioteca padrão e os caminhos dos módulos de extensão instalados.
É igual a
"lib"
na maioria das plataformas. No Fedora e SuSE, é igual a"lib64"
em plataformas de 64 bits, o que fornece os seguintes caminhossys.path
(ondeX.Y
é a versãomajor.minor
do Python):/usr/lib64/pythonX.Y/
: Biblioteca padrão (comoos.py
do móduloos
)/usr/lib64/pythonX.Y/lib-dynload/
: Módulos de extensão C da biblioteca padrão (como o móduloerrno
, o nome exato do arquivo é específico da plataforma)/usr/lib/pythonX.Y/site-packages/
(sempre usalib
, nãosys.platlibdir
): Módulos de terceiros/usr/lib64/pythonX.Y/site-packages/
: Módulos de extensão C de pacotes de terceiros
Adicionado na versão 3.9.
- sys.prefix¶
Uma string que fornece o prefixo do diretório específico do site onde os arquivos Python independentes de plataforma são instalados; no Unix, o padrão é
/usr/local
. Isso pode ser definido no momento da construção com o argumento--prefix
para o script configure. Veja Caminhos de instalação para caminhos derivados.Nota
Se um ambiente virtual estiver em vigor, este valor será alterado em
site.py
para apontar para o ambiente virtual. O valor para a instalação do Python ainda estará disponível, viabase_prefix
.
- sys.ps1¶
- sys.ps2¶
Strings especificando o prompt primário e secundário do interpretador. Elas são definidas somente se o interpretador estiver no modo interativo. Seus valores iniciais neste caso são
'>>> '
e'... '
. Se um objeto não string for atribuído a qualquer variável, seustr()
é reavaliado cada vez que o interpretador se prepara para ler um novo comando interativo; isso pode ser usado para implementar um prompt dinâmico.
- sys.setdlopenflags(n)¶
Define os sinalizadores usados pelo interpretador para chamadas
dlopen()
, como quando o interpretador carrega módulos de extensão. Entre outras coisas, isso habilitará uma resolução preguiçosa de símbolos ao importar um módulo, se chamado comosys.setdlopenflags(0)
. Para compartilhar símbolos entre módulos de extensão, chame comosys.setdlopenflags(os.RTLD_GLOBAL)
. Nomes simbólicos para os valores de sinalizadores podem ser encontrados no móduloos
(constantesRTLD_xxx
, por exemplo,os.RTLD_LAZY
).Disponibilidade: Unix.
- sys.set_int_max_str_digits(maxdigits)¶
Define a limitação de comprimento de string na conversão para inteiro usada por este interpretador. Veja também
get_int_max_str_digits()
.Adicionado na versão 3.11.
- sys.setprofile(profilefunc)¶
Define a função de perfil do sistema, que permite implementar um perfilador de código-fonte Python em Python. Veja o capítulo The Python Profilers para mais informações sobre o perfilador Python. A função de perfil do sistema é chamada de forma semelhante à função de rastreamento do sistema (veja
settrace()
), mas é chamada com eventos diferentes, por exemplo, não é chamada para cada linha de código executada (apenas na chamada e retorno, mas o evento de retorno é relatado mesmo quando uma exceção foi definida). A função é específica do thread, mas não há como o perfilador saber sobre trocas de contexto entre threads, então não faz sentido usá-la na presença de vários threads. Além disso, seu valor de retorno não é usado, então ele pode simplesmente retornarNone
. Um erro na função de perfil fará com que sua própria definição seja removida.Nota
O mesmo mecanismo de rastreamento é usado para
setprofile()
comosettrace()
. Para rastrear chamadas comsetprofile()
dentro de uma função de rastreamento (por exemplo, em um ponto de interrupção do depurador), consultecall_tracing()
.As funções de perfil devem ter três argumentos: frame, event e arg. frame é o quadro de pilha atual. event é uma string:
'call'
,'return'
,'c_call'
,'c_return'
ou'c_exception'
. arg depende do tipo de evento.Os eventos têm o seguinte significado:
'call'
Uma função é chamada (ou algum outro bloco de código é inserido). A função de perfil é chamada; arg é
None
.'return'
Uma função (ou outro bloco de código) está prestes a retornar. A função de perfilação é chamada; arg é o valor que será retornado, ou
None
se o evento for causado por uma exceção sendo levantada.'c_call'
Uma função C está prestes a ser chamada. Pode ser uma função de extensão ou uma embutida. arg é o objeto da função C.
'c_return'
Uma função C foi retornada. arg é o objeto da função C.
'c_exception'
Uma função C levantou uma exceção. arg é o objeto da função C.
Levanta um evento de auditoria
sys.setprofile
sem argumentos.
- sys.setrecursionlimit(limit)¶
Define a profundidade máxima da pilha do interpretador Python para limit. Esse limite impede que a recursão infinita cause um estouro da pilha C e trave o Python.
O limite mais alto possível depende da plataforma. Um usuário pode precisar definir o limite mais alto quando tiver um programa que exija recursão profunda e uma plataforma que dê suporte a um limite mais alto. Isso deve ser feito com cuidado, porque um limite muito alto pode levar a uma falha.
Se o novo limite for muito baixo na profundidade de recursão atual, uma exceção
RecursionError
será levantada.Alterado na versão 3.5.1: Uma exceção
RecursionError
agora é levantada se o novo limite for muito baixo na profundidade de recursão atual.
- sys.setswitchinterval(interval)¶
Define o intervalo de troca de thread do interpretador (em segundos). Este valor de ponto flutuante determina a duração ideal das “fatias de tempo” alocadas para threads Python em execução simultânea. Observe que o valor real pode ser maior, especialmente se funções ou métodos internos de execução longa forem usados. Além disso, qual thread se torna agendada no final do intervalo é uma decisão do sistema operacional. O interpretador não tem seu próprio escalonador.
Adicionado na versão 3.2.
- sys.settrace(tracefunc)¶
Define a função trace do sistema, que permite que você implemente um depurador de código-fonte Python em Python. A função é específica de thread; para um depurador suportar múltiplas threads, ele deve registrar uma função trace usando
settrace()
para cada thread que está sendo depurada ou usarthreading.settrace()
.As funções de rastreamento devem ter três argumentos: frame, event e arg. frame é o quadro de pilha atual. event é uma string:
'call'
,'line'
,'return'
,'exception'
ou'opcode'
. arg depende do tipo de evento.A função de rastreamento é invocada (com event definido como
'call'
) sempre que um novo escopo local é inserido; ela deve retornar uma referência a uma função de rastreamento local a ser usada para o novo escopo, ouNone
se o escopo não deve ser rastreado.A função de rastreamento local deve retornar uma referência a si mesma ou a outra função que seria então usada como a função de rastreamento local para o escopo.
Se ocorrer algum erro na função de rastreamento, ela será desativada, assim como
settrace(None)
é chamado.Nota
O rastreamento é desabilitado ao chamar a função de rastreamento (por exemplo, uma função definida por
settrace()
). Para rastreamento recursivo, vejacall_tracing()
.Os eventos têm o seguinte significado:
'call'
Uma função é chamada (ou algum outro bloco de código é inserido). A função de rastreamento global é chamada; arg é
None
; o valor de retorno especifica a função de rastreamento local.'line'
O interpretador está prestes a executar uma nova linha de código ou reexecutar a condição de um laço. A função de rastreamento local é chamada; arg é
None
; o valor de retorno especifica a nova função de rastreamento local. VejaObjects/lnotab_notes.txt
para uma explicação detalhada de como isso funciona. Eventos por linha podem ser desabilitados para um quadro definindof_trace_lines
comoFalse
naquele quadro.'return'
Uma função (ou outro bloco de código) está prestes a retornar. A função de rastreamento local é chamada; arg é o valor que será retornado, ou
None
se o evento for causado por uma exceção sendo levantada. O valor de retorno da função de rastreamento é ignorado.'exception'
Ocorreu uma exceção. A função de rastreamento local é chamada; arg é uma tupla
(exception, value, traceback)
; o valor de retorno especifica a nova função de rastreamento local.'opcode'
O interpretador está prestes a executar um novo opcode (veja
dis
para detalhes do opcode). A função de rastreamento local é chamada; arg éNone
; o valor de retorno especifica a nova função de rastreamento local. Eventos por opcode não são emitidos por padrão: eles devem ser explicitamente solicitados definindof_trace_opcodes
comoTrue
no quadro.
Observe que, à medida que uma exceção é propagada pela cadeia de chamadores, um evento
'exception'
é gerado em cada nível.Para um uso mais refinado, é possível definir uma função de rastreamento atribuindo
frame.f_trace = tracefunc
explicitamente, em vez de depender de ser definida indiretamente por meio do valor de retorno de uma função de rastreamento já instalada. Isso também é necessário para ativar a função de rastreamento no quadro atual, o quesettrace()
não faz. Observe que, para que isso funcione, uma função de rastreamento global deve ter sido instalada comsettrace()
para habilitar o maquinário de rastreamento em tempo de execução, mas não precisa ser a mesma função de rastreamento (por exemplo, pode ser uma função de rastreamento de baixa sobrecarga que simplesmente retornaNone
para se desabilitar imediatamente em cada quadro).Para mais informações sobre objetos de código e quadro, consulte A hierarquia de tipos padrão.
Levanta um evento de auditoria
sys.settrace
sem argumentos.Detalhes da implementação do CPython: A função
settrace()
destina-se apenas à implementação de depuradores, perfiladores, ferramentas de cobertura e similares. Seu comportamento faz parte da plataforma de implementação, e não da definição da linguagem e, portanto, pode não estar disponível em todas as implementações do Python.Alterado na versão 3.7: Tipo de evento
'opcode'
adicionado; atributosf_trace_lines
ef_trace_opcodes
adicionados a quadros
- sys.set_asyncgen_hooks([firstiter] [, finalizer])¶
Aceita dois argumentos nomeados opcionais que são chamáveis que aceitam um iterador gerador assíncrono como argumento. O chamável firstiter será chamado quando um gerador assíncrono for iterado pela primeira vez. O finalizer será chamado quando um gerador assíncrono estiver prestes a ser coletado como lixo.
Levanta um evento de auditoria
sys.set_asyncgen_hooks_firstiter
sem argumentos.Levanta um evento de auditoria
sys.set_asyncgen_hooks_finalizer
sem argumentos.Dois eventos de auditoria são gerados porque a API subjacente consiste em duas chamadas, cada uma das quais deve levantar seu próprio evento.
Adicionado na versão 3.6: Veja a PEP 525 para mais detalhes, e para um exemplo de referência de um método finalizer veja a implementação de
asyncio.Loop.shutdown_asyncgens
em Lib/asyncio/base_events.pyNota
Esta função foi adicionada provisoriamente (veja PEP 411 para detalhes.)
- sys.set_coroutine_origin_tracking_depth(depth)¶
Permite habilitar ou desabilitar o rastreamento de origem de corrotina. Quando habilitado, o atributo
cr_origin
em objetos de corrotina conterá uma tupla de tuplas (nome do arquivo, número da linha, nome da função) descrevendo o traceback onde o objeto corrotina foi criado, com a chamada mais recente primeiro. Quando desabilitado,cr_origin
seráNone
.To enable, pass a depth value greater than zero; this sets the number of frames whose information will be captured. To disable, set depth to zero.
Esta configuração é específica do thread.
Adicionado na versão 3.7.
Nota
Esta função foi adicionada provisoriamente (veja PEP 411 para detalhes.) Use-a apenas para propósitos de depuração.
- sys.activate_stack_trampoline(backend, /)¶
Ativa o trampolim do perfilador de pilha backend. O único backend suportado é
"perf"
.Disponibilidade: Linux.
Adicionado na versão 3.12.
- sys.deactivate_stack_trampoline()¶
Desativa o backend trampolim do perfilador de pilha atual.
Se nenhum perfilador de pilha estiver ativado, esta função não terá efeito.
Disponibilidade: Linux.
Adicionado na versão 3.12.
- sys.is_stack_trampoline_active()¶
Retorna
True
se um trampolim de perfilador de pilha estiver ativo.Disponibilidade: Linux.
Adicionado na versão 3.12.
- sys._enablelegacywindowsfsencoding()¶
Altera tratador de erros e codificação do sistema de arquivos para ‘replace’ e ‘mbcs’ respectivamente, para consistência com versões do Python anteriores à 3.6.
Isso é equivalente a definir a variável de ambiente
PYTHONLEGACYWINDOWSFSENCODING
antes de iniciar o Python.Veja também
sys.getfilesystemencoding()
esys.getfilesystemencodeerrors()
.Disponibilidade: Windows.
Nota
Alterar a codificação do sistema de arquivos após a inicialização do Python é arriscado porque o fsencoding antigo ou os caminhos codificados pelo fsencoding antigo podem estar armazenados em cache em algum lugar. Use
PYTHONLEGACYWINDOWSFSENCODING
em vez disso.Adicionado na versão 3.6: Veja PEP 529 para mais detalhes.
Deprecated since version 3.13, will be removed in version 3.16: Use
PYTHONLEGACYWINDOWSFSENCODING
.
- sys.stdin¶
- sys.stdout¶
- sys.stderr¶
Objetos arquivo usados pelo interpretador para entrada padrão, saída e erros:
stdin
é usado para todas as entradas interativas (incluindo chamadas parainput()
);stdout
é usado para a saída das instruçõesprint()
e expressões e para os prompts deinput()
;Os prompts do próprio interpretador e suas mensagens de erro vão para
stderr
.
Esses fluxos são arquivos texto regulares como aqueles retornados pela função
open()
. Seus parâmetros são escolhidos da seguinte forma:A codificação e o tratamento de erros são inicializados a partir de
PyConfig.stdio_encoding
ePyConfig.stdio_errors
.No Windows, o UTF-8 é usado para o dispositivo de console. Dispositivos não-caracteres, como arquivos de disco e pipes, usam a codificação da localidade do sistema (ou seja, a página de código ANSI). Dispositivos de caracteres não-console, como NUL (ou seja, onde
isatty()
retornaTrue
) usam o valor das páginas de código de entrada e saída do console na inicialização, respectivamente para stdin e stdout/stderr. Isso assume como padrão a codificação da localidade do sistema se o processo não for inicialmente anexado a um console.O comportamento especial do console pode ser substituído definindo a variável de ambiente PYTHONLEGACYWINDOWSSTDIO antes de iniciar o Python. Nesse caso, as páginas de código do console são usadas como para qualquer outro dispositivo de caractere.
Em todas as plataformas, você pode substituir a codificação de caracteres definindo a variável de ambiente
PYTHONIOENCODING
antes de iniciar o Python ou usando a nova opção de linha de comando-X
utf8
e a variável de ambientePYTHONUTF8
. No entanto, para o console do Windows, isso só se aplica quandoPYTHONLEGACYWINDOWSSTDIO
também está definido.Quando interativo, o fluxo
stdout
é armazenado em buffer de linha. Caso contrário, ele é armazenado em buffer de bloco como arquivos texto comuns. O fluxostderr
é armazenado em buffer de linha em ambos os casos. Você pode tornar ambos os fluxos sem buffer passando a opção de linha de comando-u
ou definindo a variável de ambientePYTHONUNBUFFERED
.
Alterado na versão 3.9:
stderr
não interativo agora é armazenado em buffer de linha em vez de totalmente armazenado em buffer.Nota
Para escrever ou ler dados binários de/para os fluxos padrão, use o objeto binário subjacente
buffer
. Por exemplo, para escrever bytes emstdout
, usesys.stdout.buffer.write(b'abc')
.Entretanto, se você estiver escrevendo uma biblioteca (e não controlar em qual contexto seu código será executado), esteja ciente de que os fluxos padrão podem ser substituídos por objetos arquivo ou similar, como
io.StringIO
, que não oferecem suporte ao atributobuffer
.
- sys.__stdin__¶
- sys.__stdout__¶
- sys.__stderr__¶
Esses objetos contêm os valores originais de
stdin
,stderr
estdout
no início do programa. Eles são usados durante a finalização e podem ser úteis para imprimir no fluxo padrão real, não importa se o objetosys.std*
foi redirecionado.Ele também pode ser usado para restaurar os arquivos reais para objetos arquivo de trabalho conhecidos, caso tenham sido substituídos por um objeto quebrado. No entanto, a maneira preferida de fazer isso é salvar explicitamente o fluxo anterior antes de substituí-lo e restaurar o objeto salvo.
Nota
Sob algumas condições,
stdin
,stdout
estderr
, bem como os valores originais de__stdin__
,__stdout__
e__stderr__
podem serNone
. Geralmente é o caso de aplicativos GUI do Windows que não estão conectados a um console e aplicativos Python iniciados com pythonw.
- sys.stdlib_module_names¶
Um frozenset de strings contendo os nomes dos módulos da biblioteca padrão.
É o mesmo em todas as plataformas. Módulos que não estão disponíveis em algumas plataformas e módulos desabilitados na construção do Python também são listados. Todos os tipos de módulos são listados: Python puro, módulos embutidos, congelados e de extensão. Módulos de teste são excluídos.
Para pacotes, somente o pacote principal é listado: subpacotes e submódulos não são listados. Por exemplo, o pacote
email
é listado, mas o subpacoteemail.mime
e o submóduloemail.message
não são listados.Veja também a lista de
sys.builtin_module_names
.Adicionado na versão 3.10.
- sys.thread_info¶
Uma tupla nomeada contendo informações sobre a implementação de threads.
- thread_info.name¶
O nome da implementação da thread:
"nt"
: Threads do Windows"pthread"
: Threads do POSIX"pthread-stubs"
: stub POSIX threads (on WebAssembly platforms without threading support)"solaris"
: Threads do Solaris
- thread_info.lock¶
O nome da implementação de trava.
"semaphore"
: uma trava usa um semáforo"mutex+cond"
: uma trava usa um mutex e uma variável de condiçãoNone
se essa informação for desconhecida
- thread_info.version¶
O nome e a versão da biblioteca de threads. É uma string, ou
None
se essa informação for desconhecida.
Adicionado na versão 3.3.
- sys.tracebacklimit¶
Quando essa variável é definida como um valor inteiro, ela determina o número máximo de níveis de informações de traceback impressas quando ocorre uma exceção não tratada. O padrão é
1000
. Quando definida como0
ou menos, todas as informações de traceback são suprimidas e apenas o tipo e o valor da exceção são impressos.
- sys.unraisablehook(unraisable, /)¶
Manipula uma exceção não levantada
Chamada quando uma exceção ocorreu, mas não há como o Python manipulá-la. Por exemplo, quando um destrutor levanta uma exceção ou durante a coleta de lixo (
gc.collect()
).O argumento unraisable tem os seguintes atributos:
exc_type
: Tipo de exceção.exc_value
: Valor da exceção, pode serNone
.exc_traceback
: Traceback da exceção, pode serNone
.err_msg
: Mensagem de erro, pode serNone
.object
: O objeto que causa a exceção pode serNone
.
Os formatos de gancho padrão
err_msg
eobject
como:f'{err_msg}: {object!r}'
; usa a mensagem de erro “Exception ignored in” seerr_msg
forNone
.sys.unraisablehook()
pode ser substituída para controlar como exceções não levantáveis são manipuladas.Ver também
excepthook()
, que manipula exceções não capturadas.Aviso
Armazena
exc_value
usando um gancho personalizado pode criar um ciclo de referência. Ele deve ser limpo explicitamente para quebrar o ciclo de referência quando a exceção não for mais necessária.Armazenar
object
usando um gancho personalizado pode ressuscitá-lo se ele for definido como um objeto que está sendo finalizado. Evite armazenarobject
após o gancho personalizado ser concluído para evitar ressuscitar objetos.Levanta um evento de auditoria
sys.unraisablehook
com argumentos hook e unraisable quando ocorrer uma exceção que não puder ser manipulada. O objeto unraisable é o mesmo que será passado para o gancho. Se nenhum gancho tiver sido definido, hook pode serNone
.Adicionado na versão 3.8.
- sys.version¶
Uma string contendo o número da versão do interpretador Python mais informações adicionais sobre o número da construção e o compilador usado. Esta string é exibida quando o interpretador interativo é iniciado. Não extraia informações de versão dela, em vez disso, use
version_info
e as funções fornecidas pelo móduloplatform
.
- sys.api_version¶
A versão da API C para este interpretador. Programadores podem achar isso útil ao depurar conflitos de versão entre Python e módulos de extensão.
- sys.version_info¶
Uma tupla contendo os cinco componentes do número da versão: major, minor, micro, releaselevel e serial. Todos os valores, exceto releaselevel, são inteiros; o nível de versão é
'alpha'
,'beta'
,'candidate'
ou'final'
. O valorversion_info
correspondente à versão 2.0 do Python é(2, 0, 0, 'final', 0)
. Os componentes também podem ser acessados por nome, entãosys.version_info[0]
é equivalente asys.version_info.major
e assim por diante.Alterado na versão 3.1: Added named component attributes.
- sys.warnoptions¶
Este é um detalhe de implementação do framework de avisos; não modifique este valor. Consulte o módulo
warnings
para obter mais informações sobre o framework de avisos.
- sys.winver¶
O número da versão usado para formar chaves de registro em plataformas Windows. Isso é armazenado como recurso de string 1000 na DLL do Python. O valor normalmente é a versão principal e secundária do interpretador Python em execução. Ele é fornecido no módulo
sys
para fins informativos; modificar esse valor não tem efeito nas chaves de registro usadas pelo Python.Disponibilidade: Windows.
- sys.monitoring
Espaço de nomes contendo funções e constantes para função de retorno de registro e controle de eventos de monitoramento. Veja
sys.monitoring
para detalhes.
- sys._xoptions¶
Um dicionário dos vários sinalizadores específicos de implementação passados pela opção de linha de comando
-X
. Os nomes de opção são mapeados para seus valores, se fornecidos explicitamente, ou paraTrue
. Exemplo:$ ./python -Xa=b -Xc Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50) [GCC 4.4.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import sys >>> sys._xoptions {'a': 'b', 'c': True}
Detalhes da implementação do CPython: Esta é uma maneira específica do CPython de acessar opções passadas por
-X
. Outras implementações podem exportá-las por outros meios, ou não exportá-las.Adicionado na versão 3.2.
Citações
ISO/IEC 9899:1999. “Programming languages – C.” Um rascunho público desta norma está disponível em https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf.