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

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

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 -mtimeit -s 'setup here' 'benchmarked code here'
python -mtimeit -h # for details

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.

<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__.

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

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

-V
--version

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

Python 3.6.0b2+

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

Python 3.6.0b2+ (3.6:84a3c5003510+, Oct 26 2016, 02:33:55)
[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.

-d

Turn on parser debugging output (for wizards only, depending on compilation options). See also 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 copyright e de versão nem mesmo no modo interativo.

Novo na versão 3.2.

-R

Kept for compatibility. On Python 3.3 and greater, hash randomization is turned on by default.

On previous versions of Python, this option turns on hash randomization, so that the __hash__() values of str, bytes and datetime are “salted” with an unpredictable random value. Although they remain constant within an individual Python process, they are not predictable between repeated invocations of 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.

Novo na versão 3.2.3.

-s

Não adiciona o diretório de site-packages de usuário ` a :data:`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 :data:` 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

Force the binary layer of the stdout and stderr streams (which is available as their buffer attribute) to be unbuffered. The text I/O layer will still be line-buffered if writing to the console, or block-buffered if redirected to a non-interactive file.

Veja também PYTHONUNBUFFERED.

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

Warnings can also be controlled from within a Python program using the warnings module.

The simplest form of argument is one of the following action strings (or a unique abbreviation):

ignore

Ignore todas as advertências..

default

Explicitly request the default behavior (printing each warning once per source line).

all

Print a warning each time it occurs (this may generate many messages if a warning is triggered repeatedly for the same source line, such as inside a loop).

module

Print each warning only the first time it occurs in each module.

once

Print each warning only the first time it occurs in the program.

error

Raise an exception instead of printing a warning message.

A forma completa de argumento é:

action:message:category:module:line

Here, action is as explained above but only applies to messages that match the remaining fields. Empty fields match all values; trailing empty fields may be omitted. The message field matches the start of the warning message printed; this match is case-insensitive. The category field matches the warning category. This must be a class name; the match tests whether the actual warning category of the message is a subclass of the specified warning category. The full class name must be given. The module field matches the (fully-qualified) module name; this match is case-sensitive. The line field matches the line number, where zero matches all line numbers and is thus equivalent to an omitted line number.

Ver também

warnings – the warnings module

PEP 230 – Warning framework

PYTHONWARNINGS

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

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 .

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 namespace 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.

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.

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.

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.

PYTHONHASHSEED

If this variable is not set or set to random, a random value is used to seed the hashes of str, bytes and datetime objects.

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.

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 user site-packages directory ` a :data:`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

This is equivalent to the -W option. If set to a comma separated string, it is equivalent to specifying -W multiple times.

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.

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: install debug hooks on top of the default memory allocator

  • malloc_debug: same as malloc but also install debug hooks

  • pymalloc_debug: same as pymalloc but also install debug hooks

When Python is compiled in release mode, the default is pymalloc. When compiled in debug mode, the default is pymalloc_debug and the debug hooks are used automatically.

If Python is configured without pymalloc support, pymalloc and pymalloc_debug are not available, the default is malloc in release mode and malloc_debug in debug mode.

See the PyMem_SetupDebugHooks() function for debug hooks on Python memory allocators.

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

Availability: 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.

Availability: Windows

Novo na versão 3.6.

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

Setting these variables only has an effect in a debug build of Python, that is, if Python was configured with the --with-pydebug build option.

PYTHONTHREADDEBUG

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

PYTHONDUMPREFS

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