Tutorial 1 - A sua primeira aplicação

Estamos prontos para criar a 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 a sua aplicação para distribuição aos utilizadores finais - mas também pode ser usada para arrancar um novo projeto. Certifique-se que está 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 observar erros durante a instalação, é quase certo que alguns dos requisitos do sistema não foram instalados. Certifique-se de que instalou 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 tem versões do pip e setuptools atualizadas, e uma invocação simples do pip não faz auto-atualização. Se quiser saber mais sobre isto, o Brett Cannon escreveu um post detalhado no sobre o problema.

Arrancar um novo projeto

Vamos iniciar o nosso primeiro projeto BeeWare! Vamos usar o comando new do Briefcase para criar uma aplicação chamada Hello World. Execute o seguinte na sua linha de comandos:

macOSLinuxWindows

(beeware-venv) $ briefcase new

(beeware-venv) $ briefcase new

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

O Briefcase vai pedir-nos alguns detalhes sobre a nossa nova aplicação. Para os objetivos deste tutorial, utilize o seguinte:

• GUI framework - Aceitar a opção predefinida, Toga (o kit de ferramentas GUI próprio do BeeWare).
• Formal Name - Aceitar o valor predefinido: Hello World.
• App Name - Aceitar o valor predefinido: helloworld.
• Identificador de Bundle - Se tiver o seu próprio domínio, insira esse domínio em ordem inversa. (Por exemplo, se possui o domínio "cupcakes.com", insira com.cupcakes como bundle). Se não possui o seu próprio domínio, aceite o bundle predefinido (com.example).
• Project Name - Aceitar o valor predefinido: Hello World.
• Description - Aceitar o valor redefinido (ou, se quiser ser realmente criativo, crie a sua própria descrição!)
• Author - Insira aqui seu nome próprio.
• Email do Autor - Insira o seu próprio endereço de e-mail. Isto vai ser usado no ficheiro de configuração, em textos de ajuda, e em qualquer lugar onde um e-mail seja necessário ao enviar a aplicação para uma loja de aplicações.
• URL da Aplicação - A URL da página inicial do sua aplicação. Novamente, se possui o seu próprio domínio, insira o URL desse domínio (incluindo o https://). Caso contrário, apenas aceite o URL predefinido (https://example.com/helloworld). Este URL não precisa realmente existir (por enquanto); só será usado se publicar a sua aplicação numa loja de aplicações.
• License do Projeto - Aceite o valor predefinido (BSD). Isto não afetará nada sobre o funcionamento do tutorial - se tem preferências particulares em relação à escolha de licença, sinta-se à vontade de escolher outra licença.

O Briefcase vai então gerar uma estrutura básica de projeto para você usar. Se você seguiu este tutorial até agora, e aceitou as configurações predefinidas como descrito, o seu sistema de ficheiros deve parecer-se 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

Este esqueleto já é mesmo uma aplicação totalmente funcional sem adicionar mais nada. A pasta src contém todo o código da aplicação, a pasta tests contém uma suite de testes inicial, e o ficheiro pyproject.toml descreve como empacotar a aplicação para ser distribuída. Se você abrir o pyproject.toml num editor, verá os detalhes de configuração que você forneceu ao Briefcase.

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

Inicie a aplicação no modo de desenvolvedor

Vá para o diretório do projeto helloworld e diga ao briefcase para iniciar o projeto em modo de Desenvolvedor (ou dev):

macOSLinuxWindows

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

[helloworld] A ativar o ambiente de desenvolvimento...
...
A criar ambiente virtual (dev.cpython-313-darwin)... concluído

[hello-world] A instalar pré-requisitos...
...

[helloworld] A iniciar em modo dev...
===========================================================================

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

[helloworld] A ativar o ambiente de desenvolvimento...
...
A criar ambiente virtual (dev.cpython-313-x86_64-linux-gnu)... concluído

[hello-world] A instalar pré-requisitos...
...

[helloworld] A iniciar em modo dev...
===========================================================================

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

[helloworld] A ativar ambiente de desenvolvimento...
...
A criar ambiente virtual (dev.cp313-win_amd64)... concluído

[hello-world] A instalar pré-requisitos...
...

[helloworld] A iniciar em modo dev...
===========================================================================

Isto deve abrir uma janela GUI:

macOSLinuxWindows

Possíveis erros ao executar briefcase dev

Se receber uma mensagem de erro ao executar briefcase dev, é quase certo que alguns dos requisitos do sistema não foram instalados. Certifique-se de que instalou todos os pré-requisitos da plataforma; a mensagem de erro que recebe deve indicar quais pacotes estão em falta.

Requisitos inválidos ou o pip incapaz de ligar

Se encontrar o erro:

Incapaz de instalar os requerimentos. Isto pode ter ocorrido porque um dos seus
requerimentosos é inválido, ou porque o pip não conseguiu se ligar
ao servidor PyPI.

Confirme que está a correr uma versão do python que este tutorial suporte.

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

Feche a aplicação - seja ao carregar no botão de fechar a janela da aplicação, ao selecionar Sair/Terminar no menu da aplicação, ou por teclas Ctrl+C no terminal onde correu briefcase dev - e está feito! Parabéns - acabou de escrever uma aplicação nativa e autônoma em Python!

Próximos passos

Agora temos um aplicação funcional, a correr em modo de desenvolvedor. Agora podemos adicionar alguma lógica própria para pôr a nossa aplicação a fazer algo mais interessante. No Tutorial 2, vamos colocar uma interface de utilizador mais útil na nossa aplicação.