## Inleiding Logto, als een identiteitsdienst, biedt een soepele ervaring in verschillende programmeertalen en frameworks. Dit houdt vaak in dat er Software Development Kits (SDK's) worden gemaakt. Echter, wanneer de programmeertaal buiten onze technische stack valt en ons team er niet mee bekend is, wordt het creëren van een sterke SDK een uitdaging. Python was zo'n uitdaging voor ons. Ondanks dat we veel Python-gebruikers hebben, ontbrak ons een Python SDK, een aanhoudende zorg. Vastbesloten om dit aan te pakken, begon ik de kloof te overbruggen. Hoewel ik jarenlange programmeerervaring heb, blijft Python relatief onbekend terrein voor mij. Terwijl ik jaren geleden kort met Python 2 had gewerkt voor eenvoudige scripts, was mijn kennis verouderd. Toch was het tijd om erin te duiken! ## Dag 1: Leg de basis ### Definieer het doel Uit mijn ervaring is de meest effectieve manier om een nieuwe programmeertaal te leren, het bouwen van een compleet project. Gelukkig was ons doel duidelijk: een Logto Python SDK voor webapplicaties bouwen. In plaats van meteen te beginnen met coderen, laten we het opsplitsen. Hier is de lijst: 1. Maak de Logto-client voor taken zoals inloggen, uitloggen, gebruikersinformatie en tokenbeheer. 2. Bied een tutorial en een voorbeeldproject om het gebruik van de SDK te tonen. 3. Publiceer de SDK ergens zodat gebruikers deze eenvoudig kunnen installeren. Het lijkt erop dat taak 1 het meeste werk heeft, dus we moeten de reikwijdte bevestigen en deze verder opsplitsen. Deze stap is cruciaal om de grenzen van het project veilig te stellen en om scope creep en over-engineering te voorkomen. Eerder werk van ons team bespaarde me veel tijd: - Een [SDK-conventie](https://docs.logto.io/docs/references/sdk-convention/) schetste de structuur en API-ontwerp van SDK's. - Bestaande SDK's voor verschillende talen gaven inzicht in patronen en mogelijke verbeteringen voor Python. Met referentie naar deze bronnen zie ik een duidelijk beeld van wat te doen. Hoewel de details buiten de reikwijdte van dit artikel vallen, laten we verder gaan. ### Stel de omgeving in Ik gebruik een Mac, dus Python is al geïnstalleerd. Maar ik vroeg me af of er een betere manier was om de Python-versies te beheren (ik heb gehoord van de pijn van versiecompatibiliteit), net zoals `nvm` voor Node.js. Snel vond ik [pyenv](https://github.com/pyenv/pyenv) en begon direct met de installatie. Niet fixeren op details in deze fase. Het doel is om zo snel mogelijk aan de slag te gaan. Kies voor breed geadopteerde tools en ga verder. Wijzigingen kunnen altijd later worden aangebracht. Vervolgens op de agenda: een pakket- en afhankelijkheidsbeheerder. Gewoonlijk zijn ze gekoppeld. Dus waarom niet `pip` (de standaard Python)? Als je naar de `requirements.txt` kijkt, zie je gewoon een lijst met pakketten met versies. Dit is niet genoeg voor een SDK die door andere projecten kan worden gebruikt. Bijvoorbeeld, we moeten misschien enkele pakketten toevoegen voor ontwikkeling, maar we willen ze niet in de uiteindelijke SDK opnemen. De `requirements.txt` is te simpel om dit aan te pakken. Een van de voordelen wanneer je andere programmeertalen in je technische stack hebt, is dat je kunt zoeken naar het "Python-equivalent". Dus zocht ik naar "package.json Python equivalent" en vond [Poetry](https://python-poetry.org/), een uitstekende kandidaat: - Het werkt als een pakketbeheerder, afhankelijkheidsbeheerder en virtuele omgevingsbeheerder. - Het heeft een `pyproject.toml` bestand, vergelijkbaar met `package.json` in Node.js. - Het gebruikt een lock-bestand om precieze afhankelijkheidsversies te loggen. Moderne CLI's omvatten vaak een `init`-opdracht op maat voor nieuwe projecten. Dat doet Poetry ook. Ik voerde de opdracht uit en het maakte een `pyproject.toml` bestand voor mij aan. ### De eerste regel code Eindelijk was het moment om code te schrijven aangebroken. Beginnen met het klassieke "Hello, World!" programma is altijd een goede keuze. Bij het leren van een programmeertaal zijn volwaardige IDE's niet altijd essentieel; een editor gesteund door een sterke gemeenschap, zoals VS Code, is volledig adequaat. Gezien de focus van onze SDK op webapplicaties begon ik met een eenvoudige webserver met behulp van het populaire framework Flask. Dankzij de mogelijkheden van Poetry kan Flask eenvoudig worden geïnstalleerd door `poetry add flask` uit te voeren. Vervolgens, volgens de officiële quickstart-gids van Flask, maakte ik een 'hello.py' bestand met de volgende code: ```python from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return "

Hello, World!

" ``` Het opstarten van de server via `flask --app hello run` en naar http://localhost:5000 navigeren in mijn browser leverde het gewenste resultaat op. Het werkte! De methodologie voor het selecteren van Flask en extra pakketten weerspiegelt de aanpak die werd aangenomen voor pyenv en Poetry. Vanwege de repetitieve aard worden deze specificaties weggelaten in de volgende secties. Als beginner haastte ik me niet om meer code te schrijven. In plaats daarvan is er voldoende informatie om van de code te ontvangen: - Gebruik `from x import y` om een module of een klasse te importeren. - Geen puntkomma om regels te beëindigen (oei). - We kunnen een nieuwe variabele definiëren door willekeurige namen in te voeren en een waarde eraan toe te wijzen. - Een instantie van een klasse maken zonder het `new`-trefwoord. - Python ondersteunt decorateurs, en de `@app.route` dient als een decorateur die een functie registreert als een route handler. - De retourwaarde van de functie wordt geïnterpreteerd als de response-body. - We kunnen een functie definiëren met behulp van het `def`-trefwoord. Zoals je kunt zien, kunnen we veel leren van elke regel code als we proberen elke regel te begrijpen in plaats van "gewoon te maken dat het werkt". Ondertussen legde de officiële documentatie van Flask verder de snippet in detail uit. Mijn strategie is om eerst de officiële documentatie te lezen voordat ik naar andere bronnen zoek. Gewoonlijk is het de meest efficiënte manier om iets nieuws te leren. ### Project kick-off Nu is het tijd om het project te beginnen. Al snel definieerde ik een `LogtoClient`-klasse en probeerde een aantal eigenschappen en methoden toe te voegen om de taal te voelen: ```python class LogtoClient: def __init__(self, config = 'config'): self.config = config def signIn(self): return 'signIn' + self.config ``` Vervolgens integreer de klasse met Flask: ```python from logto import LogtoClient client = LogtoClient() @app.route("/") def hello_world(): return client.signIn() ``` Het begon als een echt project aan te voelen. Maar ik voelde dat er iets ontbrak: een typesysteem. ### Typesysteem Aangezien het een SDK is, zal het opnemen van een typesysteem gebruikers helpen de API te begrijpen en de kans op fouten bij de ontwikkeling te verkleinen. Python introduceerde [type hints](https://docs.python.org/3/library/typing.html) in versie 3.5. Het is niet zo krachtig als TypeScript, maar beter dan niets. Ik voegde een aantal type hints toe aan de `LogtoClient`-klasse: ```python from typing import Optional class LogtoClient: def __init__(self): self.config: str | None = 'config' def signIn(self) -> str: return 'signIn' + self.config ``` Ziet er nu veel beter uit. Maar de uitdaging ontstond toen het op een complex type aankwam, zoals een object met vooraf gedefinieerde sleutels. Bijvoorbeeld, we moeten een `LogtoConfig`-klasse definiëren om het config-object te vertegenwoordigen: ```python class LogtoConfig: def __init__(self, clientId: str, clientSecret: str): self.clientId = clientId self.clientSecret = clientSecret # ... ``` Het ziet er oké uit, maar al snel zullen we de problemen van het coderen, decoderen en valideren van het object uit JSON onder ogen moeten zien. Geef altijd prioriteit aan ingebouwde oplossingen. Als ze echt niet werken, verken dan derde-partij bibliotheken. Alleen als alle alternatieven falen, overweeg dan om je eigen oplossing te creëren. Na wat onderzoek koos ik [pydantic](https://pydantic-docs.helpmanual.io/) als de oplossing. Het is een gegevensvalidatiebibliotheek die werkt met type hints. Het ondersteunt diverse JSON-functionaliteiten zonder het volgen van omvangrijke boilerplate-code. Dus kan de `LogtoConfig`-klasse worden herschreven als: ```python from pydantic import BaseModel class LogtoConfig(BaseModel): clientId: str clientSecret: str # ... ``` Het leerde mij ook over klasse-erfenis in Python door haakjes toe te voegen na de klassennaam. ### Asynchrone operaties Binnen de Logto SDK moeten we HTTP-verzoeken doen naar de Logto-server. Als je ervaring hebt met JavaScript, klinkt de uitdrukking "callback hell" waarschijnlijk bekend in de oren. Het is een algemeen probleem bij het omgaan met asynchrone operaties. Moderne programmeertalen presenteren vergelijkbare oplossingen zoals `Promise` of `coroutine`. Ik herinner mezelf altijd aan het doel. Als een bepaalde kennislageniveau voldoende is om het doel te bereiken, dan hoef ik niet dieper te graven, want ik kan altijd later terugkomen. Ondertussen is grondig begrip vereist binnen een specifieke laag. Zo kan ik verschillende situaties in de toekomst aan. De sleutel is om het evenwicht te vinden, en dat is niet gemakkelijk. Ik schrijf misschien een ander artikel over dit onderwerp in de toekomst. Gelukkig heeft Python een ingebouwde oplossing van `async` en `await`. Voordat je ze gebruikt, zorg ervoor dat de compatibiliteit met populaire frameworks gewaarborgd is. In Flask kan dit worden gedaan door de `async` extra te installeren en `async def` in plaats van `def` te gebruiken: ```python @app.route("/") async def hello_world(): # ... ``` Dan kunnen we `await` gebruiken om te wachten op het resultaat van een asynchrone operatie. ### HTTP-verzoeken HTTP-verzoeken zijn een interessant onderwerp. Bijna elke programmeertaal heeft een native oplossing, maar ontwikkelaars gebruiken meestal een derdepartijbibliotheek vanwege het gebruiksgemak. Enkele voorbeelden: - JavaScript: `XMLHttpRequest` vs. `fetch` vs. `axios` - Swift: `URLSession` vs. `Alamofire` - Java: `HttpURLConnection` vs. `OkHttp` Dit geldt ook voor Python. Mijn beslissing was om [aiohttp](https://docs.aiohttp.org/) te gebruiken omdat het `async` en `await` ondersteunt, in combinatie met zijn populariteit. ### De magische Copilot Voor Copilot zouden we nu komen tot het eentonige deel van het schrijven van businesslogica. Met behulp van de SDK-conventie en andere SDK's, kan ik de beschrijvende opmerkingen voor elke methode schrijven voordat ik de code schrijf. Het verhoogt de leesbaarheid van de code en helpt ook ontwikkelaars de API te begrijpen direct in de IDE of editor via code-intelligentie. Neem bijvoorbeeld de `generateCodeChallenge`-methode, de opmerkingen kunnen als volgt worden geschreven: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Genereren een code-uitdaging string voor de gegeven code-verifier string. Zie: https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2 """ ``` Dit stelde een geweldige prompt voor Groottaalmachines (LLMs): Methode-definities omvatten door duidelijke opmerkingen. En Copilot stelde niet teleur: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Genereren een code-uitdaging string voor de gegeven code-verifier string. Zie: 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('=', '') ``` Misschien zijn er wat aanpassingen nodig, maar dat doet er niet toe. Het heeft het spel al veranderd. Copilot blinkt uit bij het produceren van code voor eenvoudige logica. Het kan problemen tegenkomen wanneer het gaat om meerdere afhankelijkheden. Zoals de naam suggereert, is het een codeassistent, jij zou de kapitein moeten zijn die de richting bepaalt en de beslissingen neemt. ### Afronding Dat is zo'n beetje de voortgang die op de eerste dag is bereikt. Het was een lange dag, maar met moderne tools en technologieën was het veel beter dan verwacht. ## Dag 2: Verhoog de lat Gebaseerd op het werk van de eerste dag was de businesslogica snel gedaan. Maar voor een SDK is het nog steeds onvoldoende. Hier zijn de taken voor de tweede dag: - Voeg eenheidstoetsen toe. - Handhaaf code-opmaak. - Controleer Python-versiecompatibiliteit. - Voeg continue integratie toe. - Publiceer de SDK. ### Eenheidstoetsen Eenheidstoetsen hebben ons vaak gered, dus ik zal het niet overslaan. Hier zijn algemene overwegingen bij het schrijven van eenheidstoetsen: - Hoe organiseer en voer je de toetsen uit? - Hoe stel je het resultaat vast? - Hoe voer je asynchrone toetsen uit? (Het klinkt als vanzelfsprekend, maar het kan af en toe problemen opleveren in sommige talen.) - Hoe kunnen afhankelijkheden worden gemockt? (Niet in dit onderwerp duiken totdat het onmisbaar is, want het kan naar konijnenholen leiden.) - Hoe genereer je code-dekking rapporten? Met deze vragen in gedachten vond ik dat het ingebouwde `unittest`-module in sommige gevallen tekort schoot. Dus koos ik [pytest](https://docs.pytest.org/) als testframework. Het ondersteunt asynchrone toetsen en ziet er volwassen genoeg uit. De reis onthulde enkele interessante nieuwe concepten zoals `fixture` aan mij. Dit kan ook de denkwijze ten goede komen bij het schrijven van code in andere talen. Copilot is zelfs beter bij het schrijven van toetsen, het kan een veelheid van praktische toetsgevallen genereren. Zelfs als er wijzigingen nodig zijn, kan Copilot leren van de nieuwe context en toekomstige codegeneratie verbeteren. ### Code-opmaak Elke taal heeft zijn eigen code-opmaakstijlen. Persoonlijk kan consistente opmaak me gelukkig en comfortabel maken; het is ook nuttig voor codebeoordeling en samenwerking. In plaats van de discussie over de "beste" stijl te volgen, besloot ik een opinionated formatter te kiezen en eraan vast te houden. [Black](https://github.com/psf/black) lijkt een goede keuze. Het enige nadeel is de onmodificeerbare tabmaat. Maar het is geen groot probleem, ik koos ervoor om het te accommoderen. ### Python-versiecompatibiliteit Als een SDK moet het compatibel zijn met gangbare Python-versies. Door te zoeken naar "python versiegebruik statistieken", besloot ik om Python 3.8 als de minimumversie te gebruiken. De deugd van de omgevingbeheerder laat zich nu zien. Ik kan gemakkelijk de Python-versie wijzigen door `pyenv local 3.8` en `poetry env use 3.8` uit te voeren. Vervolgens kan ik de toetsen uitvoeren om compatibiliteitsproblemen aan het licht te brengen. ### Continue integratie Continue integratie garandeert de kwaliteit van elke code-aanpassing. Aangezien onze repository op GitHub was gehost, bood GitHub Actions de natuurlijke keuze. De kernworkflow volgt eenvoudige principes: - Stel de omgeving in. - Installeer afhankelijkheden. - Bouw het project (niet nodig voor Python overigens). - Voer de toetsen uit. GitHub Actions heeft een goede gemeenschap, dus het duurt slechts een paar minuten om [de workflow](https://github.com/logto-io/python/blob/9082d9afd25b6876cadad6d9cfebf40d1c43cabc/.github/workflows/main.yml) samen te stellen. Door matrixstrategieën te gebruiken, kunnen we de workflow op verschillende Python-versies uitvoeren, zelfs op verschillende besturingssystemen. ### Publiceer de SDK De laatste stap is om de SDK te publiceren. Voor publieke pakketten kan dit meestal worden gedaan door ze in te dienen bij het officiële taal specifieke pakkettenregister. Bijvoorbeeld, [npm](https://www.npmjs.com/) voor Node.js, [PyPI](https://pypi.org/) voor Python, en [CocoaPods](https://cocoapods.org/) voor Swift. Poetry is mijn richtsnoer. Voer gewoon `poetry publish` uit om het pakket naar PyPI te publiceren. Zo simpel is het. ## Afsluitende gedachten Het was een boeiende reis. Zonder de hulp van de opensource gemeenschap zou het veel moeilijker zijn geweest. Applaus voor alle bijdragers! Hier zijn enkele algemene lessen: - Definieer nauwkeurig het doel en splits het op, en houd het doel altijd in gedachten. - Stel een stabiele en reproduceerbare ontwikkelingsomgeving in. - Gebruik (goede) tools zoveel mogelijk. - Geef prioriteit aan ingebouwde of bestaande oplossingen. - Begrijp taalconventies en elke regel code die je schrijft. - Fixeer echter niet op details. - Gebruik Copilot voor duidelijke, beschrijvende taken. Je kunt het uiteindelijke resultaat vinden in [deze repository](https://github.com/logto-io/python). Met dezelfde strategie bouwde ik ook snel de [Logto PHP SDK](https://github.com/logto-io/php). Aarzel niet om ons te laten weten als je suggesties hebt. Ik hoop dat dit artikel nuttig is voor het leren van een nieuwe programmeertaal. Fijn hacken! Probeer Logto Vandaag