## Введение Logto, как сервис идентификации, стремится обеспечить плавный опыт взаимодействия в различных языках программирования и фреймворках. Это часто требует создания комплектов для разработки программного обеспечения (SDK). Однако, когда речь идет о языке программирования вне нашего технологического стека и наша команда не знакома с ним, создание надежного SDK становится серьезным вызовом. Python оказался таким вызовом для нас. Несмотря на наличие многих пользователей Python, у нас не было Python SDK, что вызывало некоторые опасения. Решив устранить этот пробел, я начал работать над этим. Хотя у меня многолетний опыт программирования, Python остается для меня относительно неизведанной территорией. В свое время я немного поигрался с Python 2 для написания простых скриптов, но мои знания устарели. Тем не менее, пришло время погружаться! ## День 1: Заложить основу ### Определение цели По моему опыту, наиболее эффективный способ изучения нового языка программирования — это создание полного проекта. К счастью, наша цель была ясна: создать SDK Logto на Python для веб-приложений. Вместо того, чтобы сразу же приступать к написанию кода, давайте разобьем задачу на этапы. Вот список: 1. Создать клиента Logto для задач, таких как вход, выход, информация о пользователе и управление токенами. 2. Предоставить руководство и пример проекта, чтобы показать использование SDK. 3. Опубликовать SDK где-нибудь, чтобы пользователи могли легко его установить. Похоже, что задача №1 требует наибольшего объема работы, поэтому нам нужно установить границы проекта и продолжить разбивку задач. Этот шаг важен для того, чтобы определить объем проекта и избежать его увеличения и чрезмерной инженерии. Предыдущая работа нашей команды сэкономила мне кучу времени: - [Конвенция по SDK](https://docs.logto.io/docs/references/sdk-convention/) определила структуру и дизайн API для SDK. - Существующие SDK для разных языков предоставили мне представление о некоторых шаблонах и возможных улучшениях для Python. Ссылаясь на эти ресурсы, я получил четкое представление о том, что делать. Хотя подробности выходят за рамки этой статьи, давайте двигаться дальше. ### Настройка окружения Я использую Mac, поэтому Python уже установлен. Однако, меня заинтересовало, есть ли более удобный способ управления версиями Python (я слышал о проблемах с совместимостью версий), подобно `nvm` для Node.js. Быстро нашел [pyenv](https://github.com/pyenv/pyenv) и сразу же начал его установку. Не зацикливайся на мелочах на этом этапе. Главное — как можно быстрее начать. Выбери широко используемые инструменты и двигайся дальше. Изменения всегда можно будет внести позже. Следующим пунктом повестки дня стал менеджер пакетов и зависимостей. Обычно они идут вместе. Так почему бы не использовать `pip` (по умолчанию в Python)? Если взглянуть на `requirements.txt`, то можно увидеть, что это просто список пакетов с версиями. Но этого недостаточно для SDK, который может использоваться другими проектами. Например, нам может потребоваться добавить некоторые пакеты для разработки, но мы не хотим включать их в финальный SDK. `requirements.txt` слишком прост для этого. Одним из преимуществ наличия других языков программирования в вашем технологическом стеке является возможность искать "аналог Python в другой технологии". Так я нашел [Poetry](https://python-poetry.org/), отличного кандидата: - Он выступает в роли менеджера пакетов, зависимостей и виртуальных окружений. - В нем есть файл `pyproject.toml`, аналогичный `package.json` в Node.js. - Он использует файл блокировки для логирования точных версий зависимостей. Современные CLI часто включают команду `init` для новых проектов. Также и в Poetry. Запустил команду, и он создал для меня файл `pyproject.toml`. ### Первая строка кода Наконец-то настал момент начать писать код. Начинать с классической программы "Hello, World!" всегда хорошая идея. При изучении языка программирования не всегда нужен полнофункциональный IDE; достаточно редактора, поддерживаемого сильным сообществом, таким как VS Code. Учитывая, что наш SDK ориентирован на веб-приложения, я начал с простого веб-сервера, используя популярный фреймворк Flask. Благодаря возможностям Poetry установка Flask может быть легко выполнена путем запуска команды `poetry add flask`. Затем, следуя официальному руководству по быстрому старту Flask, я написал файл "hello.py" со следующим фрагментом: ```python from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return "

Hello, World!

" ``` Запустив сервер с помощью команды `flask --app hello run` и перейдя по адресу http://localhost:5000 в браузере, я получил желаемый результат. Всё работает! Методология выбора Flask и дополнительных пакетов аналогична подходу, использованному для pyenv и Poetry. Поскольку этот процесс довольно повторяем, эти детали пропущены в последующих разделах. Будучи новичком, я не спешил писать больше кода. Вместо этого, из данного фрагмента кода можно почерпнуть много информации: - Для импорта модуля или класса используется `from x import y`. - Строки не заканчиваются точкой с запятой (о нет). - Можно определить новую переменную, вводя произвольное имя и присваивая ему значение. - Создание экземпляра класса без ключевого слова `new`. - Python поддерживает декораторы, и `@app.route` является декоратором, который регистрирует функцию в качестве обработчика маршрута. - Возвращаемое значение функции интерпретируется как тело ответа. - Функция определяется с помощью ключевого слова `def`. Как видишь, если попытаться понять каждую строку кода, а не просто "запустить её", можно много узнать. Между тем, официальная документация Flask подробно объяснила этот фрагмент. Мой основной подход — сначала читать официальную документацию, перед тем как искать другие ресурсы. Обычно это самый эффективный способ освоить что-то новое. ### Начало проекта Теперь пришло время начать проект. Скоро я определил класс `LogtoClient` и попытался добавить несколько свойств и методов, чтобы почувствовать язык: ```python class LogtoClient: def __init__(self, config = 'config'): self.config = config def signIn(self): return 'signIn' + self.config ``` Затем интегрировал этот класс в Flask: ```python from logto import LogtoClient client = LogtoClient() @app.route("/") def hello_world(): return client.signIn() ``` Начало напоминать реальный проект. Но мне казалось, что чего-то не хватает: типовой системы. ### Система типов Поскольку это SDK, включение системы типов поможет пользователям понять API и уменьшит вероятность ошибок при разработке. Python ввел [типовые подсказки](https://docs.python.org/3/library/typing.html) в версии 3.5. Это не столь мощная система, как TypeScript, но лучше, чем ничего. Я добавил несколько типовых подсказок в класс `LogtoClient`: ```python from typing import Optional class LogtoClient: def __init__(self): self.config: str | None = 'config' def signIn(self) -> str: return 'signIn' + self.config ``` Теперь это выглядит намного лучше. Но сложность возрастает, когда речь заходит о сложных типах, например, объекты с заранее определенными ключами. Например, нам нужно определить класс `LogtoConfig`, чтобы представить объект конфигурации: ```python class LogtoConfig: def __init__(self, clientId: str, clientSecret: str): self.clientId = clientId self.clientSecret = clientSecret # ... ``` Это выглядит нормально, но вскоре нам придется столкнуться с проблемами кодирования, декодирования и проверки объекта из JSON. Всегда отдавай предпочтение встроенным решениям. Если они действительно не работают, тогда пробуй сторонние библиотеки. И только когда все альтернативы терпят неудачу, стоит задуматься о создании собственного решения. После небольших исследований я выбрал [pydantic](https://pydantic-docs.helpmanual.io/) в качестве решения. Это библиотека для валидации данных, работающая с типовыми подсказками. Она поддерживает различные функции для работы с JSON без необходимости писать скучный шаблонный код. Таким образом, класс `LogtoConfig` можно переписать так: ```python from pydantic import BaseModel class LogtoConfig(BaseModel): clientId: str clientSecret: str # ... ``` Кроме того, это дало мне понимание наследования классов в Python — достаточно прописать круглые скобки после имени класса. ### Асинхронные операции Внутри SDK Logto нам нужно делать HTTP-запросы к серверу Logto. Если у тебя есть опыт работы с JavaScript, фраза "ад коллбеков" наверняка звучит знакомо. Это распространенная проблема при работе с асинхронными операциями. Современные языки программирования предлагают похожие решения, такие как `Promise` или `корутины`. Я всегда напоминаю себе о цели. Если определенный уровень знаний достаточен для достижения цели, то мне не нужно копать глубже, так как я всегда смогу вернуться к этому позже. В то же время необходима полная осведомленность в пределах определенного уровня. Это позволит справляться с различными ситуациями в будущем. Ключевое — найти баланс, и это непросто. Возможно, я напишу отдельную статью об этом в будущем. К счастью, Python предлагает встроенное решение с использованием `async` и `await`. Перед их использованием следует убедиться в совместимости с популярными фреймворками. В Flask это можно сделать, установив `async extra` и используя `async def` вместо `def`: ```python @app.route("/") async def hello_world(): # ... ``` Затем можно использовать `await` для ожидания результата асинхронной операции. ### HTTP запросы HTTP-запросы — интересная тема. Практически в каждом языке программирования есть встроенное решение, но разработчики обычно выбирают сторонние библиотеки, если это упрощает задачу. Примеры: - JavaScript: `XMLHttpRequest` vs. `fetch` vs. `axios` - Swift: `URLSession` vs. `Alamofire` - Java: `HttpURLConnection` vs. `OkHttp` То же самое верно для Python. Мой выбор пал на [aiohttp](https://docs.aiohttp.org/) из-за его поддержки `async` и `await`, а также популярности. ### Магия Copilot Раньше на этом этапе уже начинался запутанный процесс написания бизнес-логики. Но теперь, с помощью конвенций SDK и других SDK, я мог писать описательные комментарии для каждого метода перед написанием кода. Это повышает читаемость кода, а также помогает разработчикам понимать API прямо в IDE или редакторе через возможности автодополнения кода. Например, рассмотрим метод `generateCodeChallenge`, комментарии можно составить так: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Генерация строки вызова кода для данного кодового проверочного строки. См.: https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2 """ ``` Это стало отличным сигналом для моделей больших языков (LLM): методы, описанные четкими комментариями. И Copilot не разочаровал: ```python def generateCodeChallenge(codeVerifier: str) -> str: """ Генерация строки вызова кода для данного кодового проверочного строки. См.: 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('=', '') ``` Могут потребоваться незначительные корректировки, но это неважно. Это уже изменило правила игры. Copilot сияет при создании кода для простых логических операций. Однако он может испытывать затруднения с многозависимой логикой. Как и следует из названия, это помощник по коду, и ты должен быть капитаном, который контролирует направление и принимает решения. ### Завершение первого дня На этом завершился первый день работы. Это был долгий день, но с современными инструментами и технологиями все оказалось гораздо лучше, чем я ожидал. ## День 2: Поднятие планки На основе выполненной работы первого дня бизнес-логика была завершена быстро. Но для SDK этого недостаточно. Вот задачи на второй день: - Добавить модульные тесты. - Обеспечить форматирование кода. - Проверить совместимость с версиями Python. - Настроить непрерывную интеграцию. - Опубликовать SDK. ### Модульные тесты Модульные тесты не раз спасали нас, поэтому я не пропустил их. Вот основные вопросы, которые необходимо учитывать при написании модульных тестов: - Как организовать и запускать тесты? - Как проверять результат? - Как запускать асинхронные тесты? (Звучит очевидно, но иногда возникают проблемы в некоторых языках.) - Как эмулировать зависимости? (Не углубляйся, пока это не станет абсолютно необходимым, так как можно легко угодить в кроличью нору.) - Как создавать отчеты о покрытии кода? Ответы на эти вопросы показали мне, что встроенный модуль `unittest` не подходит для некоторых случаев. Поэтому я выбрал [pytest](https://docs.pytest.org/) как тестовый фреймворк. Он поддерживает асинхронные тесты и кажется достаточно зрелым. В ходе работы я обнаружил множество интересных новых концепций, таких как `fixture`. Это также полезно для изменения подхода к написанию кода на других языках. Copilot еще лучше справляется с написанием тестов, он генерирует множество практичных тест-кейсов. Даже если потребуются правки, Copilot сможет учиться на новом контексте и улучшить последующее поколение кода. ### Форматирование кода У каждого языка программирования есть свои стили форматирования кода. Лично я считаю, что достижение консистентности форматирования делает меня счастливыми и комфортными; это также полезно для организации обзора и сотрудничества в коде. Вместо того чтобы углубляться в споры о "лучшем" стиле, я решил взять на вооружение категоричный форматер и придерживаться его. [Black](https://github.com/psf/black) мне понравился. Единственное огорчение — невозможность изменить размер табуляции. Но это не критично, я решил привыкнуть. ### Совместимость версий Python Как SDK, он должен быть совместим со всеми распространенными версиями Python. Поискав "статистику использования версий Python", я решил использовать Python 3.8 как минимум. Достоинство менеджера окружения стало очевидным. Я легко переключил версию Python, запустив `pyenv local 3.8` и `poetry env use 3.8`. Теперь я мог запускать тесты и выявлять проблемы совместимости. ### Непрерывная интеграция Непрерывная интеграция гарантирует качество каждого изменения кода. Поскольку наш репозиторий размещается на GitHub, естественным выбором стало GitHub Actions. Основной рабочий процесс следует простым принципам: - Настройка окружения. - Установка зависимостей. - Сборка проекта (в Python это не требуется). - Запуск тестов. У GitHub Actions хорошее сообщество, так что на создание [рабочего процесса](https://github.com/logto-io/python/blob/9082d9afd25b6876cadad6d9cfebf40d1c43cabc/.github/workflows/main.yml) у меня ушло всего несколько минут. Используя стратегии матриц, мы можем запускать рабочий процесс на разных версиях Python, даже на разных операционных системах. ### Публикация SDK Последним шагом стала публикация SDK. Для публичных пакетов это обычно делается путем отправки в официальный реестр пакетов для конкретного языка. Например, [npm](https://www.npmjs.com/) для Node.js, [PyPI](https://pypi.org/) для Python и [CocoaPods](https://cocoapods.org/) для Swift. Poetry стал моим руководством. Просто запустил команду `poetry publish`, чтобы опубликовать пакет в PyPI. Всё очень просто. ## Заключительные мысли Это было увлекательное путешествие. Без помощи сообщества с открытым исходным кодом это было бы намного сложнее. Аплодирую всем участникам! Вот несколько выводов, которые можно усвоить: - Четко определяйте цель и разбивайте её на составляющие, и всегда держите её в голове. - Настройте стабильное и воспроизводимое окружение для разработки. - Используйте (хорошие) инструменты как можно чаще. - Отдавайте предпочтение встроенным или существующим решениям. - Понимание конвенций языка и каждой строки вашего кода. - Однако не зацикливайтесь на мелочах. - Используйте Copilot для ясных, описательных задач. Исходное решение можно найти в [этом репозитории](https://github.com/logto-io/python). С той же стратегией я также быстро создал [Logto PHP SDK](https://github.com/logto-io/php). Не стесняйтесь сообщить нам, если у вас есть предложения. Надеюсь, эта статья окажется полезной для изучения нового языка программирования. Удачи в кодинге! Попробуй Logto сегодня