## Introduzione Logto, in quanto servizio di identità, è essenziale fornire un'esperienza fluida attraverso vari linguaggi di programmazione e framework. Questo spesso comporta la creazione di Software Development Kit (SDK). Tuttavia, quando il linguaggio di programmazione non fa parte del nostro stack tecnologico e il nostro team non è familiare, creare un SDK robusto diventa una sfida. Python ci ha posto questa sfida. Nonostante avessimo molti utenti Python, mancavamo di un SDK Python, una preoccupazione persistente. Determinato a risolvere questo problema, ho iniziato a colmare questa lacuna. Anche se ho anni di esperienza nella programmazione, Python rimane relativamente inesplorato per me. Anche se avevo smanettato con Python 2 brevemente per script semplici anni fa, la mia conoscenza era obsoleta. Tuttavia, era ora di tuffarsi! ## Giorno 1: Posa le fondamenta ### Definisci l'obiettivo Nella mia esperienza, l'approccio più efficace per apprendere un nuovo linguaggio di programmazione è costruire un progetto completo. Fortunatamente, il nostro obiettivo era chiaro: costruire un SDK Python di Logto per applicazioni web. Piuttosto che gettarsi nel codice, scomponiamolo. Ecco la lista: 1. Creare il client Logto per attività come il login, il logout, le informazioni dell'utente e la gestione dei token. 2. Fornire un tutorial e un progetto di esempio per mostrare l'uso dell'SDK. 3. Pubblicare l'SDK da qualche parte in modo che gli utenti possano installarlo facilmente. Sembra che il compito 1 abbia più lavoro, quindi dobbiamo confermare l'ambito e continuare a scomporlo. Questo passaggio è cruciale per garantire i confini del progetto ed evitare l'espansione dell'ambito e l'over-engineering. Il lavoro precedente del nostro team mi ha fatto risparmiare un sacco di tempo: - Una [convenzione SDK](https://docs.logto.io/docs/references/sdk-convention/) ha delineato la struttura e il design delle API degli SDK. - Gli SDK esistenti per diversi linguaggi hanno fornito intuizioni sui modelli e i potenziali miglioramenti per Python. Facendo riferimento a queste risorse, posso vedere un quadro chiaro di ciò che devo fare. Sebbene i dettagli specifici vadano oltre l'ambito di questo articolo, andiamo avanti. ### Configura l'ambiente Sto usando un Mac, quindi Python è già installato. Tuttavia, mi chiedevo se esistesse un modo migliore per gestire le versioni di Python (ho sentito parlare della complessità della compatibilità delle versioni), proprio come `nvm` per Node.js. Rapidamente, ho trovato [pyenv](https://github.com/pyenv/pyenv) e ho iniziato direttamente a installarlo. Non fissarti sui dettagli a questo punto. L'obiettivo è partire il più presto possibile. Scegli strumenti ampiamente adottati e procedi. Le modifiche possono sempre essere fatte in seguito. Il prossimo punto all'ordine del giorno: un gestore di pacchetti e dipendenze. Di solito sono accoppiati. Allora perché non `pip` (il predefinito di Python)? Se dai un'occhiata al `requirements.txt`, noterai che è solo una lista di pacchetti con versioni. Questo non è sufficiente per un SDK che potrebbe essere usato da altri progetti. Per esempio, potremmo aver bisogno di aggiungere alcuni pacchetti per lo sviluppo, ma non vogliamo includerli nell'SDK finale. Il `requirements.txt` è troppo semplice per gestire questo. Uno dei vantaggi di avere altri linguaggi di programmazione nello stack tecnologico è che puoi cercare l'equivalente Python. Quindi ho cercato "equivalente package.json Python" e ho trovato [Poetry](https://python-poetry.org/), un candidato eccellente: - Funziona come gestore di pacchetti, gestore di dipendenze e gestore di ambienti virtuali. - Ha un file `pyproject.toml`, simile a `package.json` in Node.js. - Utilizza un file di blocco per registrare versioni precise delle dipendenze. Le CLI moderne spesso includono un comando `init` progettato per nuovi progetti. Anche Poetry lo fa. Ho eseguito il comando e ha creato per me un file `pyproject.toml`. ### La prima linea di codice Finalmente era arrivato il momento di scrivere il codice. Iniziare con il classico programma "Hello, World!" è sempre una buona scelta. Quando si impara un linguaggio di programmazione, gli IDE completi non sono sempre essenziali; un editor supportato da una comunità forte, come VS Code, è del tutto adeguato. Dato che il nostro SDK si concentra su applicazioni web, ho iniziato con un semplice server web utilizzando il popolare framework Flask. Sfruttando le capacità di Poetry, installare Flask può essere fatto facilmente eseguendo `poetry add flask`. Poi, seguendo la guida rapida ufficiale di Flask, ho scritto un file 'hello.py' con il seguente frammento di codice: ```python from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return "

Hello, World!

" ``` Avviando il server tramite `flask --app hello run` e navigando a http://localhost:5000 nel mio browser ho ottenuto il risultato desiderato. Ha funzionato! La metodologia per la selezione di Flask e pacchetti aggiuntivi rispecchia l'approccio adottato per pyenv e Poetry. Data la natura ripetitiva, questi dettagli vengono omessi nelle sezioni successive. Come principiante, non avevo fretta di scrivere più codice. Invece, ci sono molte informazioni da ricevere dal frammento di codice: - Utilizza `from x import y` per importare un modulo o una classe. - Non ci sono punti e virgola per terminare le righe (oh no). - Possiamo definire una nuova variabile inserendo un nome arbitrario e assegnandogli un valore. - Creazione di un'istanza di una classe senza la parola chiave `new`. - Python supporta i decoratori, e `@app.route` funge da decoratore che registra una funzione come gestore di percorsi. - Il valore di ritorno della funzione è interpretato come corpo della risposta. - Possiamo definire una funzione utilizzando la parola chiave `def`. Come puoi vedere, se proviamo a capire ogni riga di codice invece di "farla semplicemente funzionare", possiamo imparare molto da essa. Nel frattempo, la documentazione ufficiale di Flask ha ulteriormente spiegato il frammento di codice in dettaglio. La mia strategia di riferimento è leggere prima la documentazione ufficiale prima di cercare altre risorse. Di solito è il modo più efficiente per imparare qualcosa di nuovo. ### Inizio del progetto Ora è tempo di iniziare il progetto. Presto ho definito una classe `LogtoClient` e ho cercato di aggiungere alcune proprietà e metodi per familiarizzare col linguaggio: ```python class LogtoClient: def __init__(self, config = 'config'): self.config = config def signIn(self): return 'signIn' + self.config ``` Successivamente, integra la classe con Flask: ```python from logto import LogtoClient client = LogtoClient() @app.route("/") def hello_world(): return client.signIn() ``` Ha iniziato a sembrare un vero progetto. Ma sentivo che mancava qualcosa: un sistema di tipi. ### Sistema di tipi Dato che si tratta di un SDK, l'incorporazione di un sistema di tipi aiuterà gli utenti a comprendere l'API e a ridurre la possibilità di errori durante lo sviluppo. Python ha introdotto [type hints](https://docs.python.org/3/library/typing.html) nella versione 3.5. Non è potente come TypeScript, ma è meglio di niente. Ho aggiunto alcuni suggerimenti di tipo alla 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 ``` Ora sembra molto meglio. Ma la sfida è emersa quando si tratta di un tipo complesso come un oggetto con chiavi predefinite. Per esempio, dobbiamo definire una classe `LogtoConfig` per rappresentare l'oggetto di configurazione: ```python class LogtoConfig: def __init__(self, clientId: str, clientSecret: str): self.clientId = clientId self.clientSecret = clientSecret # ... ``` Sembra ok, ma presto dovremo affrontare i problemi di codifica, decodifica e validazione dell'oggetto da JSON. Prioritizza sempre le soluzioni integrate. Se non funzionano davvero, esplora librerie di terze parti. Solo quando tutte le alternative falliscono, considera di creare la tua soluzione. Dopo un po' di ricerca, ho scelto [pydantic](https://pydantic-docs.helpmanual.io/) come soluzione. È una libreria di validazione dei dati che funziona con i suggerimenti di tipo. Supporta diverse funzionalità JSON senza seguire fastidiosi boilerplate code. Quindi, la classe `LogtoConfig` può essere riscritta così: ```python from pydantic import BaseModel class LogtoConfig(BaseModel): clientId: str clientSecret: str # ... ``` Mi ha anche insegnato l'ereditarietà delle classi in Python aggiungendo parentesi dopo il nome della classe. ### Operazioni asincrone All'interno dell'SDK Logto, dobbiamo fare richieste HTTP al server Logto. Se hai esperienza con JavaScript, l'espressione "callback hell" probabilmente suona familiare. È un problema comune quando si tratta di operazioni asincrone. I linguaggi moderni di programmazione presentano soluzioni simili come `Promise` o `coroutine`. Mi ricordo sempre dell'obiettivo. Se un certo strato di conoscenza è sufficiente per raggiungere l'obiettivo, allora non ho bisogno di scavare più a fondo poiché posso sempre tornare in seguito. Nel frattempo, è richiesta una comprensione approfondita all'interno di uno strato specifico. Così potrò affrontare varie situazioni in futuro. La chiave è trovare l'equilibrio, e non è facile. Potrei scrivere un altro articolo su questo argomento in futuro. Fortunatamente, Python ha una soluzione integrata di `async` e `await`. Prima di usarli, assicurati della compatibilità con i framework più popolari. In Flask, ciò può essere fatto installando il pacchetto extra `async` e usando `async def` invece di `def`: ```python @app.route("/") async def hello_world(): # ... ``` Poi possiamo usare `await` per attendere il risultato di un'operazione asincrona. ### Richieste HTTP Le richieste HTTP sono un argomento interessante. Quasi ogni linguaggio di programmazione ha una soluzione nativa, ma gli sviluppatori di solito usano una libreria di terze parti per comodità. Alcuni esempi: - JavaScript: `XMLHttpRequest` vs. `fetch` vs. `axios` - Swift: `URLSession` vs. `Alamofire` - Java: `HttpURLConnection` vs. `OkHttp` Questo vale anche per Python. La mia decisione è stata di usare [aiohttp](https://docs.aiohttp.org/), poiché supporta `async` e `await`, insieme alla sua popolarità. ### La magia di Copilot Prima di Copilot, ora ci avvicinavamo alla parte tediosa della scrittura della logica di business. Con l'aiuto della convenzione SDK e di altri SDK, posso scrivere i commenti descrittivi per ogni metodo prima di scrivere il codice. Aggiunge maggiore leggibilità al codice e aiuta anche gli sviluppatori a comprendere l'API direttamente nell'IDE o nell'editor tramite l'intelligenza del codice. Per esempio, consideriamo il metodo `generateCodeChallenge`, i commenti possono essere scritti così: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Generare una stringa code challenge per la stringa code verifier fornita. Vedi: https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2 """ ``` Questo ha rappresentato un ottimo prompt per i modelli di linguaggio ampi (LLM): comprendere definizioni di metodi tramite commenti chiari. E Copilot non ha deluso: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Generare una stringa code challenge per la stringa code verifier fornita. Vedi: 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('=', '') ``` Potrebbero essere necessari alcuni aggiustamenti, ma non importa. Ha già cambiato le regole del gioco. Copilot eccelle nella produzione di codice per logiche semplici. Tuttavia, potrebbe avere difficoltà quando si tratta di molteplici dipendenze. Come suggerisce il nome, è un assistente del codice, tu dovresti essere il capitano che controlla la direzione e prende le decisioni. ### Conclusione Questo è praticamente il progresso raggiunto nel primo giorno. È stata una lunga giornata, ma con strumenti e tecnologie moderne, è stato molto meglio di quanto mi aspettassi. ## Giorno 2: Alza il livello Basandosi sul lavoro del primo giorno, la logica di business è stata completata rapidamente. Ma per un SDK, non è ancora sufficiente. Ecco i compiti per il secondo giorno: - Aggiungere test unitari. - Forzare la formattazione del codice. - Verificare la compatibilità delle versioni di Python. - Aggiungere l'integrazione continua. - Pubblicare l'SDK. ### Test unitari I test unitari ci hanno salvato molte volte, quindi non li salterò. Ecco alcune considerazioni comuni quando si scrivono test unitari: - Come organizzare ed eseguire i test? - Come verificare il risultato? - Come eseguire test asincroni? (Sembra una cosa semplice, ma occasionalmente causa problemi in alcuni linguaggi.) - Come simulare le dipendenze? (Non tuffarti in questo argomento finché non è indispensabile, poiché può portare a vicoli ciechi.) - Come generare report di copertura del codice? Con queste domande in mente, ho scoperto che il modulo integrato `unittest` non era sufficiente per alcuni casi. Così ho scelto [pytest](https://docs.pytest.org/) come framework di test. Supporta i test asincroni e sembra abbastanza maturo. Il viaggio mi ha rivelato nuovi concetti interessanti come `fixture`. Questo può anche migliorare la mentalità quando si scrive codice in altri linguaggi. Copilot è ancora più efficace quando si scrivono i test, può generare una moltitudine di casi di test pratici. Anche quando sono necessari aggiustamenti, Copilot può imparare dal nuovo contesto e migliorare la generazione di codice futura. ### Formattazione del codice Ogni linguaggio ha i suoi stili di formattazione del codice. Personalmente, una formattazione coerente può rendermi felice e a mio agio; è anche utile per la revisione del codice e la collaborazione. Piuttosto che sfogliare la discussione sullo stile "migliore", ho deciso di scegliere un formatter opinato e attenervisi. [Black](https://github.com/psf/black) sembra una buona scelta. L'unica frustrazione è la dimensione delle tabulazioni non modificabile. Ma non è un grosso problema, ho deciso di adattarmi. ### Compatibilità delle versioni di Python In quanto SDK, dovrebbe essere compatibile con le versioni più diffuse di Python. Cercando "statistiche sull'uso delle versioni di Python", ho deciso di utilizzare Python 3.8 come versione minima. Ora appare il vantaggio del gestore di ambienti. Posso facilmente cambiare versione di Python eseguendo `pyenv local 3.8` e `poetry env use 3.8`. Poi potrei eseguire i test per rivelare eventuali problemi di compatibilità. ### Integrazione continua L'integrazione continua garantisce la qualità di ogni modifica del codice. Poiché il nostro repository è ospitato su GitHub, GitHub Actions rappresentava la scelta naturale. Il flusso di lavoro principale segue principi semplici: - Configurare l'ambiente. - Installare le dipendenze. - Compilare il progetto (Non è necessario per Python comunque). - Eseguire i test. GitHub Actions ha una buona comunità, quindi bastano pochi minuti per costruire [il flusso di lavoro](https://github.com/logto-io/python/blob/9082d9afd25b6876cadad6d9cfebf40d1c43cabc/.github/workflows/main.yml). Utilizzando strategie a matrice, possiamo eseguire il flusso di lavoro su diverse versioni di Python, persino su diversi sistemi operativi. ### Pubblicazione dell'SDK L'ultimo passaggio è pubblicare l'SDK. Per i pacchetti pubblici, questo può essere fatto generalmente inviandoli al registro dei pacchetti ufficiale per linguaggio specifico. Per esempio, [npm](https://www.npmjs.com/) per Node.js, [PyPI](https://pypi.org/) per Python e [CocoaPods](https://cocoapods.org/) per Swift. Poetry è la mia stella polare. Basta eseguire `poetry publish` per pubblicare il pacchetto su PyPI. È così semplice. ## Pensieri finali È stato un viaggio coinvolgente. Senza l'aiuto della comunità open-source, sarebbe stato molto più difficile. Applaudiamo tutti i contributori! Ecco alcune conclusioni generali: - Definisci esattamente l'obiettivo e scomponilo, quindi tieni sempre a mente l'obiettivo. - Configura un ambiente di sviluppo stabile e riproducibile. - Utilizza (buoni) strumenti il più possibile. - Priorità alle soluzioni integrate o esistenti. - Comprendi le convenzioni del linguaggio e ogni riga di codice che scrivi. - Tuttavia, non fissarti sui dettagli. - Usa Copilot per compiti chiari e descrittivi. Puoi trovare il risultato finale in [questo repository](https://github.com/logto-io/python). Con la stessa strategia, ho anche costruito rapidamente il [Logto PHP SDK](https://github.com/logto-io/php). Non esitare a farci sapere se hai suggerimenti. Spero che questo articolo sia utile per imparare un nuovo linguaggio di programmazione. Buon hacking! Prova Logto Oggi