5. Usando Python em macOS
*************************

Este documento tem o objetivo de fornecer uma visão geral dos
comportamentos específicos do macOS que você deve conhecer para
começar a usar o Python em computadores Mac. O Python em um Mac com
macOS é muito semelhante ao Python em outras plataformas derivadas do
Unix, mas há algumas diferenças na instalação e alguns recursos.

Há várias maneiras de obter e instalar o Python para macOS. Versões
pré-construídas das versões mais recentes do Python estão disponíveis
em vários distribuidores. Grande parte deste documento descreve o uso
dos Pythons fornecidos pela equipe de lançamento do CPython,
disponíveis para download no site python.org. Consulte Distribuições
alternativas para conhecer outras opções.


5.1. Usando Python para macOS do "python.org"
=============================================


5.1.1. Etapas de instalação
---------------------------

Para as versões atuais de Python (exceto as com status "security"), a
equipe de lançamento produz um pacote de instalação **Python para
macOS** em cada novo lançamento. Uma lista dos instaladores
disponíveis está disponível aqui. Recomendamos usar a versão suportada
mais recente de Python sempre que possível. Os instaladores atuais
fornecem uma versão de Python como binário universal 2 que é executado
nativamente em todos os Macs (Apple Silicon e Intel) compatíveis com
uma ampla gama de versões do macOS, atualmente do **macOS 10.15
Catalina** em diante.

O arquivo baixado é um arquivo padrão do instalador de pacotes do
macOS (".pkg"). As informações de integridade do arquivo (soma de
verificação, tamanho, assinatura de Sigstore, etc.) de cada arquivo
estão inclusas na página de download dos lançamentos. Os pacotes de
instalação e seus conteúdos são assinados e autenticados com
certificados Apple Developer ID "Python Software Foundation" para
atender aos requisitos do macOS Gatekeeper.

Para uma instalação padrão, clique duas vezes no arquivo instalador de
pacotes baixado. Isso deverá abrir o aplicativo padrão de instalação
do macOS e exibir o primeiro de vários passos de instalação.

[imagem]

Ao clicar no botão **Continuar**, é exibido o **Read Me** desse
instalador. Além de outras informações importantes, o **Read Me**
documenta qual versão de Python será instalada e em quais versões do
macOS ele é compatível. Talvez você precise rolar a tela para ler o
arquivo inteiro. Por padrão, esse **Read Me** também será instalado em
"/Applications/Python 3.14/" e estará disponível para leitura a
qualquer momento.

[imagem]

Ao clicar em **Continuar**, o instalador exibe a licença do Python e
de outros softwares incluídos. Você precisará **Concordar** com os
termos da licença antes de prosseguir para a próxima etapa. Esse
arquivo de licença também será instalado e estará disponível para
leitura a qualquer momento.

[imagem]

Após aceitar os termos da licença, a próxima etapa será a tela **Tipo
de instalação**. Para a maioria dos usos, o conjunto padrão de
operações de instalação é adequado.

[imagem]

Ao pressionar o botão **Personalizar**, você pode optar por omitir ou
selecionar determinados componentes de pacote do instalador. Clique em
cada nome de pacote para ver uma descrição do que ele instala. Para
também instalar o suporte para o recurso opcional de threads livres,
consulte Instalando binários com threads livres.

[imagem]

Em ambos os casos, clicar em **Instalar** iniciará o processo de
instalação solicitando a permissão para instalar um novo software. É
necessário um nome de usuário do macOS com privilégio de
"Administrador", pois o Python instalado estará disponível para todos
os usuários do Mac.

Quando a instalação for concluída, a janela **Resumo** será exibida.

[imagem]

Clique duas vezes no ícone ou arquivo **Install Certificates.command**
na janela "/Applications/Python 3.14/" para concluir a instalação.

[imagem]

Isso abrirá uma janela temporária do console **Terminal** que usará o
novo Python para baixar e instalar certificados raiz SSL para seu uso.

[imagem]

Se "Successfully installed certifi" e "update complete" aparecerem na
janela do terminal, a instalação estará concluída. Feche essa janela
do terminal e a janela do instalador.

Uma instalação do padrão incluirá:

* Uma pasta "Python 3.14" em sua pasta "Applications". Aqui você
  encontra o **IDLE**, o ambiente de desenvolvimento que é parte das
  distribuições oficiais do Python; e o **Python Launcher**, que
  executa scripts Python quando são clicados duas vezes dentro do
  Finder .

* Uma framework "/Library/Frameworks/Python.framework", que inclui o
  executável Python e suas bibliotecas. O instalador adiciona esse
  local ao seu *path* do console. Para desinstalar o Python, você pode
  remover esses três itens. É um link simbólico para o executável
  Python armazenado na pasta "/usr/local/bin/".

Nota:

  As versões recentes do macOS incluem um comando **python3** em
  "/usr/bin/python3" que aponta para uma versão geralmente mais antiga
  e incompleta de Python fornecida por e para uso pelas ferramentas de
  desenvolvimento da Apple, **Xcode** ou o **Command Line Tools for
  Xcode**. Você nunca deve modificar ou tentar excluir essa instalação
  por ser controlada pela Apple e é usada por softwares da Apple ou de
  terceiros. Se você optar por instalar uma versão mais recente do
  Python a partir de "python.org", você terá duas instalações
  diferentes, mas funcionais, de Python no computador que podem
  coexistir. As opções do instalador padrão devem garantir que o
  comando **python3** seja usado em vez do **python3** do sistema.


5.1.2. Como executar um script Python
-------------------------------------

Há duas maneiras de invocar o interpretador Python. Se você estiver
familiarizado com o uso de um console Unix em terminal, você pode
invocar "python3.14" ou "python3", opcionalmente seguido por uma ou
mais opções da linha de comando (descritas em Linha de comando e
ambiente). O tutorial de Python também tem uma seção útil sobre o uso
interativo do Python a partir de um console.

Você também pode invocar o interpretador por um ambiente de
desenvolvimento integrado (IDE). O IDLE --- editor e console Python é
um editor e ambiente de desenvolvimento básico incluído com a
distribuição padrão de Python. **IDLE** inclui um menu Ajuda que te
permite acessar a documentação de Python. Se você for completamente
iniciante em Python, você pode ler o tutorial de introdução na
documentação.

Há muitos outros editores e IDEs disponíveis. Consulte Editores e IDEs
para mais informações.

Para executar um script Python na janela do terminal, você pode
invocar o interpretador com o nome do arquivo de script:

   "python3.14" "meuscript.py"

Para executar seu script a partir do Finder, você pode:

* Arrastá-lo para o **Python Launcher**.

* Selecione **Python Launcher** como a aplicação padrão para abrir seu
  script (ou qualquer script ".py") na janela de informações Finder
  Info, e clique duas vezes nele. O **Python Launcher** tem várias
  preferências para controlar como o script é iniciado. Você pode
  arrastar opções para alterá-las por uma invocação, ou usar o menu
  "Preferências" para alterar configurações globalmente.

Saiba que executar o script diretamente do Finder pode produzir
resultados diferentes daqueles obtidos em uma janela de terminal, pois
o script não será executado no ambiente normal do console, incluindo
qualquer configuração de variáveis de ambiente nos perfis do console.
E, como em qualquer outro script ou programa, certifique-se do que
está prestes a executar.


5.2. Distribuições alternativas
===============================

Além do instalador padrão do "python.org" para macOS, existem
distribuições de terceiros para macOS que podem incluir
funcionalidades adicionais. Algumas distribuições populares e seus
recursos-chave são:

ActivePython
   Instalador com compatibilidade multiplataforma, documentação

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

Homebrew
   Gerenciador de pacotes para macOS que inclui várias versões do
   Python e muitos pacotes Python de terceiros (incluindo numpy, scipy
   e pandas).

MacPorts
   Outro gerenciador de pacotes para macOS, incluindo várias versões
   de Python e muitos pacotes Python de terceiros. Pode incluir
   versões pré-construídas do Python e muitos pacotes para versões
   mais antigas do macOS.

Note que distribuições podem não incluir versões mais recentes de
Python ou de outras bibliotecas, e não são mantidas ou providas pela
equipe do Python.


5.3. Instalando pacotes adicionais ao python
============================================

Consulte o Guia de Usuário para Empacotamento de Python para mais
informações.


5.4. Programação de GUI
=======================

Existem várias opções para criar aplicações GUI no Mac com Python.

O kit de ferramentas GUI padrão de Python é o módulo "tkinter",
baseado no kit de ferramentas multiplataforma Tk (https://www.tcl.tk).
Uma versão nativa do Tk para macOS está incluída no instalador.

*O PyObjC* é uma ligação em Python para o Objective-C/Cocoa da Apple
framework. Informações sobre o PyObjC estão disponíveis em pyobjc.

Há vários kits de ferramentas GUI alternativas disponíveis para o
macOS, incluindo:

* PySide: Ligações oficiais em Python ao kit de ferramentas Qt GUI .

* PyQt: Ligações alternativas em Python ao Qt.

* Kivy: Um kit de ferramentas GUI multiplataforma que dá suporte a
  plataformas de desktop e dispositivos móveis.

* Toga: Parte do BeeWare Project; dá suporte a aplicativos para
  desktop, dispositivos móveis, Web e console.

* wxPython: Um kit de ferramentas multiplataforma que dá suporte a
  sistemas operacionais desktop.


5.5. Tópicos Avançados
======================


5.5.1. Instalando binários com threads livres
---------------------------------------------

Adicionado na versão 3.13.

O pacote de instalação do Python para macOS em "python.org" pode,
opcionalmente, instalar uma compilação adicional do Python 3.14 que dá
suporte à **PEP 703**, o recurso de threads livres (executado com o
*trava global do interpretador* desativado). Verifique a página de
lançamento em "python.org" para obter informações atualizadas.

O modo com threads livres está funcionando e continua sendo
aprimorado, mas há alguma sobrecarga adicional em cargas de trabalho
de thread única em comparação com a construção regular. Além disso,
pacotes de terceiros, em particular aqueles com um *módulo de
extensão*, podem não estar prontos para uso em uma construção com
threads livres e reativarão a *GIL*. Portanto, o suporte para threads
livres não é instalado por padrão. Ele é fornecido como uma opção de
instalação separada, disponível clicando no botão **Personalizar** na
etapa **Tipo de Instalação** do instalador, conforme descrito acima.

[imagem]

Se a caixa ao lado do nome **Free-Threaded Python** for marcada, um
arquivo "PythonT.framework" também será instalado junto ao arquivo
"Python.framework" em "/Library/Frameworks". Essa configuração permite
que a compilação de Python 3.14 com threads livres coexista no seu
sistema com a compilação de Python 3.14 tradicional (com GIL) com
risco mínimo durante instalação ou testagem. Esse layout de instalação
pode mudar em lançamentos futuros.

Precauções e limitações conhecidas:

* O pacote **Unix command-line tools**, que é selecionado por padrão,
  instalará links em "/usr/local/bin" para "python3.14t", o
  interpretador com threads livres e "python3.14t-config", um
  utilitário de configuração que pode ser útil para criadores de
  pacote. Como "/usr/local/bin" é normalmente incluído em seu "PATH"
  do console, geralmente não é necessário alterar as variáveis de
  ambiente do "PATH" para usar o "python3.14t".

* Neste lançamento, o pacote **Shell profile updater** e o comando
  "Update Shell Profile.command" em "/Applications/Python 3.14/" não
  dão suporte ao pacote com threads livres.

* A construção com threads livres e a compilação tradicional têm
  caminhos de pesquisa separados e diretórios "site-packages"
  separados, portanto, por padrão, se você precisar de um pacote
  disponível em ambas construções, talvez seja necessário instalá-lo
  em ambos. O pacote com threads livres instalará uma instância
  separada do **pip** para uso com o "python3.14t".

  * Para instalar um pacote usando **pip** sem um **venv**:

       python3.14t -m pip install <package_name>

* Ao trabalhar com vários ambientes Python, geralmente é mais seguro e
  mais fácil criar e usar ambientes virtuais. Isso pode tanto evitar
  possíveis conflitos de comandos, quanto evitar a confusão sobre qual
  Python está sendo usado:

     python3.14t -m venv <venv_name>

  e, em seguida, **activate**.

* Para executar uma versão do IDLE com threads livres:

     python3.14t -m idlelib

* Os interpretadores em ambos as construções respondem às mesmas
  variáveis de ambiente PYTHON, o que pode gerar resultados
  inesperados, por exemplo, se você tiver "PYTHONPATH" definido em um
  perfil de console. Se necessário, há opções de linha de comando como
  "-E" para ignorar essas variáveis de ambiente.

* A construção com threads livres é ligada às bibliotecas
  compartilhadas de terceiros, como "OpenSSL" e "Tk", instaladas no
  framework tradicional. Isso significa que ambas as compilações
  também compartilham um conjunto de certificados, como instalados
  pelo script **Install Certificates.command**, portanto, ele só
  precisa ser executado uma vez.

* Se você não puder depender do link em "/usr/local/bin" apontando
  para "python3.14t" com threads livres do "python.org" (por exemplo,
  se quiser instalar sua própria versão lá ou se alguma outra
  distribuição instalá-lo lá), você poderá definir explicitamente sua
  variável de ambiente de console "PATH" para incluir o diretório da
  framework "PythonT" "bin":

     export PATH="/Library/Frameworks/PythonT.framework/Versions/3.14/bin":"$PATH"

  A instalação tradicional do framework por padrão faz algo
  semelhante, exceto pelo arquivo "Python.framework". Observe que ter
  dois diretórios "bin" do framework em "PATH" pode gerar confusão se
  houver nomes duplicados, como "python3.14", em ambos; qual deles é
  realmente usado depende da ordem em que aparecem em "PATH". Os
  comandos "which python3.x" ou "which python3.xt" pode mostrar qual
  caminho está sendo usado. Usar ambientes virtuais pode ajudar a
  evitar essas ambiguidades. Outra opção pode ser criar um **alias**
  no console para o interpretador desejado, como:

     alias py3.14="/Library/Frameworks/Python.framework/Versions/3.14/bin/python3.14"
     alias py3.14t="/Library/Frameworks/PythonT.framework/Versions/3.14/bin/python3.14t"


5.5.2. Instalação usando a linha de comando
-------------------------------------------

Se você quiser usar automação para instalar o pacote de instalação
"python.org" (em vez de usar o aplicativo GUI **Installer** do macOS),
o utilitário para linha de comando **installer** permite que você
selecione opções que não sejam do padrão. Se você não estiver
familiarizado com o **installer**, ele pode ser um tanto enigmático
(consulte: command:*man installer* para obter mais informações). Como
exemplo, o seguinte trecho de console mostra uma maneira de fazer
isso, usando a versão "3.14.0b2" e selecionando a opção de
interpretador com threads livres:

   RELEASE="python-3.140b2-macos11.pkg"

   # download installer pkg
   curl -O https://www.python.org/ftp/python/3.14.0/${RELEASE}

   # create installer choicechanges to customize the install:
   #    enable the PythonTFramework-3.14 package
   #    while accepting the other defaults (install all other packages)
   cat > ./choicechanges.plist <<EOF
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <array>
           <dict>
                   <key>attributeSetting</key>
                   <integer>1</integer>
                   <key>choiceAttribute</key>
                   <string>selected</string>
                   <key>choiceIdentifier</key>
                   <string>org.python.Python.PythonTFramework-3.14</string>
           </dict>
   </array>
   </plist>
   EOF

   sudo installer -pkg ./${RELEASE} -applyChoiceChangesXML ./choicechanges.plist -target /

Você pode então testar que ambas as compilações de instaladores estão
disponíveis com algo como:

   $ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
   $ /usr/local/bin/python3.14t -VV
   Python 3.14.0b2 free-threading build (v3.14.0b2:3a83b172af, Jun  5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
   $ #    and the traditional interpreter
   $ /usr/local/bin/python3.14 -VV
   Python 3.14.0b2 (v3.14.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
   $ # test that they are also available without the prefix if /usr/local/bin is on $PATH
   $ python3.14t -VV
   Python 3.14.0b2 free-threading build (v3.14.0b2:3a83b172af, Jun  5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
   $ python3.14 -VV
   Python 3.14.0b2 (v3.14.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]

Nota:

  Os instaladores atuais do "python.org" só instalam em locais fixos,
  como "/Library/Frameworks/", "/Applications" e "/usr/local/bin". Não
  é possível usar a opção "-domain" do **installer** para instalar em
  outros locais.


5.5.3. Distribuindo aplicações Python
-------------------------------------

Existe uma variedade de ferramentas para converter seu código Python
em uma aplicação distribuível independente:

* py2app: Oferece suporte à criação de pacotes ".app" do macOS a
  partir de um projeto Python.

* Briefcase: Parte do BeeWare Project; uma ferramenta de empacotamento
  multiplataforma que permite criar *bundles* ".app" no macOS, além de
  gerenciar assinaturas digitais e a notarização.

* PyInstaller: Uma ferramenta de empacotamento multiplataforma que
  cria um único arquivo ou pasta como um artefato distribuível.


5.5.4. Conformidade com a App Store
-----------------------------------

As aplicações enviadas para distribuição pela macOS App Store devem
passar pelo processo de revisão de aplicativos da Apple. Esse processo
inclui um conjunto de regras de validação automatizadas que
inspecionam o pacote de aplicativos enviado em busca de código
problemático.

A biblioteca padrão do Python contém alguns códigos que violam essas
regras automatizadas. Embora essas violações pareçam ser falsos
positivos, as regras de revisão da Apple não podem ser contestadas.
Portanto, é necessário modificar a biblioteca padrão do Python para
que uma aplicação passe na revisão da App Store.

A árvore de fontes do Python contém um arquivo de patch que removerá
todo o código que é conhecido por causar problemas no processo de
revisão da App Store. Este patch é aplicado automaticamente quando o
CPython é configurado com a opção "--with-app-store-compliance".

Este patch normalmente não é necessário para usar o CPython em um Mac;
nem é necessário se você estiver distribuindo uma aplicação *fora* da
App Store do macOS. É necessário *apenas* se você estiver usando a App
Store do macOS como canal de distribuição.


5.6. Outros recursos
====================

A página de ajuda do python.org contém links para vários recursos
úteis. A lista de discussão Pythonmac-SIG é outro recurso específico
de suporte para usuários e desenvolvedores de Python no Mac.
