Tutorial 0 - Vamos nos preparar!

Antes de criarmos a nossa primeira aplicação BeeWare, precisamos garantir que temos todos os pré-requisitos para executar o BeeWare.

Instalar o Python

A primeira coisa que vamos precisar é dum interpretador Python a funcionar.

macOSLinuxWindows

Se estiver a usar Windows, pode descarregar o instalador oficial no site do Python. Pode usar qualquer versão estável do Python desde a 3.10 ou mais recente (apesar de dever evitar versões alfa, beta e candidatas a lançamento). Recomendamos fortemente o Python 3.13 ou mais recente.

Pode também instalar o Python através do homebrew, usar pyenv para gerir múltiplas instalações de Python, ou usar Anaconda ou Miniconda. Não importa como instalou o Python - só importa que possa correr python3 a partir do terminal e obter um interpretador de Python suportado e a funcionar.

O Xcode e as Ferramentas de Desenvolvimento de Linha de Comandos fornecem uma versão do Python; no entanto, esse Python é a versão 3.9. O Python 3.9 chegou ao fim da vida, e não é mais suportado pelo Python ou pelo BeeWare. Não vai poder usar a versão do Python fornecida pelo Xcode para executar este tutorial.

Para verificar a versão do Python que instalou, execute o seguinte comando:

$ python3 --version

Se o Python estiver instalado, vai ver o seu número de versão.

Se estiver a usar Linux, vai instalar o Python usando o gestor de pacotes do sistema ([aptem Debian/Ubuntu/Mint,dnfem Fedora, oupacman` em Arch).

Deve certificar que a versão do Python do sistema é 3.10 ou mais recente; se não for (ex., o Ubuntu 20.04 vem com Python 3.8), vai precisar de atualizar a sua distribuição Linux para algo mais recente.

O suporte para Raspberry Pi está limitado neste momento.

Importante: Você tem de usar o sistema Python fornecido pelo seu sistema operativo. Instalações do Python provenientes de outras fontes (como uv, pyenv, Anaconda, Python compilado manualmente, etc.) vão impedi-lo de empacotar com sucesso a sua aplicação para distribuição nas etapas posteriores deste tutorial.

Se estiver no Windows, pode obter o instalador oficial no sitio web do Python. Pode usar qualquer versão do Python desde 3.10 a 3.14 (embora deva evitar versões alfa, beta e candidatas a lançamento). Recomendamos fortemente o uso do Python 3.13 ou mais recente.

O suporte para Windows em ARM64 está limitado neste momento.

Também pode instalar Python a partir da Windows App Store, ou usar Anaconda ou Miniconda. Não importa como instalou o Python - só importa que possa correr python3 a partir da linha de comandos e obter um interpretador de Python suportado e a funcionar.

Instalar dependências

Em seguida, instale as dependências adicionais necessárias para o seu sistema operativo:

macOSLinuxWindows

Para criar aplicações BeeWare em macOS, é necessário:

• Git, um sistema de controle de versão. Ele está incluído no Xcode ou nas ferramentas de linha de comando para desenvolvedores, que você instalou acima. Talvez precise de abrir o Xcode pela primeira vez para que o Git funcione na sua sessão de terminal. Se ainda não registrar que o Git está instalado, pode precisar de reiniciar a sua sessão no terminal.

Para suportar o desenvolvimento local, será necessário instalar alguns pacotes do sistema. A lista de pacotes necessários varia de acordo com a sua distribuição:

Ubuntu / Debian

$ sudo apt update
$ sudo apt install git build-essential pkg-config python3-dev python3-venv libgirepository1.0-dev libcairo2-dev gir1.2-gtk-3.0 libcanberra-gtk3-module

Red Hat / Fedora

$ sudo dnf install git gcc make pkg-config rpm-build python3-devel gobject-introspection-devel cairo-gobject-devel gtk3 libcanberra-gtk3

Arch / Manjaro

$ sudo pacman -Syu git base-devel pkgconf python3 gobject-introspection cairo gtk3 libcanberra

OpenSUSE Tumbleweed

$ sudo zypper install git patterns-devel-base-devel_basis pkgconf-pkg-config python3-devel gobject-introspection-devel cairo-devel gtk3 'typelib(Gtk)=3.0' libcanberra-gtk3-module

Outras distribuições Linux

Se estiver a usar uma distribuição Linux que não consta nesta lista e não seja derivada de nenhuma das distribuições listadas (ex, Linux Mint e Pop! OS são distribuições derivadas de Debian; AlmaLinux é derivada de Fedora), provavelmente terá dificuldade para concluir este tutorial. Se o Briefcase mostrar uma mensagem de aviso que “Não é possível verificar os pacotes do sistema”, você não vai ser capaz de concluir este tutorial.

Para criar aplicações BeeWare em Windows, é necessário:

• Git, um sistema de controle de versão. Você pode descarregar o Git em [git-scm.com].

Após instalar essas ferramentas, deve reiniciar qualquer sessão de terminal. O Windows apenas vai expôr os novos terminais de ferramentas instaladas iniciados após a conclusão da instalação.

Configurar um ambiente virtual

Agora vamos criar um ambiente virtual - uma "caixa de areia" que podemos usar para isolar nosso trabalho neste tutorial de nossa instalação principal do Python. Se instalarmos pacotes no ambiente virtual, a nossa instalação principal do Python (e qualquer outro projeto Python no nosso computador) não será afetada. Se estragarmos completamente o nosso ambiente virtual, podemos simplesmente apaga-lo e começar de novo, sem afetar nenhum outro projeto Python no nosso computador e sem a necessidade de reinstalar o Python.

macOSLinuxWindows

$ mkdir beeware-tutorial
$ cd beeware-tutorial
$ python3 -m venv beeware-venv
$ source beeware-venv/bin/activate

$ mkdir beeware-tutorial
$ cd beeware-tutorial
$ python3 -m venv beeware-venv
$ source beeware-venv/bin/activate

C:\...>md beeware-tutorial
C:\...>cd beeware-tutorial
C:\...>py -3.12 -m venv beeware-venv
C:\...>beeware-venv\Scripts\activate

Se não estiver a usar o Python 3.12, substitua o -3.12 nestas instruções pelo número da versão que está a usar.

Erros na execução de scripts do PowerShell

Se estiver usando o PowerShell, e receber o erro:

Não é possível carregar o ficheiro C:\...\beeware-tutorial\beeware-venv\Scripts\activate.ps1 porque a execução de scripts está desativada neste sistema.

A sua conta do Windows não tem permissão para executar scripts. Para corrigir isto:

1. Execute o Windows PowerShell como Administrador.
2. Execute set-executionpolicy RemoteSigned
3. Selecione Y para alterar a política de execução.

Depois de fazer isso, pode executar novamente o comando beeware-venv\Scripts\activate.ps1 na sua sessão original do PowerShell (ou numa nova sessão no mesmo diretório).

Se isso funcionou, o seu aviso de comando deve estar diferente agora - deve ter um prefixo (beeware-venv). Isso indica que está atualmente no seu ambiente virtual BeeWare. Sempre que estiver a trabalhar neste tutorial, certifique-se que o seu ambiente virtual esteja ativado. Se não estiver, execute novamente o último comando (o comando activate) para reativar o seu ambiente.

Ambientes virtuais alternativos

Se estiver a usar o Anaconda ou o miniconda, talvez esteja mais familiarizado com o uso de ambientes conda. Talvez também já tenha ouvido falar do virtualenv, um predecessor do módulo venv incorporado no Python. Tal como nas instalações do Python, se estiver no macOS ou no Windows, não importa como você cria o seu ambiente virtual, desde que tenha um. Se estiver no Linux, deve manter-se com o venv e o Python do sistema.

Próximos passos

Agora que configuramos nosso ambiente, estamos prontos para criar a nossa primeira aplicação BeeWare.