Opettele Python viikonlopun aikana: Nollasta valmiiseen projektiin

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 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 ja aloitin sen asentamisen heti.

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, 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:

Palvelimen käynnistäminen komennolla flask --app hello run ja navigointi osoitteeseen http://localhost:5000 selaimellani tuotti halutun lopputuloksen. Se toimi!

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.

Projektin käynnistys#

Nyt on aika aloittaa projekti. Pian määrittelin LogtoClient-luokan ja yritin lisätä joitakin ominaisuuksia ja menetelmiä tunteakseni kielen:

Seuraavaksi yhdistä luokka Flaskin kanssa:

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 versiossa 3.5. Se ei ole yhtä tehokas kuin TypeScript, mutta parempi kuin ei mitään. Lisäsin joitakin tyyppivihjeitä LogtoClient-luokkaan:

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:

Se näyttää hyvältä, mutta pian kohtaamme ongelmia objektin koodaamisessa, dekoodaamisessa ja validoinnissa JSON:ista.

Jonkin tutkimuksen jälkeen valitsin pydantic ratkaisuksi. Se on datavalidointikirjasto, joka toimii tyyppivihjeiden kanssa. Se tukee monipuolisia JSON-toimintoja ilman hankalaa boilerplate-koodia.

Näin LogtoConfig-luokan voi kirjoittaa uudelleen:

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.

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:`

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, 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:

Tämä tarjosi loistavan kehotuksen Suurille Kielimalleille (LLM): muodostaa menetelmämääritykset selkeillä kommenteilla. Ja Copilot ei pettänyt:

Jotkut hienosäädöt saattavat olla tarpeen, mutta se ei haittaa. Se on jo muuttanut peliä.

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 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ä.

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 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.

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 Node.js:lle, PyPI Pythonille, ja CocoaPods 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. Saman strategian avulla rakensin nopeasti myös Logto PHP SDK:n. Älä epäröi kertoa meille, jos sinulla on ehdotuksia.

Toivottavasti tämä artikkeli auttaa uuden ohjelmointikielen oppimisessa. Iloista hakkerointia!