## Johdanto Logto, identiteettipalveluna, sujuvan kokemuksen tarjoaminen eri ohjelmointikielillä ja -kehyksillä on olennaista. Tämä sisältää usein Ohjelmistokehityspakettien (SDK) luomisen. Kuitenkin, kun ohjelmointikieli ei ole osa teknistä pinoamme ja tiimillämme ei ole siitä kokemusta, vankan SDK:n luomisesta tulee haaste. Python oli tällainen haaste meille. Huolimatta monista Python-käyttäjistä, meiltä puuttui Python SDK, mikä oli jatkuva huolenaihe. Päättäen ratkaista tämän, aloitin kuilun kaventamisen. Vaikka minulla on vuosien kokemus ohjelmoinnista, Python on minulle suhteellisen tutkimaton alue. Vaikka olin kokeillut Python 2:ta lyhyesti yksinkertaisiin skripteihin vuosia sitten, tietoni olivat vanhentuneita. Oli kuitenkin aika sukeltaa sisään! ## Päivä 1: Perustan luominen ### Määrittele tavoite Kokemukseni mukaan tehokkain tapa oppia uusi ohjelmointikieli on rakentaa kokonainen projekti. Onneksi tavoitteemme oli selkeä: rakentaa Logton Python SDK verkkosovelluksille. Ennen kuin hyppäämme koodiin, hajottakaamme se. Tässä lista: 1. Luo Logto-asiakas tehtäville kuten sisäänkirjautuminen, uloskirjautuminen, käyttäjätiedot ja tokenin hallinta. 2. Tarjoa opastus ja esimerkkiprojekti, joka näyttää SDK:n käytön. 3. Julkaise SDK jonnekin, jotta käyttäjät voivat asentaa sen helposti. Näyttää siltä, että tehtävä 1 sisältää eniten työtä, joten meidän on vahvistettava laajuus ja jatkettava sen pilkkomista. Tämä askel on ratkaiseva projektin rajojen turvaamiseksi sekä laajenemisen ja ylisuunnittelun välttämiseksi. Tiimimme aiempi työ säästi minulta valtavasti aikaa: - [SDK-konventio](https://docs.logto.io/docs/references/sdk-convention/) kuvaili SDK:iden rakennetta ja rajapintasuunnittelua. - Eri kielille tarkoitetut olemassa olevat SDK:t tarjosivat näkemyksiä malleista ja mahdollisista parannuksista Pythonia varten. Näihin resursseihin viitaten voin nähdä selkeän kuvan tehtävistä. Vaikka yksityiskohdat ovat tämän artikkelin ulkopuolella, siirrytään eteenpäin. ### Ympäristön asennus Käytän Macia, joten Python on jo asennettu. Kuitenkin mietin, olisiko parempi tapa hallita Python-versioita (olen kuullut version yhteensopivuuden ongelmista), aivan kuten `nvm` Node.js:lle. Nopeasti löysin [pyenv](https://github.com/pyenv/pyenv) ja aloitin sen asentamisen heti. Älä takerru yksityiskohtiin tässä vaiheessa. Tavoite on päästä alkuun mahdollisimman pian. Valitse laajasti käytettyjä työkaluja ja etene. Muutoksia voi aina tehdä myöhemmin. Seuraavaksi ohjelmassa: paketti- ja riippuvuudenhallinta. Yleensä ne ovat yhdistetty. Joten miksi ei "pip" (Pythonin oletus)? Jos katsot `requirements.txt`, huomaat, että se on vain lista paketeista ja niiden versioista. Tämä ei riitä SDK:lle, jota muut projektit voivat käyttää. Esimerkiksi saatamme joutua lisäämään paketteja kehitystä varten, mutta emme halua sisällyttää niitä lopulliseen SDK:han. `requirements.txt` on liian yksinkertainen tämän käsittelemiseksi. Yksi hyöty muista ohjelmointikielistä teknologiapinossasi on, että voit etsiä "Pythonin vastaavaa". Joten etsin "package.json Python vastine" ja löysin [Poetryn](https://python-poetry.org/), loistavan ehdokkaan: - Se toimii paketti-, riippuvuuden- ja virtuaalisen ympäristön hallitsijana. - Sillä on `pyproject.toml`-tiedosto, joka on kuin `package.json` Node.js:ssä. - Se käyttää lukitutiedostoa kirjatakseen tarkat riippuvuusversiot. Nykyaikaisissa CLI-työkaluissa on usein `init`-komento uusille projekteille. Niin myös Poetryssä. Annoin komennon ja se loi `pyproject.toml`-tiedoston minulle. ### Ensimmäinen koodirivi Viimeinkin, hetki kirjoittaa koodia oli saapunut. Aloitus klassisella "Hello, World!" -ohjelmalla on aina hyvä valinta. Kun opitaan ohjelmointikieltä, täysimittaista IDE:tä ei aina tarvita; editori, jolla on vahva yhteisö, kuten VS Code, on täysin riittävä. Koska SDK:mme keskittyy verkkosovelluksiin, aloitin yksinkertaisella verkkopalvelimella käyttäen suosittua Flask-kehystä. Hyödyntäen Poetryn kykyjä, Flaskin asentaminen voidaan helposti tehdä suorittamalla `poetry add flask`. Sitten, seuraten Flaskin virallista pikasoitto-opasta, koostin 'hello.py' -tiedoston seuraavalla katkelmalla: ```python from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return "

Hello, World!

" ``` Palvelimen käynnistäminen komennolla `flask --app hello run` ja navigointi osoitteeseen http://localhost:5000 selaimellani tuotti halutun lopputuloksen. Se toimi! Metodologia Flaskin ja lisäpakettien valitsemiseksi heijastaa pyenv:n ja Poetryn valintatapaan. Ottaen huomioon sen toistuvan luonteen, nämä erityispiirteet jätetään pois seuraavista osioista. Aloittelijana en kiirehtinyt kirjoittamaan lisää koodia. Sen sijaan on paljon tietoa saatavilla koodikatkelmasta: - Käytä `from x import y` tuodaksesi moduuli tai luokka. - Ei puolipistettä rivien lopettamiseen (voi ei). - Voimme määritellä uusi muuttuja syöttämällä satunnainen nimi ja antaa sille arvo. - Luokan instanssin luominen ilman `new`-avainsanaa. - Python tukee koristeita, ja `@app.route` toimii koristeena, joka rekisteröi funktion reitin käsittelijäksi. - Funktion palautusarvo tulkitaan vasteen runkoksi. - Voimme määritellä funktion käyttämällä `def`-avainsanaa. Kuten näette, jos yritämme ymmärtää jokaista koodiriviä "sen toimimiseksi tekemisen sijaan", voimme oppia siitä paljon. Samaan aikaan Flaskin virallinen dokumentaatio selitti katkelman yksityiskohtaisesti. Suosikkistrategiani on lukea ensin virallinen dokumentaatio, ennen kuin etsin muita resursseja. Yleensä se on tehokkain tapa oppia jotakin uutta. ### Projektin käynnistys Nyt on aika aloittaa projekti. Pian määrittelin `LogtoClient`-luokan ja yritin lisätä joitakin ominaisuuksia ja menetelmiä tunteakseni kielen: ```python class LogtoClient: def __init__(self, config = 'config'): self.config = config def signIn(self): return 'signIn' + self.config ``` Seuraavaksi yhdistä luokka Flaskin kanssa: ```python from logto import LogtoClient client = LogtoClient() @app.route("/") def hello_world(): return client.signIn() ``` Se alkoi tuntua todelliselta projektilta. Mutta tuntui, että jotain puuttui: tyyppijärjestelmä. ### Tyyppijärjestelmä Koska kyseessä on SDK, tyyppijärjestelmän lisääminen auttaa käyttäjiä ymmärtämään API:a ja vähentää virheiden mahdollisuutta kehityksen aikana. Python esitteli [tyyppivihjeet](https://docs.python.org/3/library/typing.html) versiossa 3.5. Se ei ole yhtä tehokas kuin TypeScript, mutta parempi kuin ei mitään. Lisäsin joitakin tyyppivihjeitä `LogtoClient`-luokkaan: ```python from typing import Optional class LogtoClient: def __init__(self): self.config: str | None = 'config' def signIn(self) -> str: return 'signIn' + self.config ``` Näyttää paljon paremmalta nyt. Mutta haaste syntyy, kun kyseessä on monimutkainen tyyppi, kuten objekti ennalta määritetyin avainparin. Esimerkiksi, meidän on määriteltävä `LogtoConfig`-luokka edustamaan config-objektia: ```python class LogtoConfig: def __init__(self, clientId: str, clientSecret: str): self.clientId = clientId self.clientSecret = clientSecret # ... ``` Se näyttää hyvältä, mutta pian kohtaamme ongelmia objektin koodaamisessa, dekoodaamisessa ja validoinnissa JSON:ista. Aina priorisoi sisäänrakennetut ratkaisut. Jos ne todella eivät toimi, tutki sitten kolmannen osapuolen kirjastoja. Vasta kun kaikki vaihtoehdot pettävät, harkitse oman ratkaisun luomista. Jonkin tutkimuksen jälkeen valitsin [pydantic](https://pydantic-docs.helpmanual.io/) ratkaisuksi. Se on datavalidointikirjasto, joka toimii tyyppivihjeiden kanssa. Se tukee monipuolisia JSON-toimintoja ilman hankalaa boilerplate-koodia. Näin `LogtoConfig`-luokan voi kirjoittaa uudelleen: ```python from pydantic import BaseModel class LogtoConfig(BaseModel): clientId: str clientSecret: str # ... ``` Se opetti minulle myös luokan perinnöstä Pythonissa lisäämällä sulkuja luokan nimen jälkeen. ### Asynkroniset toiminnot Logto SDK:ssa tarvitsemme HTTP-pyyntöjen tekemistä Logto-palvelimelle. Jos sinulla on kokemusta JavaScriptistä, termi "callback hell" voi soida kelloa. Se on yleinen ongelma asynkronisten toimintojen käsittelyssä. Nykyaikaiset ohjelmointikielet tarjoavat samanlaisia ratkaisuja kuten `Promise` tai `coroutine`. Muistutan aina itseäni tavoitteesta. Jos tietty tietotaso riittää tavoitteen saavuttamiseen, en tarvitse kaivaa syvemmälle, koska voin aina palata myöhemmin. Samaan aikaan perusteellinen ymmärrys vaaditaan tietyssä kerroksessa. Näin voin käsitellä erilaisia tilanteita tulevaisuudessa. Avain on löytää tasapaino, eikä se ole helppoa. Saatan kirjoittaa toisen artikkelin tästä aiheesta tulevaisuudessa. Onneksi Pythonilla on sisäänrakennettu ratkaisu `async` ja `await`. Ennen niiden käyttämistä varmista yhteensopivuus suosittujen kehysten kanssa. Flaskissa tämä voidaan tehdä asentamalla `async` extra ja käyttämällä `async def` ha:` ```python @app.route("/") async def hello_world(): # ... ``` Sitten voimme käyttää `await` odottamaan asynkronisen operaation tulosta. ### HTTP-pyynnöt HTTP-pyynnöt ovat mielenkiintoinen aihe. Melkein jokaisella ohjelmointikielellä on natiivi ratkaisu, mutta kehittäjät yleensä käyttävät kolmannen osapuolen kirjastoa helppokäyttöisyyden vuoksi. Joitakin esimerkkejä: - JavaScript: `XMLHttpRequest` vs. `fetch` vs. `axios` - Swift: `URLSession` vs. `Alamofire` - Java: `HttpURLConnection` vs. `OkHttp` Tämä pätee myös Pythonille. Päätökseni oli käyttää [aiohttp](https://docs.aiohttp.org/), koska se tukee `async` ja `await`, yhdessä sen suosion kanssa. ### Copilot-taika Ennen Copilotia, meidän olisi nyt tultava liiketoimintaloogisuuden kirjoittamisen yksityiskohtiin. SDK-konvention ja muiden SDK:iden avulla voin kirjoittaa kuvaavat kommentit kaikille menetelmille ennen koodin kirjoittamista. Se lisää koodin selkeyttä ja auttaa kehittäjiä ymmärtämään API:a suoraan IDE:ssä tai editorissa koodiälyn avulla. Esimerkiksi, ajattele `generateCodeChallenge`-menetelmää, kommentit voidaan kirjoittaa: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Generoi koodin haaste merkkijono annettuun koodin varmennusmerkkijonoon. Katso: https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2 """ ``` Tämä tarjosi loistavan kehotuksen Suurille Kielimalleille (LLM): muodostaa menetelmämääritykset selkeillä kommenteilla. Ja Copilot ei pettänyt: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Generoi koodin haaste merkkijono annettuun koodin varmennusmerkkijonoon. Katso: 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('=', '') ``` Jotkut hienosäädöt saattavat olla tarpeen, mutta se ei haittaa. Se on jo muuttanut peliä. Copilot loistaa tuottaessaan koodia suoraviivaiselle logiikalle. Kuitenkin se saattaa kamppailla, kun mukana on useita riippuvuuksia. Kuten nimi vihjaa, se on koodiassistentti, sinun pitäisi olla kapteeni, joka ohjaa suuntaa ja tekee päätöksiä. ### Yhteenveto Tämä on melkein kaikki ensimmäisen päivän saavutetut edistysaskeleet. Se oli pitkä päivä, mutta nykyaikaisilla työkaluilla ja teknologioilla se oli paljon parempaa kuin odotin. ## Päivä 2: Riman nostaminen Ensimmäisen päivän työn perusteella liiketoimintaloogisuus tehtiin nopeasti. Mutta SDK:lle se on edelleen riittämätöntä. Tässä toisen päivän tehtävät: - Lisää yksikkötestit. - Varmista koodin muotoilu. - Tarkista Python-version yhteensopivuus. - Lisää jatkuva integrointi. - Julkaise SDK. ### Yksikkötestit Yksikkötestit pelastivat meidät monta kertaa, joten en jätä sitä väliin. Tässä tavallisia huomioita yksikkötestejä kirjoitettaessa: - Kuinka järjestää ja ajaa testit? - Kuinka todeta tulos? - Kuinka ajaa asynkroniset testit? (Se kuulostaa itsestäänselvyydeltä, mutta se satunnaisesti aiheuttaa ongelmia joissain kielissä.) - Kuinka mallintaa riippuvuudet? (Älä sukeltaa tähän aiheeseen, ellet se ole välttämätöntä, koska se voi johtaa kanin koloihin.) - Kuinka luoda koodikattavuusraportteja? Näiden kysymysten kanssa huomasin, että sisäänrakennettu `unittest`-moduuli jäi puutteelliseksi joissain tapauksissa. Joten valitsin [pytest](https://docs.pytest.org/) testikehykseksi. Se tukee asynkronisia testejä ja vaikuttaa tarpeeksi kypsältä. Matka paljasti joitain mielenkiintoisia uusia konsepteja kuten `fixture` minulle. Tämä voi myös hyödyttää ajattelutapaa koodia kirjoitettaessa muilla kielillä. Copilot on vielä parempi testejä kirjoitettaessa, se voi tuottaa useita käytännön testitapauksia. Vaikka hienosäädöt olisivat tarpeen, Copilot voi oppia uudesta kontekstista ja parantaa tulevaa koodin tuottamista. ### Koodin muotoilu Jokaisella kielellä on oma koodin muotoilutyyli. Henkilökohtaisesti, johdonmukainen muotoilu voi tehdä minut onnelliseksi ja mukavaksi; se on myös hyödyllistä koodikatselmoinnissa ja yhteistyössä. Sen sijaan, että selaisin "parhaan" tyylin argumenttia, päätin valita mielipidejohtaisen muotoilijan ja pysyä siinä. [Black](https://github.com/psf/black) vaikuttaa hyvältä valinnalta. Ainoa turhautuminen on muuttumattomien välilehtikoon kanssa. Mutta se ei ole iso juttu, päätin sopeutua siihen. ### Python version yhteensopivuus SDK:nä sen pitäisi olla yhteensopiva vallitsevien Python-versioiden kanssa. Etsimällä "python version käyttötilastot", päätin käyttää Python 3.8: ää vähimmäisversiona. Ympäristöhallinnan hyvyys nyt näyttää. Voin helposti vaihtaa Python-versiota suorittamalla `pyenv local 3.8` ja `poetry env use 3.8`. Voin sitten ajaa testit paljastaakseni yhteensopivuusongelmat. ### Jatkuva integrointi Jatkuva integrointi takaa jokaisen koodimuutoksen laadun. Koska repositorioamme isännöitiin GitHubissa, GitHub Actions tarjosi luonnollisen valinnan. Ydin työnkulkua seuraa yksinkertaisia periaatteet: - Asenna ympäristö. - Asenna riippuvuudet. - Rakenna projekti (ei kuitenkaan tarvita Pythonille). - Suorita testit. GitHub Actionsilla on hyvä yhteisö, joten kestää vain muutamia minuutteja rakentaa [prosessin](https://github.com/logto-io/python/blob/9082d9afd25b6876cadad6d9cfebf40d1c43cabc/.github/workflows/main.yml). Käyttämällä matriisistrategioita, voimme ajaa työnkulun eri Python-versioilla, jopa eri käyttöjärjestelmissä. ### SDK:n julkaisu Viimeinen vaihe on SDK:n julkaisu. Julkisille paketeille tämä voidaan tyypillisesti tehdä lähettämällä viralliseen kielikohtaiseen pakettirekisteriin. Esimerkiksi [npm](https://www.npmjs.com/) Node.js:lle, [PyPI](https://pypi.org/) Pythonille, ja [CocoaPods](https://cocoapods.org/) Swiftille. Poetry on ohjaava tähteni. Suorita vain `poetry publish` julkaistaksesi paketti PyPI:lle. Se on niin yksinkertaista. ## Loppupäätelmät Se oli kiehtova matka. Ilman avoimen lähdekoodin yhteisön apua se olisi ollut paljon vaikeampaa. Suosio kaikille osallistujille! Tässä on joitain yleisiä oppeja: - Määrittele tarkasti tavoite ja pilko se, pidä sitten aina tavoite mielessä. - Aseta vakaa ja toistettavissa oleva kehitysympäristö. - Käytä (hyviä) työkaluja mahdollisimman paljon. - Priorisoi sisäänrakennetut tai olemassa olevat ratkaisut. - Ymmärrä kielen konventiot ja jokainen koodirivi, jonka kirjoitat. - Kuitenkaan älä takerru yksityiskohtiin. - Käytä Copilotia selkeisiin, kuvainnollisiin tehtäviin. Löydät lopullisen tuloksen [tästä repositoriosta](https://github.com/logto-io/python). Saman strategian avulla rakensin nopeasti myös [Logto PHP SDK:n](https://github.com/logto-io/php). Älä epäröi kertoa meille, jos sinulla on ehdotuksia. Toivottavasti tämä artikkeli auttaa uuden ohjelmointikielen oppimisessa. Iloista hakkerointia! Kokeile Logtoa Tänään