2. Instalação de um ambiente de trabalho

2.1. Python 3.8.1

Os exemplos deste documento foram testados com o interpretador Python 3.8.1 disponível em URL |https://www.python.org/downloads/| (fevereiro de 2020) num computador com Windows 10:

A instalação do Python cria a estrutura de ficheiros [1] e o menu [2] na lista de programas:

[3-4]: dois interpretadores Python interativos;
[5]: a documentação do Python;
[6]: a documentação dos módulos Python;

Não iremos utilizar o interpretador Python interativo. Basta saber que os scripts deste documento poderiam ser executados com este interpretador. É prático para testar o funcionamento de uma funcionalidade Python, mas pouco útil para scripts que devam ser reutilizados. Eis um exemplo com a opção [4] acima referida:

O prompt >>> permite introduzir uma instrução Python que é executada imediatamente. O código digitado acima tem o seguinte significado:

>>> nom="tintin"
>>> print("nom=%s" % nom)
nom=tintin
>>> print("type=%s" % type(nom))
type=<class 'str'>
>>>

Linhas:

1: inicialização de uma variável. Em Python, não se declara o tipo das variáveis. Estas assumem automaticamente o tipo do valor que lhes é atribuído. Este tipo pode mudar ao longo do tempo;
2: exibição do nome. «nom=%s» é um formato de exibição em que %s é um parâmetro formal que designa uma cadeia de caracteres. nom é o parâmetro efetivo que será exibido no lugar de %s;
3: o resultado da exibição;
4: a exibição do tipo da variável «nom»;
5: a variável «nom» é aqui do tipo class. Com o Python 2.7, teria o valor <type 'str'>;

Agora, vamos abrir uma consola do Windows:

O facto de termos conseguido escrever [python] em vez de [1] e de o executável [python.exe] ter sido encontrado mostra que este se encontra no PATH da máquina Windows. Isto é importante porque significa que as ferramentas de desenvolvimento Python conseguirão encontrar o interpretador Python. É possível verificar isto da seguinte forma:

no [2], sai-se do interpretador Python;
em [3], o comando que apresenta o PATH dos executáveis da máquina Windows;
em [4], verifica-se que a pasta do interpretador Python 3.8 faz parte do PATH;

2.2. O IDE PyCharm Community

2.2.1. Introdução

Para compilar e executar os scripts deste documento, utilizámos o editor [PyCharm], edição Community, disponível (fevereiro de 2020) em URL |https://www.jetbrains.com/fr-fr/pycharm/download/#section=windows| :

Descarregue o IDE, o PyCharm Community e o [1-3] e instale-os.

Vamos iniciar o IDE PyCharm e, em seguida, criar um primeiro projeto em Python:

no [2-4], crie um novo projeto;

O IDE PyCharm apresenta o projeto criado da seguinte forma:

no [2-3], vamos analisar as propriedades do IDE;

em [4], o interpretador Python que será utilizado para o projeto;
em [5], uma lista suspensa dos interpretadores disponíveis;
em [6], seleciona-se o interpretador descarregado no parágrafo |Python 3.8.1|;

em [7], o interpretador selecionado;
em [8], a lista de pacotes disponíveis com este interpretador. Os pacotes contêm módulos que os scripts Python podem utilizar. Existem centenas de módulos disponíveis;

Comecemos por criar uma pasta onde iremos colocar o nosso primeiro script Python:

clique com o botão direito do rato no projeto e, em seguida, em [1-2] para criar uma pasta;
em [3], digite o nome da pasta: esta será criada na pasta do projeto;

Em seguida, vamos criar um script Python:

clique com o botão direito do rato na pasta [bases] e, em seguida, em [1-3];
em [4-5], indique o nome do script;

Vamos escrever o nosso primeiro script:

no ficheiro [3], escrevemos o seguinte script:
- linhas 1 e 3: os comentários começam com o símbolo #;
- linha 2: inicialização de uma variável. O Python não declara o tipo das suas variáveis;
- linha 4: saída para o ecrã. A sintaxe utilizada aqui é [format % données] com:
  - formato: nome=%s, em que %s indica a posição de uma cadeia de caracteres. Esta será encontrada na parte [données] da expressão;
  - dados: o valor da variável [nom] substituirá o formato %s na cadeia de formato;
- com [4-5], reformata-se o código de acordo com as recomendações do organismo responsável pelo Python;

O script é executado com um clique direito no código [6]:

em [7], o comando executado;
em [8], o resultado da execução;

Para executar o script do documento, descarregue o código em URL |https://tahe.developpez.com/tutoriels-cours/python-flask-2020/documents/python-flask-2020.rar| e, em seguida, em PyCharm, proceda da seguinte forma:

em [1-2], abertura de um projeto existente: indicar a pasta do código descarregado;
no [3], o projeto aberto;
em [4-5], execução de um dos scripts do projeto;

em [7-8], os resultados da execução;

2.2.2. Ambiente virtual de execução

O nosso ambiente de trabalho já está operacional. No entanto, vamos modificá-lo para escrever os scripts deste curso. Em primeiro lugar, vamos alterar a configuração do Pycharm:

Na janela da direita:

por predefinição, a caixa de seleção [1] está marcada. Desmarcamo-la para que o Pycharm não abra, por predefinição, o último projeto aberto, mas nos permita escolher o que queremos abrir;
em [2], não se confirma o encerramento do Pycharm ao fechar a janela da aplicação;
em [3], os novos projetos são abertos numa janela diferente;
em [4], se fecharmos o Pycharm e houver um programa em execução, este é interrompido;

Vamos agora fechar o PyCharm e reabri-lo:

em [1], cria-se um novo projeto;
em [2], indicar a pasta do projeto;
No [3], utilize um ambiente virtual. Um ambiente virtual é específico do projeto que se está a criar. Não se mistura com os ambientes virtuais de outros projetos. Um projeto Python/Flask utiliza várias bibliotecas externas que têm de ser instaladas. Um projeto P1 pode utilizar a biblioteca B na sua versão v1 e um projeto P2 pode utilizar a mesma biblioteca B, mas na sua versão v2. Estas duas versões podem ser mais ou menos compatíveis. No entanto, quando se instala uma biblioteca na sua versão v2 e já existe uma versão v1 instalada, esta é substituída pela versão v2. Isto pode ser problemático para o projeto que utilizava a versão v1, caso a nova versão v2 não seja totalmente compatível com a versão v1. Para evitar estes problemas, isola-se cada projeto num ambiente virtual;
em [4], indique a pasta onde serão guardadas as bibliotecas Python que serão descarregadas ao longo do projeto. Escolhemos aqui uma pasta [venv] (ambiente virtual) dentro da pasta do projeto. Não é obrigatório fazer isto;
em [5], o interpretador Python do projeto. É aquele que instalámos na etapa anterior;
em [6], criar o projeto;

em [7-8], o projeto criado;
em [9], o ambiente de execução do projeto, denominado ambiente virtual;
em [10], a pasta [site-packages] é a pasta onde serão guardadas as bibliotecas descarregadas posteriormente;

2.2.3. Git

Em seguida, ativa-se um software de controlo de código-fonte. Neste caso, será o Git [1-4]:

Um software de controlo de código-fonte (VCS: Sistema de Controlo de Versões) permite acompanhar a evolução de um projeto. É possível capturar instantâneos, através de uma operação denominada «commit», do projeto em diferentes momentos do seu ciclo de vida. Se forem efetuados dois «commits» nos momentos T e T+1, o VCS permite saber o que mudou entre as duas versões submetidas. Normalmente, o VCS é utilizado por uma equipa de programadores. Estes efetuam commits do seu código quando este tiver sido devidamente testado. A partir do VCS, os outros programadores podem recuperar esse código validado e utilizá-lo.

Neste caso, há apenas um programador. A experiência mostra que é possível ter uma aplicação que funciona no momento T e que deixa de funcionar no momento T+1. Nessa altura, gostaríamos de voltar atrás para o momento T para recomeçar do zero. O VCS permite isso e é por essa razão que o vamos utilizar aqui.

Mostramos como proceder com o Git.

No [1], selecione o separador [Git] (no canto inferior esquerdo);
no [2], vemos que existem 495 ficheiros do projeto que não estão controlados pelo Git. Isto significa que não farão parte das imagens do projeto durante os commits;
em [3], o botão de [commit] ou botão de validação do projeto. Como já foi referido, o Git tira então um instantâneo do projeto e armazena-o numa pasta [.git] na raiz do projeto (não exibida pelo PyCharm, mas visível no Explorador do Windows);

Vamos validar o projeto no seu estado atual.

em [4], a lista de ficheiros não versionados;
em [5], todos estes ficheiros não versionados pertencem ao ambiente virtual [venv];
em [6], qualquer commit deve ser acompanhado por uma mensagem. O programador descreve aqui as alterações introduzidas pela versão que vai ser submetida, em relação à última versão submetida;

Algumas pastas ou ficheiros podem ser ignorados pelo Git. Nesse caso, nunca fazem parte do repositório. No [5] acima, cliquemos com o botão direito do rato na pasta [venv].

Em [1-3], indica-se que a pasta [venv] não deve fazer parte dos snapshots do Git. A lista de pastas e ficheiros ignorados pelo Git é guardada num ficheiro chamado [.gitignore] [4];

Após a operação anterior, todos os ficheiros da pasta [venv] desaparecem da lista de ficheiros não versionados. Resta apenas o ficheiro [.gitignore], que acabou de ser criado;
no [5], selecionamo-lo para que seja guardado;
em [6], criamos uma mensagem de commit:
em [7], confirmamos. A imagem do projeto é então capturada;

no ficheiro [8-9], o conteúdo do ficheiro [.gitignore]: uma única linha com o nome da pasta [/venv], que indica que o seu conteúdo deve ser ignorado nas fotografias;

Vamos agora mostrar para que nos pode servir o Git. Em primeiro lugar, criamos uma pasta [git] (pode usar qualquer outro nome – poderá ser eliminada no final da demonstração):

em [1-5], criamos uma pasta [git];

em [6-10], criamos um script Python [git_01];

em [11-12], o script contém apenas um comentário;
em [13-14], cria-se uma cópia de [git_01]. Para tal, selecione [git_01] e prima Ctrl-C (Copiar), depois (Ctrl-V) (Colar) e indique [git_02] como nome do ficheiro;

Agora, vamos submeter o nosso projeto. Será tirada uma fotografia com os dois ficheiros [git_01, git_02];

em [1-3], submetemos o projeto;
em [4], selecionamos os ficheiros não versionados que queremos submeter, neste caso todos;
no [5], insere-se a mensagem que identifica o commit;
em [6], confirma-se;

em [1-2], confirma-se o commit;
em [3], seleciona-se o separador [Log];
em [4], uma vista dos ramos do projeto. Aqui, existe apenas um ramo denominado [master];
em [5-6], o commit que acabou de ser efetuado;

Agora, vamos criar, da mesma forma, um script [git_03]:

Alteremos o script [git_02] e eliminemos o script [git_01]:

Em seguida, vamos submeter a nova versão:

Agora temos dois commits nos registos:

Quando selecionamos um commit específico, aparece à sua direita a árvore de ficheiros do projeto:

Suponhamos agora que o último commit nos tenha levado a um impasse e que queiramos voltar a uma situação correspondente a um dos commits anteriores:

em [1-2], selecionamos o commit ao qual queremos regressar;
em [3-5], existem vários modos de repor. Escolhemos o modo [hard], que volta ao estado selecionado, perdendo as alterações que foram feitas desde então;

em [6], recuperámos o [git_01] que tinha sido eliminado;
em [7-8], recuperamos o [git_02] no seu estado original, sem a alteração que tinha sido feita;

Agora, vamos alterar o [git_02] e adicionar o [git_03] e o [1-4]:

Agora, vamos repetir a operação de voltar ao commit inicial:

em [1-4], voltamos à imagem do commit n.º 1;
em [5-6], escolhe-se a opção [Keep] em vez de [Hard]. Estas opções não são fáceis de compreender. Por isso, é preciso experimentá-las:

em [1], o ficheiro [git_03] continua lá;
ao converter para [2-3], o ficheiro [git_02] manteve as suas alterações;

É difícil dizer o que este [Revert Commit] fez. Agora, vamos fazer o commit da situação atual:

no [1-6], o commit;

no [9], vemos o novo commit;

Agora, vamos tentar voltar ao commit 1, tal como já foi feito:

em [1-6], voltamos ao commit n.º 1 no modo [Hard];

em [7-8], desta vez perdemos efetivamente todas as alterações feitas desde o primeiro commit;

Daqui em diante, não voltaremos a abordar o [Git]. O leitor poderá trabalhar da seguinte forma:

poderá seguir os exemplos apresentados, quer digitando-os ele próprio, quer descarregando-os do site do curso;
sempre que um exemplo funcionar, poderá fazer um commit do seu projeto;
quando estiver a desenvolver os seus próprios códigos e se encontrar num impasse, sabe que pode regressar a uma situação estável, voltando a um commit anterior;

2.3. Convenções de escrita de código Python

É possível escrever código Python sem seguir convenções de escrita e isso não impedirá que funcione. Mas poderá não ser bem visto pela comunidade Python, que estabeleceu convenções de escrita. Estas estão resumidas num post disponível em |https://stackoverflow.com/questions/159720/what-is-the-naming-convention-in-python-for-variable-and-function-names|:

o nome de um módulo (module_name) segue uma convenção por vezes denominada [snake_case]: todo em minúsculas, podendo incluir palavras separadas pelo caractere sublinhado. Esta convenção [snake_case] aplica-se aos nomes de métodos, pacotes, variáveis e funções;
o nome de uma classe (ClassName) segue uma convenção por vezes denominada [PascalCase]: uma sequência de palavras unidas, com a primeira letra de cada palavra em maiúscula;
os nomes das constantes seguem a convenção [SNAKE_CASE]: sequência de palavras em maiúsculas separadas pelo caractere de sublinhado;

Estas convenções foram, em geral, seguidas neste documento. No entanto, no caso dos módulos que definem uma classe, atribuí ao módulo o mesmo nome que a classe que ele contém. Assim, segue a convenção [PascalCase] em vez de [snake_case]. O meu objetivo era poder identificar rapidamente os módulos de classes.