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/python*version*" e
   "*exec_prefix*/lib/python*version*", 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/python*version*" (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:

   * "malloc": usa a função "malloc()" da biblioteca C para todos os
     domínios ("PYMEM_DOMAIN_RAW", "PYMEM_DOMAIN_MEM",
     "PYMEM_DOMAIN_OBJ").

   * "pymalloc": usa o alocador pymalloc para domínios
     "PYMEM_DOMAIN_MEM" e "PYMEM_DOMAIN_OBJ" e usa a função "malloc()"
     para o domínio "PYMEM_DOMAIN_RAW".

   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.
