3. Utilizando Python no Windows
*******************************

Este documento pretende dar uma visão geral do comportamento
específico do Windows que você deve conhecer quando fores utilizar o
Python no sistema operacional Microsoft Windows.


3.1. Instalando o Python
========================

Diferente da maioria dos sistemas e serviços Unix, o Windows não
inclui uma instalação suportada do Python. Para deixar o Python
disponível, o time CPython compilou os instaladores do Windows
(pacotes MSI) com cada versão por vários anos. Esses instaladores têm
a intenção primária de adicionar uma instalação de Python por usuário,
com o interpretador e as bibliotecas núcleo sendo utilizadas por um
único usuário. O instalador também é capaz de instalar para todos os
usuários de uma única máquina, e um arquivo ZIP separado está
disponível para distribuições locais de aplicação.


3.1.1. Versões Suportadas
-------------------------

Como especificado na **PEP 11**, uma versão Python suporta apenas uma
plataforma Windows enquanto a Microsoft considera a plataforma sob
suporte extendido. Isso significa que o Python 3.6 suporta Windows
Vista ou superiores. Se você requer suporte à Windows XP, então por
favor instale o Python 3.4.


3.1.2. Etapas de Instalação
---------------------------

Quatro instaladores Python 3.6 estão disponíveis para download - dois
de cada para as versões 32-bit e 64-bit do interpretador. O
*instalador web* é um download inicial menor, e ele irá
automaticamente fazer o download dos componentes solicitados na medida
do necessário. O *instalador offline* inclui os componentes
necessários para uma instalação padrão e requer apenas uma conexão de
internet para recursos opcionais. Veja Instalando Sem Download para
outras formas de evitar o download durante a instalação.

Após iniciar o instalador, uma de duas opções deve ser selecionada:

[imagem]

Se você selecionar "Install Now":

* Você *não* precisará ser um administrador (a menos que uma
  atualização de sistema para a Biblioteca em Tempo de Execução C seja
  necessária ou que você instale o Inicializador Python para Windows
  para todos os usuários)

* Python será instalado dentro do seu diretório de usuário

* O Inicializador Python para Windows será instalado de acordo com a
  opção ao final da primeira página

* A biblioteca padrão, a suíte de testes, o inicializador e o pip
  serão instalados

* Se selecionado, o diretório de instalação será adicionado no seu
  "PATH"

* Atalhos serão visíveis apenas para o usuário atual

Selecionando "Customize installation" irá permitir que você selecione
os recursos a serem instalados, o local da instalação e outras opções
ou ações pós-instalação. Para instalar símbolos de depuração ou
binários, você precisará usar essa opção.

Para realizar uma instalação para todos os usuários, você deve
selecionar "Customize installation". Neste caso:

* Você pode ser solicitado a providenciar credenciais administrativas
  ou aprovação

* Python será instalado dentro do diretório Program Files

* O Inicializador Python para Windows será instalado dentro do
  diretório Windows

* Recursos opcionais podem ser selecionados durante a instalação

* A biblioteca padrão pode ser pré-compilada em bytecode

* Se selecionado, o diretório de instalação será adicionado ao  "PATH"
  do sistema

* Atalhos estão disponíveis para todos os usuários


3.1.3. Removendo a limitação do MAX_PATH
----------------------------------------

O Windows historicamente tem limitado os comprimentos dos caminhos de
arquivos em 260 caracteres. Isso significava que caminhos maiores que
isso não seriam resolvidos e resultariam em erros.

Nas últimas versões do Windows, essa limitação pode ser expandida para
aproximadamente 32.000 caracteres. Seu administrador irá precisar
ativar a política de grupo "Enable Win32 long paths", ou definir um
valor de registro "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Contro
l\FileSystem@LongPathsEnabled" para "1".

Isso permite que a função "open()", o módulo "os" e a maior parte das
outras funcionalidades de caminho aceitem e retornem caminhos maiores
que 260 caracteres quando usando strings. (O uso de bytes como
caminhos está descontinuado no Windows, e esse recurso não está
disponível quando usando bytes.)

Após alterar a opção acima, nenhuma configuração adicional é
necessária.

Alterado na versão 3.6: Suporte para caminhos longos foi ativado no
Python.


3.1.4. Instalando sem UI
------------------------

Todas as opções disponíveis na IU do instalador também podem ser
especificadas a partir da linha de comando, permitindo que
instaladores por script repliquem uma instalação em várias máquinas
sem interação do usuário. Essas opções também podem ser definidas sem
suprimir a IU para alterar alguns dos padrões.

Para esconder completamente a IU do instalador e instalar o Python
silenciosamente, passe a opção "/quiet". Para pular a interação de
usuário mas ainda exibir o progresso e os erros, passe a opção
"/passive". A opção "/uninstall" pode ser passada para imediatamente
começar a remover o Python - nenhuma confirmação será exibida.

Todas as outras opções são passadas como "nome=valor", onde o valor é
usualmente "0" para desabilitar o recurso, "1" para ativar o recurso,
ou um caminho. A lista completa de opções disponíveis é mostrada
abaixo.

+-----------------------------+----------------------------------------+----------------------------+
| Name (nome)                 | Description (descrição)                | Default (padrão)           |
|=============================|========================================|============================|
| InstallAllUsers (Instalar   | Execute uma instalação em todo o       | 0                          |
| para Todos usuários)        | sistema.                               |                            |
+-----------------------------+----------------------------------------+----------------------------+
| TargetDir (Diretório Alvo)  | O diretório de instalação              | Selecionado com base em    |
|                             |                                        | "Instalar para Todos os    |
|                             |                                        | Usuários"                  |
+-----------------------------+----------------------------------------+----------------------------+
| DefaultAllUsersTargetDir    | O diretório de instalação padrão para  | "%ProgramFiles%\Python     |
| (Diretório de Destino       | instalações de todos os usuários       | X.Y" or "%ProgramFiles(x8  |
| Padrão para Todos os        |                                        | 6)%\Python X.Y"            |
| usuários)                   |                                        |                            |
+-----------------------------+----------------------------------------+----------------------------+
| DefaultJustForMeTargetDir   | O diretório de instalação padrão para  | "%LocalAppData%\Programs\  |
| (Diretório Alvo Padrão      | instalações just-for-me                | PythonXY" ou "%LocalAppDa  |
| Apenas Para Mim)            |                                        | ta%\Programs\PythonXY-32"  |
+-----------------------------+----------------------------------------+----------------------------+
| DefaultCustomTargetDir      | Diretório de instalação personalizado  | (vazio)                    |
| (Diretório de destino       | padrão exibido na interface do usuário |                            |
| personalizado padrão)       |                                        |                            |
+-----------------------------+----------------------------------------+----------------------------+
| AssociateFiles (Arquivos    | Criar associações de arquivos se o     | 1                          |
| Associados)                 | launcher também estiver instalado.     |                            |
+-----------------------------+----------------------------------------+----------------------------+
| CompileAll (Compilar Tudo)  | Compile todos os arquivos ".py" para   | 0                          |
|                             | ".pyc".                                |                            |
+-----------------------------+----------------------------------------+----------------------------+
| PrependPath (path a ser     | Adicione o diretório de instalação e o | 0                          |
| percorrido)                 | de Scripts para "PATH" e ".PY" para    |                            |
|                             | "PATHEXT"                              |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Shortcuts (atalhos)         | Crie atalhos para o intérprete,        | 1                          |
|                             | documentação e IDLE se instalado.      |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_doc                 | Install Python manual (Instalação      | 1                          |
|                             | Manual do Python)                      |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_debug (Incluir o    | Instalar binários de Depuração         | 0                          |
| Modo de Depuração)          |                                        |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_dev                 | Instalar cabeçalhos e bibliotecas de   | 1                          |
|                             | desenvolvedores                        |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_exe                 | Instalar "python.exe" e arquivos       | 1                          |
|                             | relacionados                           |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_launcher            | Instalar Inicializador Python para     | 1                          |
|                             | Windows.                               |                            |
+-----------------------------+----------------------------------------+----------------------------+
| InstallLauncherAllUsers     | Instalar para Inicializador Python     | 1                          |
|                             | para Windows todos os usuários.        |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_lib                 | Instalar biblioteca padrão e módulos   | 1                          |
|                             | de extensão                            |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_pip                 | Instale o pacote pip e setuptools      | 1                          |
+-----------------------------+----------------------------------------+----------------------------+
| Include_symbols             | Instalar símbolos de depuração         | 0                          |
|                             | (***.pdb)                              |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_tcltk               | Instale o suporte Tcl/Tk e o IDLE      | 1                          |
+-----------------------------+----------------------------------------+----------------------------+
| Include_test                | Instalar o conjunto de testes da       | 1                          |
|                             | biblioteca padrão                      |                            |
+-----------------------------+----------------------------------------+----------------------------+
| Include_tools               | Instalar scripts com utilitários       | 1                          |
+-----------------------------+----------------------------------------+----------------------------+
| LauncherOnly                | Instala apenas o launcher. Isso        | 0                          |
|                             | substituirá a maioria das outras       |                            |
|                             | opções.                                |                            |
+-----------------------------+----------------------------------------+----------------------------+
| SimpleInstall               | Desativar a maioria das UIs de         | 0                          |
|                             | instalação                             |                            |
+-----------------------------+----------------------------------------+----------------------------+
| SimpleInstallDescription    | Uma mensagem personalizada para exibir | (vazio)                    |
|                             | quando a IU de instalação simplificada |                            |
|                             | é usada.                               |                            |
+-----------------------------+----------------------------------------+----------------------------+

Por exemplo, para instalar silenciosamente uma instalação de Python
padrão e em todo o sistema, você pode usar o seguinte comando (a
partir de um terminal de comando autorizado):

   python-3.6.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

Para permitir que usuários instalem facilmente uma cópia do Python sem
a suíte de testes, você pode fornecer um atalho com o seguinte
comando. Isso irá exibir uma página inicial simplificado e bloquear a
personalização:

   python-3.6.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
       SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."

(Observe que omitir o inicializador também omite associações de
arquivos, e só é recomendado para instalações por usuários quando
também existe uma instalação por todo o sistema que inclui o
inicializador.)

As opções listadas acima também podem ser fornecidas em um arquivo
chamado "unattend.xml" juntamente com o executável. Esse arquivo
especifica uma lista de opções e valores. Quando um valor é fornecido
como um atributo, ele será convertido para um número se possível.
Valores fornecidos como elementos de texto são sempre deixados como
strings. Esse arquivo de exemplo define as mesmas opções que o exemplo
anterior:

   <Options>
       <Option Name="InstallAllUsers" Value="no" />
       <Option Name="Include_launcher" Value="0" />
       <Option Name="Include_test" Value="no" />
       <Option Name="SimpleInstall" Value="yes" />
       <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
   </Options>


3.1.5. Instalando Sem Download
------------------------------

Como alguns recursos do Python não estão inclusos no download inicial
do instalador, selecionar esses recursos pode exigir uma conexão com a
internet. Para evitar isso, todos os possíveis componentes podem ser
baixados sob demanda para criar um *layout* completo que não irá
precisar de uma conexão de internet independentemente dos recursos
selecionados. Note que este download pode ser maior que o necessário,
mas onde um grande número de instalações serão realizadas é bem útil
ter uma cópia em cache local.

Execute the following command from Command Prompt to download all
possible required files.  Remember to substitute "python-3.6.0.exe"
for the actual name of your installer, and to create layouts in their
own directories to avoid collisions between files with the same name.

   python-3.6.0.exe /layout [optional target directory]

Você também pode especificar a opção "/quiet" para esconder o
acompanhamento de progresso.


3.1.6. Modificando uma instalação
---------------------------------

Uma vez que o Python foi instalado, você pode adicionar ou remover
recursos através da ferramenta Programas e Recursos que é parte do
Windows. Selecione o registro do Python e escolha "Uninstall/Change"
para abrir o instalador no modo de manutenção.

"Modify" permite que você adicione ou remova recursos modificando as
caixas de entrada - caixas de entrada não modificadas não irão
instalar ou remover nada. Algumas opções não podem ser modificadas
dessa forma, como o diretório de instalação; para modificá-las, você
precisará remover e então reinstalar o Python completamente.

"Repair" irá verificar todos os arquivos que devem ser instalados
usando as configurações atuais e substituir qualquer um que tiver sido
removido ou modificado.

"Uninstall" irá remover o Python completamente, com a exceção do
Inicializador Python para Windows, que tem seu próprio registro nos
Programas e Recursos.


3.1.7. Outras plataformas
-------------------------

Com o desenvolvimento do Python em andamento, algumas plataformas que
costumavam ser suportadas anteriormente não são mais suportadas
(devido à falta de usuário ou desenvolvedores). Confira a **PEP 11**
para detalhes de todas as plataformas não suportadas.

* Windows CE ainda é suportado.

* O instalador Cygwin também oferece instalação do interpretador do
  Python (cf. Cygwin package source, Maintainer releases)

Veja Python for Windows para informação detalhada sobre as plataformas
com instaladores pré-compilados.

Ver também:

  Python on XP
     "7 Minutes to "Hello World!"" by Richard Dooling, 2006

  Installing on Windows
     in "Dive into Python: Python from novice to pro" by Mark Pilgrim,
     2004, ISBN 1-59059-356-1

  For Windows users
     in "Installing Python" in "A Byte of Python" by Swaroop C H, 2003


3.2. Pacotes Alternativos
=========================

À parte da distribuição padrão CPython, existem pacotes modificados
incluindo funcionalidades adicionais. A seguir está uma lista de
versões populares e seus recursos chave:

ActivePython
   Instalador com compatibilidade multi-plataforma, documentação,
   PyWin32

Anaconda
   Módulos científicos populares (como o numpy, scipy e pandas) e o
   gerenciador de pacotes "conda".

Canopy
   Um "ambiente de análise Python compreensivo" com editores e outras
   ferramentas de desenvolvimento.

WinPython
   Distribuição específica do Windows com pacotes científicos
   pré-construídos e ferramentas para construir pacotes.

Note que esses pacotes podem não incluir as últimas versões do Python
ou outras bibliotecas, e não são mantidos ou suportados pelo time do
núcleo do Python.


3.3. Configurando o Python
==========================

Para executar o Python convenientemente de um prompt de comando, você
pode considerar mudar algumas variáveis de ambiente padrão do Windows.
Ainda que o instalador forneça uma opção para configurar as variáveis
PATH e PATHEXT para você, isso só é confiável para uma instalação
única e global no sistema. Se você usa regularmente múltiplas versões
do Python, considere usar o Inicializador Python para Windows.


3.3.1. Excursus: Configurando variáveis de ambiente
---------------------------------------------------

O Windows permite que variáveis de ambiente sejam configuradas de
forma permanente em ambos os níveis de Usuário e de Sistema, ou
temporariamente em um prompt de comando.

Para definir as variáveis de ambiente temporariamente, abra um Prompt
de Comando e use o comando **set**:

   C:\>set PATH=C:\Program Files\Python 3.6;%PATH%
   C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
   C:\>python

Essas mudanças serão aplicadas em quaisquer comandos posteriores que
forem executados neste console, e serão herdadas por quaisquer
aplicações iniciadas pelo console.

Incluir o nome da variável com sinais de porcentagem irá expandir o
valor existente, permitindo que você adicione seu novo valor ao início
ou final. Modificar o "PATH" adicionando o diretório contendo
**python.exe** ao início é o modo mais comum de garantir que a versão
correta do Python seja iniciada.

Para modificar permanentemente as variáveis de ambiente padrão, clique
em Iniciar e procure por 'Editar as variáveis de ambiente do sistema`,
ou abra as propriedades do Sistema, Configurações avançadas do sistema
e clique no botão Variáveis de Ambiente. Neste diálogo, você pode
adicionar ou modificar as variáveis de Usuário ou Sistema. Para mudar
as variáveis do Sistema, você precisa de acesso não-restrito à sua
máquina (isto é, direitos de Administrador).

Nota:

  O Windows irá concatenar as variáveis de Usuário *após* as variáveis
  de Sistema, o que pode causar resultados inesperados quando
  modificando o "PATH".A variável "PYTHONPATH" é usada por todas as
  versões do Python 2 e Python 3, então você não deve configurar
  permanentemente esta variável a menos que ela apenas inclua código
  que seja compatível com todas as suas versões instaladas do Python.

Ver também:

  https://support.microsoft.com/kb/100843
     Variáveis de ambiente no Windows NT

  https://technet.microsoft.com/en-us/library/cc754250.aspx
     O comando SET, para modificar temporariamente as variáveis de
     ambiente

  https://technet.microsoft.com/en-us/library/cc755104.aspx
     O comando SETX, para modificar permanentemente as variáveis de
     ambiente

  https://support.microsoft.com/kb/310519
     Como Gerenciar Variáveis de Ambiente no Windows XP

  https://www.chem.gla.ac.uk/~louis/software/faq/q1.html
     Configurando variáveis de ambiente, Lous J. Farrugia


3.3.2. Encontrando o executável do Python
-----------------------------------------

Alterado na versão 3.5.

Além de usar o registro do menu Iniciar criado automaticamente para o
interpretador do Python, você pode querer iniciar o Python no prompt
de comando. O instalador possui uma opção para configurar isso pra
você.

Na primeira página do instalador, uma opção chamada "Add Python to
PATH" pode ser selecionada para que o instalador adicione o local de
instalação na sua variável "PATH". O local da pasta de "Scripts\"
também é adicionado. Isso permite que você digite **python** para
executar o interpretador, e **pip** para o instalador de pacotes. Além
disso, você pode também executar seus scripts com as opções de linha
de comando, veja a documentação Linha de comando.

Se você não habilitar essa opção no momento de instalação, você sempre
pode re-executar o instalador, selecionar Modify, e habilitá-la.
Alternativamente, você pode modificar manualmente a variável "PATH"
usando os direcionamentos em Excursus: Configurando variáveis de
ambiente. Você precisa definir sua variável de ambiente "PATH" para
incluir o diretório da sua instalação Python, delimitado por um ponto
e vírgula de outras entradas. Uma variável exemplo pode parecer com
isso (assumindo que as duas primeiras entradas já existem):

   C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.6


3.4. Inicializador Python para Windows
======================================

Novo na versão 3.3.

O inicializador Python para Windows é um utilitário que auxilia na
localização e execução de diferentes versões do Python. Ele permite
que scripts (ou a linha de comando) indiquem uma preferência por uma
versão do Python específica, e irá localizar e executar essa versão.

Ao contrário da variável "PATH", o inicializador irá corretamente
selecionar a versão mais apropriada do Python. Ele irá preferir
instalações por usuário ao invés de instalações globais no sistema, e
ordenará por versão da linguagem ao invés de usar a versão instalada
mais recentemente.


3.4.1. Começando
----------------


3.4.1.1. Pela linha de comando
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Alterado na versão 3.6.

Instalações globais no sistema do Python 3.3 ou posterior irão colocar
o inicializador no seu "PATH". O inicializador é compatível com todas
as versões disponíveis do Python, então não importa qual versão está
instalada. Para verificar se o inicializador está disponível, execute
o seguinte comando no Prompt de Comando:

   py

Você deve perceber que a última versão do Python que você tem é
iniciada - ela pode ser fechada normalmente, e qualquer argumento da
linha de comando adicional especificado será enviado diretamente para
o Python.

Se você tem múltiplas versões do Python instaladas (por exemplo, 2.7 e
3.6) você deve ter notado que o Python 3.6 foi iniciado - para iniciar
o Python 2.7, use o comando:

   py -2.7

Se você quer a versão mais recente do Python 2.x que você tem
instalada, tente o comando:

   py -2

Você deve perceber que a versão mais recente do Python 2.x iniciou.

Se você ver o seguinte erro, você não tem o inicializador instalado:

   'py' is not recognized as an internal or external command,
   operable program or batch file.

Instalações do Python por usuário não permitem adicionar o
inicializador ao "PATH" a não ser que a opção seja selecionada na
instalação.


3.4.1.2. Ambientes virtuais
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Novo na versão 3.5.

Se o inicializador é executado sem versão explícita do Python
especificada, e um ambiente virtual (criado com o módulo da biblioteca
padrão "venv" ou da ferramenta externa "virtualenv") está ativo, o
inicializador irá executar o interpretador do ambiente virtual ao
invés do global. Para executar o interpretador global, ou desative o
ambiente virtual, ou explicitamente especifique a versão global do
Python.


3.4.1.3. Por um script
~~~~~~~~~~~~~~~~~~~~~~

Vamos criar um script teste de Python - crie um arquivo chamado
"hello.py" com os seguintes conteúdos:

   #! python
   import sys
   sys.stdout.write("hello from Python %s\n" % (sys.version,))

A partir do diretório onde hello.py está, execute o comando:

   py hello.py

Você deve notar que o número da versão da sua instalação mais recente
do Python 2.x é exibido. Agora tente mudar a primeira linha para ser:

   #! python3

Re-executar o comando agora deve exibir informações da última versão
do Python 3.x. Como nos exemplos da linha de comando acima, você pode
especificar um qualificador de versão mais explícito. Assumindo que
você tem o Python 2.6 instalado, tente mudar a primeira linha para "#!
python2.6" e você deve ver as informações da versão 2.6 sendo
exibidas.

Note que diferentemente do uso interativo, um simples "python" irá
usar a última versão do Python 2.x que você tem instalada. Isso é para
retrocompatibilidade e para compatibilidade com Unix, onde o comando
"python" tipicamente se refere ao Python 2.


3.4.1.4. Por associação de arquivos
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

O inicializador deve ter sido associado com arquivos Python (isto é,
arquivos ".py", ".pyw", ".pyc") quando foi instalado. Isso significa
que quando você clica duas vezes em um desses arquivos a partir do
Explorador de Arquivos do Windows o inicializador será usado, e assim
você pode usar as mesmas facilidades descritas acima para que o script
especifique qual versão deve ser usada.

O benefício chave disso é que um único inicializador pode suportar
múltiplas versões do Python ao mesmo tempo dependendo dos conteúdos da
primeira linha.


3.4.2. Linhas Shebang
---------------------

Se a primeira linha de um arquivo de script começa com "#!", ela é
conhecida como linha "shebang". Linux e outros tipos de sistemas
operacionais Unix têm suporte nativo para essas linhas e elas são
comumente usadas nesses sistemas para indicar como um script deve ser
executado. Esse inicializador permite que as mesmas facilidades sejam
usadas com scripts Python no Windows e os exemplos acima demonstram
seu uso.

Para permitir que linhas shebang em scripts Python sejam portáveis
entre Unix e Windows, este inicializador suporta um número de comandos
'virtuais' para especificar qual interpretador deve ser usado. Os
comandos virtuais suportados são:

* "/usr/bin/env python"

* "/usr/bin/python"

* "/usr/local/bin/python"

* "python"

Por exemplo, se a primeira linha do seu script começa com

   #! /usr/bin/python

O Python padrão será localizado e utilizado. Como muitos scripts
Python escritos para funcionar no Unix já terão essa linha, você deve
perceber que esses scripts podem ser usados pelo inicializador sem
modificação. Se você está escrevendo um novo script no Windows que
você espera que seja útil no Unix, você deve usar uma dessas linhas
shebang começando com "/usr".

Any of the above virtual commands can be suffixed with an explicit
version (either just the major version, or the major and minor
version) - for example "/usr/bin/python2.7" - which will cause that
specific version to be located and used.

A forma de linha shebang "/usr/bin/env" tem uma propriedade especial
adicional. Antes de procurar pela versão dos interpretadores de Python
instalados, essa forma irá pesquisar no "PATH" por um executável
Python. Isso corresponde ao comportamento do programa "env" do Unix,
que realiza a pesquisa no "PATH".


3.4.3. Argumentos em linhas shebang
-----------------------------------

As linhas shebang também podem especificar opções adicionais a serem
passadas ao interpretador Python. Por exemplo, se você tem uma linha
shebang:

   #! /usr/bin/python -v

O Python será iniciado com a opção "-v"


3.4.4. Personalização
---------------------


3.4.4.1. Personalização via arquivos INI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Dois arquivos .ini serão pesquisados pelo inicializador - "py.ini" no
diretório "application data" do usuário atual (isto é, o diretório
retornado ao chamar a função do Windows "SHGetFolderPath" com
"CSIDL_LOCAL_APPDATA") e "py.ini" no mesmo diretório que o
inicializador. Os mesmos arquivos .ini são usados para ambas a versão
'console' do inicializador (isto é, py.exe) e a versão 'windows' (isto
é, pyw.exe).

Personalização especificada no "diretório da aplicação" terão
precedência sobre àquela especificada junto do executável, portanto um
usuário, que pode não ter acesso de escrita ao arquivo .ini junto do
inicializador, pode sobrescrever comandos naquele arquivo .ini global.


3.4.4.2. Personalizando versões padrão do Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In some cases, a version qualifier can be included in a command to
dictate which version of Python will be used by the command. A version
qualifier starts with a major version number and can optionally be
followed by a period ('.') and a minor version specifier. If the minor
qualifier is specified, it may optionally be followed by "-32" to
indicate the 32-bit implementation of that version be used.

Por exemplo, uma linha shebang "#!python" não tem qualificador de
versão, enquanto "#!python3" tem um qualificador de versão que
especifica apenas uma versão maior.

If no version qualifiers are found in a command, the environment
variable "PY_PYTHON" can be set to specify the default version
qualifier - the default value is "2". Note this value could specify
just a major version (e.g. "2") or a major.minor qualifier (e.g.
"2.6"), or even major.minor-32.

Se nenhum qualificador de versão menor é encontrado, a variável de
ambiente "PY_PYTHON{major}" (onde "{major}" é o qualificador da versão
maior atual, como determinado acima) pode ser definida para
especificar a versão completa. Se nenhuma opção é encontrada, o
inicializador irá enumerar as versões do Python instaladas e usar a
última versão menor encontrada como versão maior, o que é
provavelmente, ainda que não garantido, a versão instalada mais
recentemente naquela família.

On 64-bit Windows with both 32-bit and 64-bit implementations of the
same (major.minor) Python version installed, the 64-bit version will
always be preferred. This will be true for both 32-bit and 64-bit
implementations of the launcher - a 32-bit launcher will prefer to
execute a 64-bit Python installation of the specified version if
available. This is so the behavior of the launcher can be predicted
knowing only what versions are installed on the PC and without regard
to the order in which they were installed (i.e., without knowing
whether a 32 or 64-bit version of Python and corresponding launcher
was installed last). As noted above, an optional "-32" suffix can be
used on a version specifier to change this behaviour.

Exemplos:

* Se nenhuma opção relevante for definida, os comandos "python" e
  "python2" irão usar a última versão instalada do Python 2.x e o
  comando "python3" irá usar o último Python 3.x instalado.

* Os comandos "python3.1" e "python2.7" não irão consultar nenhuma
  opção já que as versões estão completamente especificadas.

* Se "PY_PYTHON=3", os comandos "python" e "python3" irão ambos usar a
  última versão do Python 3 instalada.

* Se "PY_PYTHON=3.1-32",  o comando "python" irá usar a implementação
  32-bit do 3.1 enquanto o comando "python3" irá usar o último Python
  instalado (PY_PYTHON não foi considerado porque uma versão maior foi
  especificada).

* Se "PY_PYTHON=3" e "PY_PYTHON3=3.1", os comandos "python" e
  "python3" irão ambos usar especificamente 3.1.

Em adição às variáveis de ambiente, as mesmas configurações podem ser
feitas no arquivo .INI usado pelo inicializador. A seção nos arquivos
INI é chamada "[defaults]" e o nome da chave será o mesmo que as
variáveis de ambiente sem o prefixo "PY_" (e observe que os nomes das
chaves no arquivo INI não diferem maiúsculas e minúsculas). Os
conteúdos de uma variável de ambiente irão sobrescrever coisas
especificadas em um arquivo INI.

Por exemplo:

* Configurar "PY_PYTHON=3.1" é o equivalente ao arquivo INI contendo:

   [defaults]
   python=3.1

* Configurar "PY_PYTHON=3" e "PY_PYTHON3=3.1" é o equivalente ao
  arquivo INI contendo:

   [defaults]
   python=3
   python3=3.1


3.4.5. Diagnósticos
-------------------

Se uma variável de ambiente "PYLAUNCH_DEBUG" é configurada (para
qualquer valor), o inicializador irá exibir a informação de
diagnóstico do stderr (isto é, no console). Enquanto essa informação
consegue ser simultaneamente verbosa *e* concisa, ela deve permitir
que você veja quais versões do Python foram localizadas, porquê uma
versão particular foi escolhida e qual linha de comando exatamente foi
usada para executar o Python alvo.


3.5. Encontrando módulos
========================

O Python geralmente armazena sua biblioteca (e assim sua pasta de
site-packages) no diretório de instalação. Então, se você instalou o
Python em "C:\Python\", a biblioteca padrão irá residir em
"C:\Python\Lib\" e módulos de terceiros serão armazenados em
"C:\Python\Lib\site-packages\".

To completely override "sys.path", create a "._pth" file with the same
name as the DLL ("python36._pth") or the executable ("python._pth")
and specify one line for each path to add to "sys.path". The file
based on the DLL name overrides the one based on the executable, which
allows paths to be restricted for any program loading the runtime if
desired.

Quando o arquivo existe, todos os registros e variáveis de ambiente
são ignorados, o modo isolado é ativado, e "site" não é importado a
menos que uma linha do arquivo especifique "import site". Caminhos em
branco e linhas começando com "#" são ignorados. Cada caminho pode ser
absoluto ou relativo ao local do arquivo. Instruções de importação que
não seja ao "site" não são permitidas, e código arbitrário não pode
ser especificado.

Note that ".pth" files (without leading underscore) will be processed
normally by the "site" module.

Quando nenhum arquivo "._pth" é encontrado, assim é como "sys.path" é
populado no Windows:

* Uma entrada em branco é adicionada ao início, que corresponde ao
  diretório atual.

* Se a variável de ambiente "PYTHONPATH" existe, como descrito em
  Variáveis de ambiente, suas entradas são adicionadas em seguida.
  Note que no Windows, caminhos nessa variável devem ser separados por
  ponto e vírgula, para distinguir eles dos dois pontos usados nos
  identificadores de drivers ("C:\" etc.).

* "Caminhos da aplicação" adicionais podem ser adicionados ao registro
  como subchaves de "\SOFTWARE\Python\PythonCore{version}\PythonPath"
  sob ambas "HKEY_CURRENT_USER" e "HKEY_LOCAL_MACHINE". Subchaves que
  possuem string de caminhos delimitados por ponto e vírgula como seu
  valor padrão farão com que cada caminho seja adicionado ao
  "sys.path". (Note que todos os instaladores conhecidos usam apenas
  HKLM, portanto HKCU está tipicamente vazio.)

* Se a variável de ambiente "PYTHONHOME" está definida, ela é assumida
  como "Python Home". Caso contrário, o caminho do principal
  executável do Python é usado para localizar um "arquivo de
  referência" (ou "Lib\os.py" ou "pythonXY.zip") para deduzir o
  "Python Home". Se um Python Home é encontrado, os subdiretórios
  relevantes adicionados ao "sys.path" ("Lib", "plat-win", etc) são
  baseados naquela pasta. Se não, o caminho núcleo do Python é
  construído a partir do PythonPath armazenado no registro.

* Se o Python Home não puder ser localizado, nenhum "PYTHONPATH" está
  especificado no ambiente, e nenhuma entrada de registro pôde ser
  encontrada, um caminho padrão com entradas relativas é usado (por
  exemplo, ".\Lib;.\plat-win", etc).

Se um arquivo "pyvenv.cfg" for encontrado juntamente com o principal
executável ou no diretório um nível acima do executável, as seguintes
variações se aplicam:

* Se "home" é um caminho absoluto e "PYTHONHOME" não está definido, o
  caminho é usado ao invés do caminho ao principal executável quando
  deduzindo a localização do Home.

O resultado final de tudo isso é:

* Quando executando "python.exe", ou qualquer outro .exe no diretório
  principal do Python (ou uma versão instalada, ou diretamente do
  diretório PCbuild), o caminho núcleo é deduzido, e os caminhos
  núcleo no registro são ignorados. Outros "caminhos da aplicação" no
  registro são sempre lidos.

* Quando Python é hospedado em outro .exe (diretório diferente,
  embutido via COM, etc), o "Python Home" não será deduzido, então o
  caminho núcleo do registro é usado. Outros "caminhos da aplicação"
  no registro sempre são lidos.

* Se o Python não puder encontrar seu Home e não existem valores no
  registro (.exe imutáveis, algumas configurações de instalação bem
  estranhas) você recebe um caminho com alguns caminhos padrão, porém
  relativos.

Para aqueles que querem empacotar o Python em suas aplicações ou
distribuições, o seguinte conselho irá prevenir conflitos com outras
instalações:

* Inclua um arquivo "._pth" juntamente do executável contendo os
  diretórios a serem incluídos. Isso irá ignorar caminhos listados no
  registro e variáveis de ambiente, e também ignorar "sites" a não ser
  que "import site" seja listado.

* If you are loading "python3.dll" or "python36.dll" in your own
  executable, explicitly call "Py_SetPath()" or (at least)
  "Py_SetProgramName()" before "Py_Initialize()".

* Limpe e/ou sobrescreva "PYTHONPATH" e defina "PYTHONHOME" antes de
  iniciar o "python.exe" a partir da sua aplicação.

* Se você não puder usar as sugestões anteriores (por exemplo, você é
  uma distribuição que permite que as pessoas executem o arquivo
  "python.exe" diretamente), certifique-se de que o arquivo de
  referência ("Lib\os.py") existe no seu diretório de instalação.
  (Note que ele não será detectado dentro de um arquivo ZIP, mas um
  arquivo ZIP corretamente nomeado será detectado ao invés disso.)

Isso irá garantir que seus arquivos em uma instalação global no
sistema não terão precedência sobre uma cópia da biblioteca padrão
empacotada com a sua aplicação. Caso contrário, seus usuários podem
experienciar problemas usando sua aplicação. Note que a primeira
sugestão é a melhor, pois as outras podem ainda estar suscetíveis a
caminhos não-padrão no registro e no site-packages do usuário.

   Alterado na versão 3.6:

   * Adiciona suporte a arquivos "._pth" e remove a opção "applocal"
     do "pyvenv.cfg".

   * Adiciona "pythonXX.zip" como uma possível referência quando
     diretamente adjacente ao executável.

   Obsoleto desde a versão 3.6:

   Módulos especificados no registro sob "Modules" (não "PythonPath")
   podem ser importados por
   "importlib.machinery.WindowsRegistryFinder". Este localizador está
   ativo no Windows no 3.6.0 e anteriores, mas pode precisar ser
   explicitamente adicionado ao "sys.meta_path" no futuro.


3.6. Módulos adicionais
=======================

Mesmo que o Python tenha como objetivo ser portável através de todas
as plataformas, existem recursos que são únicos para o Windows. Alguns
módulos, em ambas as bibliotecas padrão e externa, e trechos de código
existem para usar esses recursos.

Os módulos padrão específicos para Windows estão documentados em
Serviços Específicos do MS Windows.


3.6.1. PyWin32
--------------

O módulo PyWin32 de Mark Hammond é uma coleção de módulos para suporte
avançado específico para Windows. Isso inclui utilitários para:

* Component Object Model (COM)

* Chamadas à API Win32

* Registro

* Log de Eventos

* Microsoft Foundation Classes (MFC) interface de usuário

PythonWin é uma aplicação MFC de exemplo enviada com o PyWin32. É uma
IDE embutível com um depurador embutido.

Ver também:

  Win32 How Do I...?
     por Tim Golden

  Python and COM
     by David and Paul Boddie


3.6.2. cx_Freeze
----------------

cx_Freeze is a "distutils" extension (see Estendendo Distutils) which
wraps Python scripts into executable Windows programs ("***.exe"
files).  When you have done this, you can distribute your application
without requiring your users to install Python.


3.6.3. WConio
-------------

Dado que a camada de manipulação de terminal avançada do Python,
"curses", é restrita a sistemas tipo Unix, existe uma biblioteca
exclusiva para o Windows: Windows Console I/O para Python.

WConio é um encapsulador para o "CONIO.H" do Turbo-C usado para criar
texto sob interfaces de usuário.


3.7. Compilando Python no Windows
=================================

Se você quer compilar o CPython por conta própria, a primeira coisa
que você precisa ter é a fonte. Você pode fazer o download tanto da
fonte da última versão quanto pegar um novo checkout.

A árvore de fontes contém uma solução de construção e arquivos de
projeto para o Microsoft Visual Studio 2015, que é o compilador usado
para construir as versões do Python oficiais. Esses arquivos estão no
diretório "PCbuild".

Configra o "PCbuild/readme.txt" para informações gerais sobre o
processo de construção.

Para módulos de extensão, consulte Construindo Extensões C e C++ no
Windows.

Ver também:

  Python + Windows + distutils + SWIG + gcc MinGW
     ou "Creating Python extensions in C/C++ with SWIG and compiling
     them with MinGW gcc under Windows" ou "Installing Python
     extension with distutils and without Microsoft Visual C++" por
     Sébastien Sauvage, 2003

  MingW -- Python extensions
     by Trent Apted et al, 2007


3.8. Embedded Distribution
==========================

Novo na versão 3.5.

A distribuição embutida é um arquivo ZIP contendo um ambiente Python
mínimo. Ela foi criada para atuar como parte de outra aplicação, ao
invés de ser diretamente acessada por usuários finais.

When extracted, the embedded distribution is (almost) fully isolated
from the user's system, including environment variables, system
registry settings, and installed packages. The standard library is
included as pre-compiled and optimized ".pyc" files in a ZIP, and
"python3.dll", "python36.dll", "python.exe" and "pythonw.exe" are all
provided. Tcl/tk (including all dependants, such as Idle), pip and the
Python documentation are not included.

Nota:

  A distribuição embutida não inclui o Microsoft C Runtime e é de
  responsabilidade do instalador da aplicação providenciar isso. O
  aplicativo de tempo de execução pode já ter sido instalado no
  sistema de um usuário previamente ou automaticamente via Windows
  Update, e pode ser detectado procurando por "ucrtbase.dll" no
  diretório do sistema.

Pacotes de terceiros devem ser instalados pelo instalador da aplicação
juntamente com a distribuição embutida. Usar o pip para gerenciar as
dependências como em uma instalação regular do Python não é suportado
nessa distribuição, apesar de que com algum cuidado pode ser possível
incluir e usar o pip para atualizações automáticas. Em geral, pacotes
de terceiros devem ser tratados como parte da aplicação ("vendoring")
para que o desenvolvedor consiga garantir compatibilidade com versões
mais recentes antes de fornecer atualizações para os usuários.

Os dois casos de uso recomendados para essa distribuição são descritos
abaixo.


3.8.1. Aplicação Python
-----------------------

Uma aplicação escrita em Python não requer necessariamente que os
usuários estejam cientes deste fato. A distribuição embutida pode ser
usada neste caso para incluir uma versão privada do pacote de
instalação do Python. Dependendo de quão transparente deve ser (ou
pelo contrário, quão profissional deve parecer), existem duas opções.

Usando um executável especializado como inicializador requer um pouco
de código, mas fornece a experiência mais transparente para os
usuários. Com um inicializador customizado, não existem indicações
óbvias que o programa está rodando em Python: ícones podem ser
personalizados, informações da empresa e versão podem ser
especificadas, e associações de arquivo se comportam de forma
apropriada. Na maioria dos casos, um inicializador personalizado deve
simplesmente ser capaz de chamar "Py_Main" com uma linha de comando
predefinida (hard-coded).

A abordagem mais simples é fornecer um arquivo batch ou um atalho
gerado que chama diretamente o "python.exe" ou "pythonw.exe" com os
argumentos de linha de comando necessários. Neste caso, a aplicação
irá aparecer como Python e não seu nome real, e os usuários podem ter
problemas em distinguir ela de outros processos ou associações de
arquivo em Python.

Com a abordagem anterior, pacotes devem ser instalados como diretórios
juntamente do executável do Python para garantir que estarão
disponíveis no caminho do ambiente. Com o instalador especializado,
pacotes podem ser armazenados em outras localidades já que há uma
oportunidade de especificar o caminho de busca antes de executar a
aplicação.


3.8.2. Incorporando Python
--------------------------

Aplicações escritas em código nativo frequentemente precisam de alguma
forma de linguagem de script, e a distribuição embutida do Python pode
ser usada para esse propósito. Em geral, a maior parte da aplicação é
em código nativo, e uma parte irá ou invocar "python.exe" ou usar
diretamente "python3.dll". Para ambos os casos, extrair a distribuição
embutida em um subdiretório da instalação da aplicação é suficiente
para providenciar um interpretador Python carregável.

Para uso da aplicação, pacotes podem ser instalados em qualquer local
já que há uma oportunidade de especificar caminhos de busca antes de
inicializar o interpretador. De outra forma, não existem diferenças
fundamentais entre usar a distribuição embutida ou a instalação
regular.


3.9. Outros recursos
====================

Ver também:

  Python Programming On Win32
     "Help for Windows Programmers" by Mark Hammond and Andy Robinson,
     O'Reilly Media, 2000, ISBN 1-56592-621-8

  A Python for Windows Tutorial
     by Amanda Birmingham, 2004

  **PEP 397** - Launcher do Python para Windows
     A proposta do launcher do Python a ser incluído na distribuição
     Python.
