## Einführung Logto, als Identitätsdienst, sorgt für ein reibungsloses Erlebnis in verschiedenen Programmiersprachen und Frameworks. Dies beinhaltet oft die Erstellung von Software Development Kits (SDKs). Wenn die Programmiersprache jedoch außerhalb unseres Tech-Stacks liegt und unserem Team die Vertrautheit fehlt, wird es zu einer Herausforderung, ein robustes SDK zu erstellen. Python stellte uns eine solche Herausforderung. Trotz zahlreicher Python-Nutzer fehlte uns ein Python SDK, was eine beständige Sorge darstellte. Entschlossen, dies anzugehen, begann ich, diese Lücke zu überbrücken. Obwohl ich jahrelange Programmiererfahrung habe, bleibt Python für mich relativ unerschlossenes Terrain. Während ich vor Jahren kurzzeitig mit Python 2 für einfache Skripte experimentierte, war mein Wissen veraltet. Trotzdem war es an der Zeit, sich hineinzustürzen! ## Tag 1: Grundlage legen ### Ziel definieren Meiner Erfahrung nach ist der effektivste Ansatz, eine neue Programmiersprache zu lernen, ein vollständiges Projekt zu bauen. Zum Glück war unser Ziel klar: Ein Logto Python SDK für Webanwendungen zu erstellen. Anstatt direkt in den Code zu springen, lass uns das Ganze aufschlüsseln. Hier ist die Liste: 1. Erstellen des Logto-Clients für Aufgaben wie Anmelden, Abmelden, Benutzerinformationen und Token-Management. 2. Bereitstellung eines Tutorials und eines Beispielprojekts, um die Nutzung des SDKs zu demonstrieren. 3. Veröffentlichung des SDKs irgendwo, damit die Benutzer es einfach installieren können. Es sieht so aus, als ob Aufgabe 1 die meiste Arbeit erfordert, daher müssen wir den Umfang bestätigen und weiter aufschlüsseln. Dieser Schritt ist entscheidend, um den Projektrahmen zu sichern und Umfangserweiterungen und Überengineering zu vermeiden. Vorherige Arbeiten unseres Teams haben mir eine Menge Zeit gespart: - Eine [SDK-Konvention](https://docs.logto.io/docs/references/sdk-convention/) skizzierte die Struktur und das API-Design von SDKs. - Bestehende SDKs für verschiedene Sprachen lieferten Einblicke in Muster und potenzielle Verbesserungen für Python. Anhand dieser Ressourcen kann ich ein klares Bild dessen sehen, was zu tun ist. Während die Details über den Rahmen dieses Artikels hinausgehen, machen wir jetzt weiter. ### Die Umgebung einrichten Ich benutze einen Mac, daher ist Python bereits installiert. Allerdings habe ich mich gefragt, ob es eine bessere Möglichkeit gibt, die Python-Versionen zu verwalten (ich habe von den Schmerzen der Versionskompatibilität gehört), genau wie `nvm` für Node.js. Schnell fand ich [pyenv](https://github.com/pyenv/pyenv) und begann direkt mit der Installation. Fixiere dich in dieser Phase nicht auf Details. Das Ziel ist es, so schnell wie möglich zu beginnen. Entscheide dich für weit verbreitete Tools und mache Fortschritte. Änderungen können später immer noch vorgenommen werden. Als nächstes auf der Tagesordnung: ein Paket- und Abhängigkeitsmanager. Normalerweise sind sie gekoppelt. Warum dann nicht `pip` (das Python-Standardtool)? Wenn du dir die `requirements.txt` ansiehst, wirst du feststellen, dass es sich nur um eine Liste von Paketen mit Versionen handelt. Das reicht für ein SDK, das möglicherweise von anderen Projekten verwendet wird, nicht aus. Zum Beispiel müssen wir möglicherweise einige Pakete für die Entwicklung hinzufügen, aber wir möchten sie nicht im endgültigen SDK enthalten. Die `requirements.txt` ist zu einfach, um dies zu handhaben. Einer der Vorteile, wenn du andere Programmiersprachen in deinem Tech-Stack hast, ist, dass du nach dem "Python-Äquivalent" suchen kannst. Also suchte ich nach "package.json Python-Äquivalent" und fand [Poetry](https://python-poetry.org/), einen großartigen Kandidaten: - Es fungiert als Paketmanager, Abhängigkeitsmanager und als virtueller Umgebungsmanager. - Es hat eine `pyproject.toml`-Datei, ähnlich wie `package.json` in Node.js. - Es verwendet eine Sperrdatei, um genaue Abhängigkeitsversionen zu protokollieren. Moderne CLIs umfassen oft einen `init`-Befehl, der speziell für neue Projekte entwickelt wurde. So auch Poetry. Ich führte den Befehl aus und er erstellte eine `pyproject.toml`-Datei für mich. ### Die erste Codezeile Endlich war der Moment gekommen, Code zu schreiben. Mit dem klassischen "Hello, World!" Programm zu beginnen, ist immer eine gute Wahl. Beim Erlernen einer Programmiersprache sind voll ausgestattete IDEs nicht immer erforderlich; ein von einer starken Community unterstützter Editor wie VS Code ist völlig ausreichend. Da sich unser SDK auf Webanwendungen konzentriert, begann ich mit einem einfachen Webserver unter Verwendung des beliebten Frameworks Flask. Dank der Fähigkeiten von Poetry kann Flask einfach installiert werden, indem man `poetry add flask` ausführt. Dann, gemäß der offiziellen Schnellstartanleitung von Flask, schrieb ich eine 'hello.py'-Datei mit folgendem Codeabschnitt: ```python from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return "

Hello, World!

" ``` Das Starten des Servers mit `flask --app hello run` und das Navigieren zu http://localhost:5000 in meinem Browser lieferte das gewünschte Ergebnis. Es funktionierte! Die Methodik zur Auswahl von Flask und zusätzlichen Paketen spiegelt den Ansatz wider, der für pyenv und Poetry gewählt wurde. Aufgrund seiner Wiederholung werden diese Details in den folgenden Abschnitten weggelassen. Als Anfänger habe ich es nicht eilig, mehr Code zu schreiben. Es gibt stattdessen eine Menge Informationen, die aus dem Codeabschnitt zu entnehmen sind: - Verwende `from x import y`, um ein Modul oder eine Klasse zu importieren. - Kein Semikolon zum Beenden von Zeilen (oh nein). - Wir können eine neue Variable definieren, indem wir einen beliebigen Namen eingeben und ihr einen Wert zuweisen. - Erstellen einer Instanz einer Klasse ohne das `new` Schlüsselwort. - Python unterstützt Dekoratoren, und `@app.route` fungiert als Dekorator, der eine Funktion als Routen-Handler registriert. - Der Rückgabewert der Funktion wird als Antworttext interpretiert. - Wir können eine Funktion mit dem `def` Schlüsselwort definieren. Wie du sehen kannst, wenn wir versuchen, jede Zeile des Codes zu verstehen, anstatt es nur "zum Laufen zu bringen", können wir viel daraus lernen. In der Zwischenzeit erklärte die offizielle Dokumentation von Flask den Codeabschnitt im Detail. Meine bevorzugte Strategie ist es, zuerst die offizielle Dokumentation zu lesen, bevor ich nach anderen Ressourcen suche. Normalerweise ist dies der effizienteste Weg, etwas Neues zu lernen. ### Projektstart Jetzt ist es an der Zeit, das Projekt zu starten. Kurz darauf definierte ich eine `LogtoClient`-Klasse und versuchte, einige Eigenschaften und Methoden hinzuzufügen, um ein Gefühl für die Sprache zu bekommen: ```python class LogtoClient: def __init__(self, config = 'config'): self.config = config def signIn(self): return 'signIn' + self.config ``` Anschließend die Klasse in Flask integrieren: ```python from logto import LogtoClient client = LogtoClient() @app.route("/") def hello_world(): return client.signIn() ``` Es begann sich wie ein echtes Projekt anzufühlen. Aber ich hatte das Gefühl, dass etwas fehlte: ein Typsystem. ### Typsystem Da es sich um ein SDK handelt, wird die Implementierung eines Typsystems den Benutzern helfen, die API zu verstehen und die Fehlerwahrscheinlichkeit bei der Entwicklung zu verringern. Python führte [Type Hints](https://docs.python.org/3/library/typing.html) in Version 3.5 ein. Sie sind nicht so mächtig wie TypeScript, aber besser als nichts. Ich fügte der Klasse `LogtoClient` einige Type Hints hinzu: ```python from typing import Optional class LogtoClient: def __init__(self): self.config: str | None = 'config' def signIn(self) -> str: return 'signIn' + self.config ``` Sieht jetzt viel besser aus. Aber die Herausforderung warf sich auf, als es um komplexe Typen wie ein Objekt mit vordefinierten Schlüsseln ging. Zum Beispiel müssen wir eine `LogtoConfig`-Klasse definieren, um das Konfigurationsobjekt darzustellen: ```python class LogtoConfig: def __init__(self, clientId: str, clientSecret: str): self.clientId = clientId self.clientSecret = clientSecret # ... ``` Sieht okay aus, aber bald müssen wir uns mit den Problemen der Codierung, Dekodierung und Validierung des Objekts aus JSON auseinandersetzen. Priorisiere immer integrierte Lösungen. Wenn sie wirklich nicht funktionieren, dann erkunde Drittanbieterbibliotheken. Nur wenn alle Alternativen scheitern, solltest du in Betracht ziehen, deine eigene Lösung zu erstellen. Nach einiger Recherche entschied ich mich für [pydantic](https://pydantic-docs.helpmanual.io/) als Lösung. Es handelt sich um eine Datenvalidierungsbibliothek, die mit Type Hints funktioniert. Sie unterstützt verschiedene JSON-Funktionalitäten, ohne dass aufwendiger Boilerplate-Code erforderlich ist. Daher kann die Klasse `LogtoConfig` wie folgt umgeschrieben werden: ```python from pydantic import BaseModel class LogtoConfig(BaseModel): clientId: str clientSecret: str # ... ``` Es lehrte mich auch etwas über Klassenvererbung in Python, indem ich Klammern nach dem Klassennamen hinzufügte. ### Asynchrone Operationen Im Logto SDK müssen wir HTTP-Anfragen an den Logto-Server stellen. Wenn du Erfahrung mit JavaScript hast, mag der Begriff "Callback-Hölle" ein Begriff für dich sein. Es ist ein häufiges Problem, wenn man mit asynchronen Operationen arbeitet. Moderne Programmiersprachen bieten ähnliche Lösungen wie `Promise` oder `Coroutine` an. Ich erinnere mich immer an das Ziel. Wenn eine bestimmte Wissensschicht ausreicht, um das Ziel zu erreichen, dann muss ich nicht tiefer graben, da ich jederzeit später darauf zurückkommen kann. Gleichzeitig ist ein gründliches Verständnis innerhalb einer bestimmten Schicht erforderlich. So kann ich verschiedene Situationen in der Zukunft bewältigen. Der Schlüssel ist, das Gleichgewicht zu finden, und das ist nicht einfach. Möglicherweise schreibe ich in Zukunft einen weiteren Artikel über dieses Thema. Zum Glück hat Python eine eingebaute Lösung mit `async` und `await`. Bevor wir sie verwenden, stellen wir die Kompatibilität mit gängigen Frameworks sicher. In Flask kann dies durch die Installation des `async`-Zusatzes und die Verwendung von `async def` anstelle von `def` erreicht werden: ```python @app.route("/") async def hello_world(): # ... ``` Dann können wir `await` verwenden, um das Ergebnis einer asynchronen Operation abzuwarten. ### HTTP-Anfragen HTTP-Anfragen sind ein interessantes Thema. Fast jede Programmiersprache hat eine native Lösung, aber Entwickler verwenden normalerweise eine Drittanbieterbibliothek aus Gründen der Benutzerfreundlichkeit. Einige Beispiele: - JavaScript: `XMLHttpRequest` vs. `fetch` vs. `axios` - Swift: `URLSession` vs. `Alamofire` - Java: `HttpURLConnection` vs. `OkHttp` Das gilt auch für Python. Meine Entscheidung war, [aiohttp](https://docs.aiohttp.org/) zu verwenden, da es `async` und `await` unterstützt und ziemlich beliebt ist. ### Die Magie von Copilot Vor Copilot sollten wir jetzt zum mühsamen Teil des Schreibens von Geschäftslogik kommen. Mit Hilfe der SDK-Konvention und anderer SDKs kann ich die erklärenden Kommentare für jede Methode schreiben, bevor ich den Code schreibe. Es erhöht die Lesbarkeit des Codes und hilft Entwicklern, die API direkt in der IDE oder im Editor durch Code-Intelligenz zu verstehen. Betrachte zum Beispiel die Methode `generateCodeChallenge`, die Kommentare können wie folgt geschrieben werden: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Erzeuge einen Code-Herausforderungs-String für den gegebenen Code-Verifizierer-String. Siehe: https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2 """ ``` Dies stellte einen großartigen Hinweis für große Sprachmodelle (LLMs) dar: Definitionen von Methoden durch klare Kommentare zu verfassen. Und Copilot enttäuschte nicht: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Erzeuge einen Code-Herausforderungs-String für den gegebenen Code-Verifizierer-String. Siehe: 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('=', '') ``` Einige Anpassungen könnten erforderlich sein, aber das ist nicht wichtig. Es hat das Spiel bereits verändert. Copilot ist besonders hilfreich beim Erstellen von Code für einfache Logik. Bei der Arbeit mit mehreren Abhängigkeiten könnte es jedoch Schwierigkeiten haben. Wie der Name schon sagt, ist es ein Codenassistent, du solltest der Kapitän sein, der die Richtung vorgibt und die Entscheidungen trifft. ### Zusammenfassung Das war so ziemlich der Fortschritt, den wir am ersten Tag erreicht haben. Es war ein langer Tag, aber mit modernen Werkzeugen und Technologien war es viel besser, als ich erwartet hatte. ## Tag 2: Die Messlatte höher legen Basierend auf den Arbeiten des ersten Tages wurden die Geschäftslogik schnell erledigt. Aber für ein SDK ist das noch nicht ausreichend. Hier sind die Aufgaben für den zweiten Tag: - Unit-Tests hinzufügen. - Codeformatierung erzwingen. - Python-Versionskompatibilität überprüfen. - Continuous Integration einrichten. - Das SDK veröffentlichen. ### Unit-Tests Unit-Tests haben uns schon oft gerettet, also werde ich sie nicht überspringen. Hier sind allgemeine Überlegungen beim Schreiben von Unit-Tests: - Wie organisiert und führt man die Tests aus? - Wie wird das Ergebnis überprüft? - Wie führt man asynchrone Tests aus? (Es klingt vielleicht einfach, aber es kann in einigen Sprachen Probleme verursachen.) - Wie gibt man die Abhängigkeiten vor? (Tauchen Sie nicht in dieses Thema ein, bis es unverzichtbar wird, da es in Kaninchenlöcher führen kann.) - Wie erstellt man Codeabdeckungsberichte? Mit diesen Fragen im Hinterkopf stellte ich fest, dass das integrierte `unittest`-Modul in einigen Fällen nicht ausreicht. Also entschied ich mich für [pytest](https://docs.pytest.org/) als Testframework. Es unterstützt asynchrone Tests und erscheint reif genug. Die Reise offenbarte mir interessante neue Konzepte wie `fixture`. Dies kann auch die Denkweise beim Schreiben von Code in anderen Sprachen bereichern. Copilot ist noch besser beim Schreiben von Tests, es kann eine Menge praktischer Testfälle generieren. Selbst wenn Anpassungen erforderlich sind, kann Copilot aus dem neuen Kontext lernen und die zukünftige Codegenerierung verbessern. ### Codeformatierung Jede Programmiersprache hat ihre eigenen Codeformatierungsstile. Persönlich kann eine konsistente Formatierung mich glücklich und zufrieden machen; es ist auch hilfreich für den Code-Review und die Zusammenarbeit. Anstatt das Argument des "besten" Stils zu durchsuchen, entschied ich mich für einen Meinungsstarken Formatierer und halte mich an ihn. [Black](https://github.com/psf/black) scheint eine gute Wahl zu sein. Die einzige Frustration ist die nicht-veränderbare Tab-Größe. Aber das ist kein großes Problem, ich entschied mich, mich anzupassen. ### Python-Versionskompatibilität Als SDK sollte es mit den gängigsten Python-Versionen kompatibel sein. Durch die Suche nach "Python Version Usage Statistics" entschied ich mich, Python 3.8 als Mindestversion festzulegen. Die Tugend des Umgebungsmanagers zeigt sich jetzt. Ich kann die Python-Version einfach durch Ausführen von `pyenv local 3.8` und `poetry env use 3.8` umschalten. Dann könnte ich die Tests ausführen, um Kompatibilitätsprobleme aufzudecken. ### Continuous Integration Continuous Integration stellt die Qualität jeder Codeänderung sicher. Da unser Repository auf GitHub gehostet wird, bot sich GitHub Actions als natürliche Wahl an. Der Kernablauf folgt einfachen Prinzipien: - Die Umgebung einrichten. - Abhängigkeiten installieren. - Das Projekt bauen (Das ist bei Python nicht erforderlich). - Die Tests ausführen. GitHub Actions hat eine gute Community, daher dauert es nur ein paar Minuten, um [den Workflow](https://github.com/logto-io/python/blob/9082d9afd25b6876cadad6d9cfebf40d1c43cabc/.github/workflows/main.yml) zu erstellen. Durch die Verwendung von Matrixstrategien können wir den Workflow mit verschiedenen Python-Versionen und sogar auf verschiedenen Betriebssystemen ausführen lassen. ### Das SDK veröffentlichen Der letzte Schritt ist die Veröffentlichung des SDKs. Für öffentliche Pakete kann dies typischerweise durch die Übermittlung an das offizielle sprachspezifische Paketregister erfolgen. Zum Beispiel [npm](https://www.npmjs.com/) für Node.js, [PyPI](https://pypi.org/) für Python, und [CocoaPods](https://cocoapods.org/) für Swift. Poetry ist mein Leitstern. Einfach `poetry publish` ausführen, um das Paket an PyPI zu übermitteln. So einfach ist das. ## Abschließende Gedanken Es war eine spannende Reise. Ohne die Hilfe der Open-Source-Community wäre es wesentlich schwerer gewesen. Applaus an alle Mitwirkenden! Hier sind einige allgemeine Erkenntnisse: - Definiere das Ziel präzise und zerlege es, halte dir dann das Ziel immer vor Augen. - Richte eine stabile und reproduzierbare Entwicklungsumgebung ein. - Verwende (gute) Werkzeuge so viel wie möglich. - Priorisiere integrierte oder bestehende Lösungen. - Verstehe Sprachkonventionen und jede Zeile Code, die du schreibst. - Fixiere dich jedoch nicht auf Details. - Verwende Copilot für klare, beschreibende Aufgaben. Du findest das Endergebnis in [diesem Repository](https://github.com/logto-io/python). Mit der gleichen Strategie habe ich auch schnell das [Logto PHP SDK](https://github.com/logto-io/php) erstellt. Zögere nicht, uns zu kontaktieren, wenn du Vorschläge hast. Ich hoffe, dieser Artikel ist hilfreich, um eine neue Programmiersprache zu lernen. Happy Hacking! Logto heute ausprobieren