## Introdução O Logto, como um serviço de identidade, proporcionar uma experiência suave em várias linguagens de programação e frameworks é essencial. Isso muitas vezes envolve a criação de Kits de Desenvolvimento de Software (SDKs). No entanto, quando a linguagem de programação está fora da nossa pilha de tecnologia e nossa equipe não tem familiaridade, construir um SDK robusto torna-se um desafio. Python representou tal desafio para nós. Apesar de termos muitos usuários de Python, faltava-nos um SDK em Python, uma preocupação persistente. Determinado a resolver isso, comecei a preencher essa lacuna. Embora eu tenha anos de experiência em programação, Python ainda é relativamente desconhecido para mim. Embora eu tenha brincado com Python 2 brevemente para scripts simples anos atrás, meu conhecimento estava desatualizado. No entanto, era hora de mergulhar de cabeça! ## Dia 1: Lançar as bases ### Definir o objetivo Na minha experiência, a abordagem mais eficaz para aprender uma nova linguagem de programação é construir um projeto completo. Felizmente, nosso objetivo estava claro: construir um SDK Logto em Python para aplicativos web. Em vez de pular direto para o código, vamos dividir o processo. Aqui está a lista: 1. Criar o cliente Logto para tarefas como login, logout, informações de usuário e gerenciamento de tokens. 2. Fornecer um tutorial e um projeto exemplo mostrando o uso do SDK. 3. Publicar o SDK em algum lugar para que os usuários possam instalá-lo facilmente. Parece que a tarefa 1 tem o maior volume de trabalho, então precisamos confirmar o escopo e continuar a dividi-la. Este passo é crucial para garantir os limites do projeto, evitando expansão de escopo e engenharia excessiva. Trabalhos anteriores de nossa equipe me salvaram muito tempo: - Uma [convenção de SDK](https://docs.logto.io/docs/references/sdk-convention/) delineou a estrutura e o design da API dos SDKs. - SDKs existentes para diferentes linguagens proporcionaram insights sobre padrões e possíveis melhorias para Python. Referenciando esses recursos, posso ver um panorama claro do que fazer. Embora os detalhes estejam além do escopo deste artigo, vamos avançar. ### Configurar o ambiente Estou usando um Mac, então o Python já está instalado. No entanto, estava me perguntando se existia uma forma melhor de gerenciar as versões do Python (ouvi sobre a dor da compatibilidade de versões), assim como o `nvm` para Node.js. Rapidamente, encontrei o [pyenv](https://github.com/pyenv/pyenv) e comecei a instalá-lo diretamente. Não se prenda aos detalhes pontuais neste estágio. O objetivo é começar o mais rápido possível. Opte por ferramentas amplamente adotadas e avance. Mudanças sempre podem ser feitas mais tarde. O próximo item na agenda: um gerenciador de pacotes e dependências. Normalmente eles estão acoplados. Então, por que não o `pip` (o padrão do Python)? Se você der uma olhada no `requirements.txt`, verá que é apenas uma lista de pacotes com versões. Isso não é suficiente para um SDK que pode ser usado por outros projetos. Por exemplo, podemos precisar adicionar alguns pacotes para desenvolvimento, mas não queremos incluí-los no SDK final. O `requirements.txt` é muito simples para lidar com isso. Um dos benefícios de se ter outras linguagens de programação na sua pilha de tecnologia é que você pode procurar um "equivalente em Python". Então eu procurei por "equivalente do package.json em Python" e encontrei o [Poetry](https://python-poetry.org/), um candidato excelente: - Funciona como um gerenciador de pacotes, gerenciador de dependências e gerenciador de ambiente virtual. - Possui um arquivo `pyproject.toml`, semelhante ao `package.json` no Node.js. - Emprega um arquivo de bloqueio (`lockfile`) para registrar versões exatas de dependências. CLIs modernos muitas vezes incluem um comando `init` voltado para novos projetos. O mesmo ocorre com o Poetry. Executei o comando e ele criou um arquivo `pyproject.toml` para mim. ### A primeira linha de código Finalmente, o momento para escrever código chegou. Começar com o clássico programa "Hello, World!" é sempre uma boa escolha. Ao aprender uma linguagem de programação, IDEs completas não são sempre essenciais; um editor respaldado por uma comunidade forte, como o VS Code, é totalmente adequado. Dado o foco do nosso SDK em aplicativos web, comecei com um servidor web simples utilizando o popular framework Flask. Aproveitando as capacidades do Poetry, instalar o Flask pode ser feito facilmente executando `poetry add flask`. Em seguida, seguindo o guia de início rápido oficial do Flask, compus um arquivo 'hello.py' com o seguinte trecho: ```python from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return "

Hello, World!

" ``` Lançando o servidor via `flask --app hello run` e navegando até http://localhost:5000 no meu navegador obtive o resultado desejado. Funcionou! A metodologia para selecionar o Flask e pacotes adicionais espelha a abordagem adotada para o pyenv e o Poetry. Dada a sua natureza repetitiva, esses detalhes são omitidos nas seções subsequentes. Como iniciante, eu não estava com pressa de escrever mais código. Em vez disso, há muitas informações para obter do trecho de código: - Use `from x import y` para importar um módulo ou uma classe. - Não há ponto e vírgula para terminar as linhas (oh não). - Podemos definir uma nova variável inserindo qualquer nome arbitrário e atribuindo um valor a ela. - Criando uma instância de uma classe sem a palavra-chave `new`. - Python suporta decoradores, e o `@app.route` serve como decorador que registra uma função como manipulador de rota. - O valor de retorno da função é interpretado como o corpo da resposta. - Podemos definir uma função usando a palavra-chave `def`. Como você pode ver, se tentarmos entender cada linha de código em vez de "apenas fazer funcionar", podemos aprender muito com isso. Enquanto isso, a documentação oficial do Flask explicou ainda mais o trecho de código em detalhes. Minha estratégia principal é primeiro ler a documentação oficial antes de buscar outros recursos. Geralmente é a maneira mais eficiente de aprender algo novo. ### Início do projeto Agora é hora de começar o projeto. Logo defini uma classe `LogtoClient` e tentei adicionar algumas propriedades e métodos para sentir a linguagem: ```python class LogtoClient: def __init__(self, config = 'config'): self.config = config def signIn(self): return 'signIn' + self.config ``` Em seguida, integrei a classe com o Flask: ```python from logto import LogtoClient client = LogtoClient() @app.route("/") def hello_world(): return client.signIn() ``` Começou a parecer um projeto real. Mas senti que faltava algo: um sistema de tipos. ### Sistema de tipos Como é um SDK, incorporar um sistema de tipos ajudará os usuários a entender a API e reduzirá a chance de erros durante o desenvolvimento. Python introduziu [type hints](https://docs.python.org/3/library/typing.html) na versão 3.5. Não é tão poderoso quanto o TypeScript, mas é melhor do que nada. Adicionei algumas type hints à classe `LogtoClient`: ```python from typing import Optional class LogtoClient: def __init__(self): self.config: str | None = 'config' def signIn(self) -> str: return 'signIn' + self.config ``` Parece muito melhor agora. Mas o desafio surgiu quando se trata de um tipo complexo como um objeto com chaves predefinidas. Por exemplo, precisamos definir uma classe `LogtoConfig` para representar o objeto de configuração: ```python class LogtoConfig: def __init__(self, clientId: str, clientSecret: str): self.clientId = clientId self.clientSecret = clientSecret # ... ``` Parece bom, mas logo teremos que enfrentar problemas de codificação, decodificação e validação do objeto a partir do JSON. Sempre priorize soluções nativas. Se elas realmente não funcionarem, explore bibliotecas de terceiros. Somente quando todas as alternativas falharem, considere criar sua própria solução. Após alguma pesquisa, escolhi o [pydantic](https://pydantic-docs.helpmanual.io/) como solução. É uma biblioteca de validação de dados que trabalha com type hints. Ela suporta diversas funcionalidades JSON sem precisar seguir códigos boilerplate tediosos. Assim, a classe `LogtoConfig` pode ser reescrita como: ```python from pydantic import BaseModel class LogtoConfig(BaseModel): clientId: str clientSecret: str # ... ``` Isso também me ensinou sobre herança de classes em Python ao adicionar parênteses após o nome da classe. ### Operações assíncronas Dentro do SDK Logto, precisamos fazer requisições HTTP ao servidor Logto. Se você tem experiência com JavaScript, a expressão "callback hell" provavelmente lhe soa familiar. É um problema comum quando se lida com operações assíncronas. Linguagens de programação modernas apresentam soluções semelhantes como `Promise` ou `coroutine`. Eu sempre me lembro do objetivo. Se um certo nível de conhecimento for suficiente para alcançar o objetivo, então eu não preciso me aprofundar mais, pois sempre posso voltar mais tarde. Enquanto isso, compreensão profunda é necessária dentro de um certo nível. Assim, posso lidar com várias situações no futuro. A chave é encontrar o equilíbrio, e isso não é fácil. Eu talvez escreva outro artigo sobre este tópico no futuro. Felizmente, Python tem uma solução nativa de `async` e `await`. Antes de usá-los, certifique-se de que há compatibilidade com frameworks populares. No Flask, isso pode ser feito instalando o extra `async` e usando `async def` em vez de `def`: ```python @app.route("/") async def hello_world(): # ... ``` Então podemos usar `await` para esperar pelo resultado de uma operação assíncrona. ### Requisições HTTP Requisições HTTP são um tópico interessante. Quase toda linguagem de programação tem uma solução nativa, mas os desenvolvedores geralmente usam uma biblioteca de terceiros pela facilidade de uso. Alguns exemplos: - JavaScript: `XMLHttpRequest` vs. `fetch` vs. `axios` - Swift: `URLSession` vs. `Alamofire` - Java: `HttpURLConnection` vs. `OkHttp` Isso também é verdade para Python. Minha decisão foi usar o [aiohttp](https://docs.aiohttp.org/) pois ele suporta `async` e `await`, além de ser bastante popular. ### A magia do Copilot Antes do Copilot, agora estaríamos chegando à parte tediosa de escrever a lógica de negócios. Com a ajuda da convenção de SDK e de outros SDKs, posso escrever os comentários descritivos para cada método antes de escrever o código. Isso adiciona mais legibilidade ao código, além de ajudar os desenvolvedores a entender a API diretamente no IDE ou editor via inteligência de código. Por exemplo, considere o método `generateCodeChallenge`, os comentários podem ser escritos como: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Gerar uma string de desafio de código para a string de verificador de código fornecida. Consulte: https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2 """ ``` Isso proporcionou um excelente prompt para Modelos de Linguagem Grandes (LLMs): inclui definições de métodos por comentários claros. E o Copilot não decepcionou: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Gerar uma string de desafio de código para a string de verificador de código fornecida. Consulte: https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2 """ codeChallenge = hashlib.sha256(codeVerifier.encode('utf-8')).digest() return base64.urlsafe_b64encode(codeChallenge).decode('utf-8').replace('=', '') ``` Alguns ajustes podem ser necessários, mas não importa. Já mudou o jogo. O Copilot brilha ao produzir código para lógica direta. No entanto, ele pode ter dificuldades quando envolve múltiplas dependências. Como o nome sugere, é um assistente de código, você deve ser o capitão que controla a direção e toma as decisões. ### Conclusão do dia Esse foi basicamente o progresso alcançado no primeiro dia. Foi um dia longo, mas com ferramentas e tecnologias modernas, foi muito melhor do que eu esperava. ## Dia 2: Eleve o nível Com base no trabalho do primeiro dia, a lógica de negócios foi concluída rapidamente. Mas para um SDK, ainda é insuficiente. Aqui estão as tarefas para o segundo dia: - Adicionar testes unitários. - Impor formatação de código. - Verificar compatibilidade de versões do Python. - Adicionar integração contínua. - Publicar o SDK. ### Testes unitários Testes unitários nos salvaram muitas vezes, então não os pularei. Aqui estão considerações comuns ao escrever testes unitários: - Como organizar e executar os testes? - Como afirmar o resultado? - Como executar testes assíncronos? (Parece uma brincadeira, mas ocasionalmente causa problemas em algumas linguagens.) - Como simular as dependências? (Não se aprofunde neste tópico até ser imprescindível, pois pode levar a buracos de coelho.) - Como gerar relatórios de cobertura de código? Com essas perguntas em mente, descobri que o módulo `unittest` embutido era insuficiente para alguns casos. Então escolhi o [pytest](https://docs.pytest.org/) como o framework de testes. Ele suporta testes assíncronos e parece maduro o suficiente. A jornada revelou alguns novos conceitos interessantes como `fixture` para mim. Isso também pode melhorar a mentalidade ao escrever código em outras linguagens. O Copilot é ainda melhor ao escrever testes, ele pode gerar uma multitude de casos de teste práticos. Mesmo que ajustes sejam necessários, o Copilot pode aprender com o novo contexto e aprimorar a geração de código no futuro. ### Formatação de código Toda linguagem tem seus próprios estilos de formatação de código. Pessoalmente, formatação consistente pode me deixar feliz e confortável; também é útil para revisão de código e colaboração. Em vez de navegar pela discussão sobre o "melhor" estilo, decidi escolher um formatador opinativo e me manter fiel a ele. [Black](https://github.com/psf/black) parece uma boa escolha. A única frustração é o tamanho da tabulação não modificável. Mas não é um grande problema, escolhi me adaptar a isso. ### Compatibilidade de versão do Python Como um SDK, ele deve ser compatível com as versões predominantes do Python. Ao buscar "estatísticas de uso de versão do python", determinei usar Python 3.8 como a versão mínima. A virtude do gerenciador de ambiente agora se destaca. Posso alternar facilmente a versão do Python executando `pyenv local 3.8` e `poetry env use 3.8`. Eu então poderia rodar os testes para revelar problemas de compatibilidade. ### Integração contínua A integração contínua garante a qualidade de cada alteração de código. Como nosso repositório estava hospedado no GitHub, o GitHub Actions foi a escolha natural. O fluxo de trabalho principal segue princípios simples: - Configurar o ambiente. - Instalar dependências. - Construir o projeto (não necessário com Python). - Executar os testes. O GitHub Actions tem uma boa comunidade, então leva apenas alguns minutos para construir [o fluxo de trabalho](https://github.com/logto-io/python/blob/9082d9afd25b6876cadad6d9cfebf40d1c43cabc/.github/workflows/main.yml). Empregando estratégias de matriz, podemos executar o fluxo de trabalho em diferentes versões do Python, até mesmo em diferentes sistemas operacionais. ### Publicar o SDK O passo final é publicar o SDK. Para pacotes públicos, isso pode ser normalmente feito enviando para o registro oficial da linguagem específica. Por exemplo, [npm](https://www.npmjs.com/) para Node.js, [PyPI](https://pypi.org/) para Python, e [CocoaPods](https://cocoapods.org/) para Swift. Poetry é a minha estrela guia. Basta executar `poetry publish` para publicar o pacote no PyPI. É simples assim. ## Pensamentos finais Foi uma jornada envolvente. Sem a ajuda da comunidade open-source, teria sido muito mais difícil. Aplausos para todos os contribuidores! Aqui estão alguns aprendizados gerais: - Defina precisamente o objetivo e divida-o, depois sempre mantenha o objetivo em mente. - Configure um ambiente de desenvolvimento estável e reprodutível. - Use (boas) ferramentas tanto quanto possível. - Priorize soluções nativas ou já existentes. - Compreenda convenções de linguagem e cada linha de código que você escreve. - No entanto, não se prenda aos detalhes pontuais. - Use o Copilot para tarefas claras e descritivas. Você pode encontrar o resultado final neste [repositório](https://github.com/logto-io/python). Com a mesma estratégia, também construí rapidamente o [SDK Logto em PHP](https://github.com/logto-io/php). Não hesite em nos informar se tiver alguma sugestão. Espero que este artigo seja útil para aprender uma nova linguagem de programação. Boas hackings! Experimente o Logto Hoje