Tutorial 1 - Seu primeiro app¶

Estamos prontos para criar nossa primeira aplicação.

Instale as ferramentas do BeeWare¶

Primeiro, precisamos instalar o Briefcase. Briefcase é uma ferramenta do BeeWare que pode ser usada para empacotar sua aplicação para distribuição aos usuários finais - mas também pode ser usada para iniciar um novo projeto. Certifique-se de estar no diretório beeware-tutorial que você criou no Tutorial 0, com o ambiente virtual beeware-venv ativado, e execute:

macOSLinuxWindows

(beeware-venv) $ python -m pip install briefcase

(beeware-venv) $ python -m pip install briefcase

Possíveis erros durante a instalação

Se você observar erros durante a instalação, é quase certo que alguns dos requisitos do sistema não foram instalados. Certifique-se de ter instalado todos os pré-requisitos da plataforma.

(beeware-venv) C:\...>python -m pip install briefcase

Possíveis erros durante a instalação

É importante usar o comando python -m pip, em vez de apenas pip. Isso porque o Briefcase precisa garantir que as versões do pip e setuptools estejam atualizadas, pois o pip usado sozinho não consegue se atualizar. Se quiser entender melhor o motivo, o Brett Cannon escreveu um post detalhado no blog dele.

Iniciar um novo projeto¶

Vamos iniciar nosso primeiro projeto BeeWare! Vamos usar o comando new do Briefcase para criar um aplicativo chamado Hello World. Execute o seguinte em seu prompt de comando:

macOSLinuxWindows

(beeware-venv) $ briefcase new

(beeware-venv) $ briefcase new

(beeware-venv) C:\...>briefcase new

O Briefcase solicitará alguns detalhes sobre nosso novo aplicativo. Para os propósitos deste tutorial, utilize o seguinte:

Formal Name - Aceite o valor padrão: Hello World.
App Name - Aceite o valor padrão: helloworld.
Bundle - Se você possui seu próprio domínio, insira esse domínio invertido. (Por exemplo, se você possui o domínio "cupcakes.com", insira com.cupcakes como nome do bundle). Se você não possui seu próprio domínio, aceite o padrão (com.example).
Project Name - Aceite o valor padrão: Hello World.
Description - Aceite o valor padrão (ou, se quiser ser realmente criativo, crie sua própria descrição!)
Author - Insira seu próprio nome.
Author's email - Insira seu próprio endereço de e-mail. Ele será usado no arquivo de configuração, em textos de ajuda e em qualquer lugar onde um e-mail seja necessário ao enviar o aplicativo para uma loja de aplicativos.
URL - A URL da página inicial do seu aplicativo. Novamente, se você possui seu próprio domínio, insira uma URL nesse domínio (incluindo o https://). Caso contrário, apenas aceite a URL padrão (https://example.com/helloworld). Esta URL não precisa realmente existir (por enquanto); ela será usada apenas se você publicar sua aplicação em uma loja de aplicativos.
License - Aceite o valor padrão (BSD). Isso não afetará nada sobre o funcionamento do tutorial. Se você tem preferências particulares em relação à escolha de licença, sinta-se à vontade para escolher outra licença.
GUI framework - Aceite a opção padrão, Toga (a própria biblioteca de interface gráfica da BeeWare).

O Briefcase então gerará uma estrutura básica de projeto para você usar. Se você seguiu este tutorial até agora e aceitou as configurações padrão como descrito, seu sistema de arquivos deve se parecer com algo assim:

beeware-tutorial/
├── beeware-venv/
│   └── ...
└── helloworld/
    ├── CHANGELOG
    ├── LICENSE
    ├── pyproject.toml
    ├── README.rst
    ├── src/
    │   └── helloworld/
    │       ├── app.py
    │       ├── __init__.py
    │       ├── __main__.py
    │       └── resources/
    │           └── README
    └── tests/
        ├── helloworld.py
        ├── __init__.py
        └── test_app.py

Essa estrutura atual já é um aplicativo totalmente funcional sem adicionar mais nada. A pasta src contém todo o código do aplicativo, a pasta tests contém uma suíte de testes inicial, e o arquivo pyproject.toml descreve como empacotar o aplicativo para distribuição. Se você abrir o pyproject.toml em um editor, verá os detalhes de configuração que você acabou de fornecer ao Briefcase.

Agora que temos um aplicativo inicial, podemos usar o Briefcase para executar a aplicação.

Inicie o app no modo de desenvolvedor¶

Vá para o diretório do projeto helloworld e peça ao Briefcase para iniciar o projeto no modo de Desenvolvedor (ou dev):

macOSLinuxWindows

(beeware-venv) $ cd helloworld
(beeware-venv) $ briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cpython-313-darwin)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

(beeware-venv) $ cd helloworld
(beeware-venv) $ briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cpython-313-x86_64-linux-gnu)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

(beeware-venv) C:\...>cd helloworld
(beeware-venv) C:\...>briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cp313-win_amd64)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

Isso deve abrir uma janela GUI:

macOSLinuxWindows

Possíveis erros ao executar briefcase dev

Se você receber uma mensagem de erro ao executar briefcase dev, é quase certo que alguns dos requisitos do sistema não foram instalados. Certifique-se de ter [instalado todos os pré-requisitos da plataforma]; a mensagem de erro que você receberá deve indicar quais pacotes estão faltando.

Janela Hello World Tutorial 1, no Windows

Requisitos inválidos ou o pip não consegue se conectar

Se você encontrar o erro:

Unable to install requirements. This may be because one of your
requirements is invalid, or because pip was unable to connect
to the PyPI server.

Confirme que você está executando uma versão do python compatível com este tutorial.

Se a sua versão do python não for suportada, você terá que reiniciar o tutorial.

Pressione o botão de fechar (ou selecione Sair no menu do aplicativo) e pronto! Parabéns - você acabou de criar um aplicativo autônomo e nativo em Python!

Próximos passos¶

Agora temos um aplicativo funcional, em execução no modo de desenvolvedor. Podemos adicionar alguma lógica própria para tornar nosso aplicativo um pouco mais interessante. No Tutorial 2, vamos colocar uma interface de usuário mais útil em nossa aplicação.