## Introduktion Logto, som en identitetstjänst, är det viktigt att tillhandahålla en smidig upplevelse över olika programmeringsspråk och ramverk. Detta innebär ofta att skapa Software Development Kits (SDKs). Men när programmeringsspråket ligger utanför vår teknikstack och vårt team saknar erfarenhet, blir det en utmaning att skapa ett robust SDK. Python utgjorde en sådan utmaning för oss. Trots att vi hade många Python-användare saknade vi ett Python SDK, vilket var en kvarstående oro. Besluten att adressera detta, började jag brygga denna klyfta. Även om jag har flera års programmeringserfarenhet, är Python fortfarande relativt outforskad mark för mig. Även om jag hade experimenterat med Python 2 kort för enkla skript för många år sedan, var min kunskap föråldrad. Ändå var det dags att dyka in! ## Dag 1: Lägg grunden ### Definiera målet Av erfarenhet är det mest effektiva sättet att lära sig ett nytt programmeringsspråk att bygga ett komplett projekt. Som tur var var vårt mål klart: konstruera ett Logto Python SDK för webbapplikationer. Istället för att hoppa direkt in i koden, låt oss bryta ner det. Här är listan: 1. Skapa Logto-klienten för uppgifter som inloggning, utloggning, användarinfo och tokenhantering. 2. Tillhandahålla en handledning och ett exempelprojekt som visar användningen av SDK. 3. Publicera SDK så att användare enkelt kan installera det. Det ser ut som uppgift 1 har mest arbete, så vi behöver bekräfta omfattningen och fortsätta bryta ner den. Detta steg är avgörande för att säkra projektets gräns och undvika omfattningsglidning och överingenjörer. Tidigare arbete av vårt team sparade mig massor av tid: - En [SDK-konvention](https://docs.logto.io/docs/references/sdk-convention/) beskrev strukturen och API-designen för SDK:er. - Befintliga SDK:er för olika språk gav insikter i mönster och potentiella förbättringar för Python. Genom att referera till dessa resurser kan jag se en tydlig bild av vad som behöver göras. Även om specifika detaljer går utanför denna artikels omfattning, låt oss gå vidare. ### Ställ in miljön Jag använder en Mac, så Python är redan installerad. Jag undrade dock om det finns ett bättre sätt att hantera Python-versionerna (jag har hört talas om smärtan med versionens kompatibilitet), precis som `nvm` för Node.js. Snabbt hittade jag [pyenv](https://github.com/pyenv/pyenv) och började direkt installera det. Fokusera inte på småsaker i det här skedet. Målet är att komma igång så snart som möjligt. Välj allmänt antagna verktyg och fortsätt. Ändringar kan alltid göras senare. Nästa på agendan: en paketerings- och beroendemanager. Vanligtvis är de kopplade. Så varför inte `pip` (Python-standard)? Om du tittar på `requirements.txt`, kommer du märka att det bara är en lista över paket med versioner. Detta är inte tillräckligt för ett SDK som kan användas av andra projekt. Till exempel kanske vi behöver lägga till några paket för utveckling, men vi vill inte inkludera dem i det slutliga SDK:et. `requirements.txt` är för enkelt för att hantera detta. En av fördelarna när du har andra programmeringsspråk i din teknikstack är att du kan söka efter "Python-ekvivalent". Så jag sökte efter "package.json Python-ekvivalent" och hittade [Poetry](https://python-poetry.org/), en strålande kandidat: - Det fungerar som en paketmanager, beroendehanterare och hanterare för virtuella miljöer. - Den har en `pyproject.toml`-fil, liknande `package.json` i Node.js. - Den använder en låsfil för att registrera exakta beroendeversioner. Moderna CLI:er omfattar ofta ett `init`-kommando som är anpassat för nya projekt. Poetry gör det också. Jag körde kommandot och det skapade en `pyproject.toml`-fil åt mig. ### Den första raden kod Äntligen hade ögonblicket att skriva kod anlänt. Att börja med det klassiska "Hello, World!"-programmet är alltid ett bra val. När man lär sig ett programmeringsspråk är fullfjädrade IDE:er inte alltid nödvändiga; en redaktör backad av en stark gemenskap, såsom VS Code, är helt tillräcklig. Med tanke på vårt SDK:s fokus på webbapplikationer började jag med en enkel webbserver som använde det populära ramverket Flask. Genom att utnyttja Poetries kapabiliteter kan Flask enkelt installeras genom att köra `poetry add flask`. Sedan, enligt Flasks officiella snabbstartsguide, komponerade jag en 'hello.py'-fil med följande kodbit: ```python from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return "

Hello, World!

" ``` Att starta servern via `flask --app hello run` och navigera till http://localhost:5000 på min webbläsare resulterade i det önskade resultatet. Det fungerade! Metodologin för att välja Flask och ytterligare paket speglar det tillvägagångssätt som antogs för pyenv och Poetry. Med tanke på dess repetitiva karaktär, utelämnas dessa specifika delar i följande avsnitt. Som nybörjare var jag inte snabb att skriva mer kod. Istället finns det mycket information att ta emot från kodbiten: - Använd `from x import y` för att importera en modul eller en klass. - Inga semikolon för att avsluta rader (oj då). - Vi kan definiera en ny variabel genom att ange ett godtyckligt namn och tilldela ett värde till det. - Skapa en instans av en klass utan `new`-nyckelordet. - Python stöder dekorerare, och `@app.route` fungerar som en dekorerare som registrerar en funktion som en routhanterare. - Funktionens returvärde tolkas som svarskropp. - Vi kan definiera en funktion genom att använda `def`-nyckelord. Som du kan se, om vi försöker förstå varje rad kod istället för att "bara få det att fungera", kan vi lära oss mycket av det. Samtidigt förklarade Flasks officiella dokument ytterligare kodbiten i detalj. Min tillgo är att först läsa den officiella dokumentationen innan jag söker efter andra resurser. Vanligtvis är det det mest effektiva sättet att lära sig något nytt. ### Projektstart Nu är det dags att starta projektet. Snart definierade jag en `LogtoClient`-klass och försökte lägga till några egenskaper och metoder för att känna språket: ```python class LogtoClient: def __init__(self, config = 'config'): self.config = config def signIn(self): return 'signIn' + self.config ``` Därefter integrera klassen med Flask: ```python from logto import LogtoClient client = LogtoClient() @app.route("/") def hello_world(): return client.signIn() ``` Det började kännas som ett riktigt projekt. Men jag kände att något saknades: ett typeringssystem. ### Typeringssystem Eftersom det är ett SDK, kommer det att hjälpa användarna att förstå API:et och minska risken för fel vid utveckling genom att inkorporera ett typeringssystem. Python introducerade [typhintar](https://docs.python.org/3/library/typing.html) i version 3.5. Det är inte lika kraftfullt som TypeScript, men det är bättre än ingenting. Jag la till några typhintar till `LogtoClient`-klassen: ```python from typing import Optional class LogtoClient: def __init__(self): self.config: str | None = 'config' def signIn(self) -> str: return 'signIn' + self.config ``` Ser mycket bättre ut nu. Men utmaningen dök upp när det kommer till en komplex typ som ett objekt med fördefinierade nycklar. Till exempel, vi måste definiera en `LogtoConfig`-klass för att representera konfigurationsobjektet: ```python class LogtoConfig: def __init__(self, clientId: str, clientSecret: str): self.clientId = clientId self.clientSecret = clientSecret # ... ``` Det ser okej ut, men snart måste vi möta problemen med att koda, dekoda och validera objektet från JSON. Prioritera alltid inbyggda lösningar. Om de verkligen inte fungerar, utforska tredje part-bibliotek. Endast när alla andra alternativ misslyckas, överväg att skapa din egen lösning. Efter lite forskning valde jag [pydantic](https://pydantic-docs.helpmanual.io/) som lösning. Det är ett datavalideringsbibliotek som fungerar med typhintar. Det stödjer olika JSON-funktioner utan att följa tråkig boilerplate-kod. Därför kan `LogtoConfig`-klassen skrivas om som: ```python from pydantic import BaseModel class LogtoConfig(BaseModel): clientId: str clientSecret: str # ... ``` Det lärde mig också om klassarv i Python genom att lägga till parenteser efter klassnamnet. ### Asynkrona operationer Inom Logto SDK, behöver vi göra HTTP-förfrågningar till Logto-servern. Om du har erfarenhet av JavaScript, klingar termen "callback hell" troligen bekant. Det är ett vanligt problem när man hanterar asynkrona operationer. Moderna programmeringsspråk presenterar liknande lösningar som `Promise` eller `coroutine`. Jag påminner alltid mig själv om målet. Om ett visst kunskapslager är nog för att uppnå målet, behöver jag inte gräva djupare eftersom jag alltid kan återvända senare. Samtidigt krävs grundlig förståelse inom ett specifikt lager. Så kan jag hantera olika situationer i framtiden. Nyckeln är att hitta balansen, och det är inte lätt. Jag kan skriva en annan artikel om detta ämne i framtiden. Lyckligtvis har Python en inbyggd lösning av `async` och `await`. Innan du använder dem, säkerställ kompatibiliteten med populära ramverk. I Flask kan detta göras genom att installera `async`-extra och använda `async def` istället för `def`: ```python @app.route("/") async def hello_world(): # ... ``` Då kan vi använda `await` för att vänta på resultatet av en asynkron operation. ### HTTP-förfrågningar HTTP-förfrågningar är ett intressant ämne. Nästan varje programmeringsspråk har en inhemsk lösning, men utvecklare använder vanligtvis ett tredjeparts-bibliotek eftersom det är lättare att använda. Några exempel: - JavaScript: `XMLHttpRequest` vs. `fetch` vs. `axios` - Swift: `URLSession` vs. `Alamofire` - Java: `HttpURLConnection` vs. `OkHttp` Detta är också sant för Python. Mitt beslut var att använda [aiohttp](https://docs.aiohttp.org/) eftersom det stöder `async` och `await` samt dess popularitet. ### Copilot-magin Tidigare än Copilot, skulle vi nu komma till den tråkiga delen av att skriva affärslogik. Med hjälp av SDK-konventionen och andra SDK:er kunde jag skriva de beskrivande kommentarerna för varje metod innan jag skrev koden. Det ökar kodens läsbarhet och hjälper utvecklare att förstå API:et direkt i IDE eller redaktör via kodintelligens. Till exempel, överväg `generateCodeChallenge`-metoden, kommentarerna kan skrivas som: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Generera en kodutmaningsträng för den givna kodverifierarssträngen. Se: https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2 """ ``` Detta utgjorde ett bra prompt för stora språksmodeller (LLMs): sammansättning av metoddefinitioner genom tydliga kommentarer. Och Copilot gjorde inte besviken: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Generera en kodutmaningsträng för den givna kodverifierarssträngen. Se: 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('=', '') ``` Några justeringar kan behövas, men det spelar ingen roll. Det har redan förändrat spelet. Copilot lyser när det producerar kod för enkel logik. Däremot kan det behöva kämpa när det involverar flera beroenden. Som namnet antyder är det en kodassistent, du borde vara kaptenen som styr riktningen och tar besluten. ### Avrundning Det är ungefär framstegen som uppnåddes under den första dagen. Det var en lång dag, men med moderna verktyg och teknologier var det mycket bättre än jag förväntat mig. ## Dag 2: Höj ribban Baserat på arbetet den första dagen blev affärslogiken snabbt färdig. Men för ett SDK är det fortfarande otillräckligt. Här är uppgifterna för den andra dagen: - Lägg till enhetstester. - Tvinga fram kodformatering. - Verifiera kompatibilitet med Python-version. - Lägg till kontinuerlig integration. - Publicera SDK. ### Enhetstester Enhetstester har räddat oss många gånger, så jag kommer inte att hoppa över det. Här är vanliga överväganden när man skriver enhetstester: - Hur organiserar och kör man testerna? - Hur bekräftar man resultatet? - Hur kör man asynkrona tester? (Det låter självklart men det kan ibland orsaka problem i vissa språk.) - Hur mockar man beroenden? (Dyk inte in i detta ämne förrän det är oumbärligt, eftersom det kan leda in i en kaninhål.) - Hur genererar man kodtäckningsrapporter? Med dessa frågor i åtanke fann jag att det inbyggda `unittest`-modulen inte räckte för vissa fall. Så jag valde [pytest](https://docs.pytest.org/) som testramverk. Det stöder asynkrona tester och ser tillräckligt moget ut. Resan avslöjade några intressanta nya koncept som `fixture` för mig. Detta kan också gynna tankesättet när man skriver kod i andra språk. Copilot är ännu bättre när det gäller att skriva tester, det kan generera en mängd praktiska testfall. Även när justeringar behövs, kan Copilot lära sig från det nya sammanhanget och förbättra framtida kodgenerering. ### Kodformatering Varje språk har sina egna kodformateringsstilar. Personligen kan konsekvent formatering göra mig glad och bekväm; det är också hjälpsamt för kodgranskning och samarbete. Istället för att bläddra i argumentet för den "bästa" stilen, bestämde jag mig för att välja en bestämd formatterare och hålla mig till den. [Black](https://github.com/psf/black) ser ut som ett bra val. Den enda frustrationen är den omodifierbara flikstorleken, men det är inget stort problem, jag valde att anpassa mig till det. ### Python versionskompatibilitet Som ett SDK bör det vara kompatibelt med rådande Python-versioner. Genom att söka efter "python version usage statistics", bestämde jag att använda Python 3.8 som minsta version. Fördelarna med miljöhanterare visar sig nu. Jag kan enkelt växla Python-versionen genom att köra `pyenv local 3.8` och `poetry env use 3.8`. Då kunde jag köra testerna för att avslöja kompatibilitetsproblem. ### Kontinuerlig integration Kontinuerlig integration garanterar kvaliteten på varje kodändring. Eftersom vårt arkiv fanns på GitHub presenterade GitHub Actions det naturliga valet. Kärnworkflowen följer enkla principer: - Ställ in miljön. - Installera beroenden. - Bygg projektet (Inte nödvändigt för Python dock). - Kör testerna. GitHub Actions har ett bra community, så det tar bara några minuter att konstruera [workflowen](https://github.com/logto-io/python/blob/9082d9afd25b6876cadad6d9cfebf40d1c43cabc/.github/workflows/main.yml). Genom att använda matrisstrategier kan vi köra workflowen på olika Python versioner, även på olika operativsystem. ### Publicera SDK Det sista steget är att publicera SDK. För offentliga paket kan detta vanligtvis göras genom att skicka till det officiella språksspecifika pakethanteringsregistret. Till exempel, [npm](https://www.npmjs.com/) för Node.js, [PyPI](https://pypi.org/) för Python, och [CocoaPods](https://cocoapods.org/) för Swift. Poetry är min ledstjärna. Kör bara `poetry publish` för att publicera paketet till PyPI. Det är så enkelt. ## Avslutande tankar Det var en engagerande resa. Utan hjälp från öppen källkodscommunity hade det varit mycket svårare. Beröm till alla bidragsgivare! Här är några allmänna lärdomar: - Definiera målet exakt och bryt ner det, håll sedan alltid målet i åtanke. - Sätt upp en stabil och reproducerbar utvecklingsmiljö. - Använd (bra) verktyg så mycket som möjligt. - Prioritera inbyggda eller befintliga lösningar. - Förstå språkets konventioner och varje kodrad du skriver. - Men fokusera inte på småsaker. - Använd Copilot för tydliga, beskrivande uppgifter. Du kan hitta det slutgiltiga resultatet i [detta arkiv](https://github.com/logto-io/python). Med samma strategi byggde jag också snabbt [Logto PHP SDK](https://github.com/logto-io/php). Tveka inte att låta oss veta om du har några förslag. Hoppas den här artikeln är hjälpsam för att lära sig ett nytt programmeringsspråk. Lycka till med hackandet! Prova Logto idag