python

Submit the cool project: свой API-client с одного конфигурационного файла

  • вторник, 3 октября 2017 г. в 03:12:25
https://habrahabr.ru/post/339150/
  • Python
  • Open source
  • GitHub
  • API



Привет, Хабрахабр! Я тут недавно сделал тулзу, которая генерирует целую обертку-клиент над любым API, который ты только захочешь, с одного yml-файла, а потом сразу же загружает его в Python Package Index (PyPi). Да, результат можно установить в свой любой проект с помощью pip и начать пользоваться. Подробнее под катом!

Пример


Посмотрите на код вымышленных http-запросов на Game of Thrones API-сервер, который бы вы написали с помощью библиотеки requests.

import requests 


create_jon_snow_user = requests.post(
    'https://gameofthrones.com/api/v1/user', 
    params={
        'id': 7,
        'name': 'Jon',
        'surname': 'Snow',
    }
)

get_jon_snow_user = requests.get(
    'https://gameofthrones.com/api/v1/user', params={'id': 7}
)

create_jon_snow_castle = requests.post(
    'https://gameofthrones.com/api/v1/user/castle', 
    params={
        'id': 7,
        'castle': 'Winterfell',
    }
)

А теперь на код, который делает возможным использовать синтаксические, комфортные для клиента (девелопера), конструкции.

from gameofthrones_api import gameofthrones_api_client as got_api_client


create_jon_snow_user = got_api_alient.user.create({
    'id': 7,
    'name': 'Jon',
    'surname': 'Snow'
})

get_jon_snow_user = got_api_alient.user.get({'id': 7})

create_jon_snow_castle = got_api_alient.user.castle.create({
    'id': 7,
    'castle': 'Winterfell',
})

Как это работает


Такую возможность открывает инструмент acg (ссылка на Github), но для этого ему необходим файл с названием .acg.yml в следующем виде:

pypi:
  username: dmytrostriletskyi
  password: d843rnd3

acg:
  name: gameofthronesapi
  version: 0.1.5

  api: https://gameofthrones.com/api/v1

  services:
    user:
      url: /user
      endpoints: create:post, get:get

    user.castle:
      url: /user/castle
      endpoints: create:post

Вы указываете свои PyPi логин и пароль, чтобы acg загрузил клиент на ваш аккаунт и этот пакет мог быть доступен для установки через pipacg вписывает параметры в файл .pypirc, который нужен для загрузки вашего пакета в Python Package Index (PyPi).

Теперь к back-end серверу, к которому вы пишите клиент:

  • в .acg.yml доступно поле api, где нужно указать корень (адрес), от которого уже идут ответвления на различные запросы. Например, корнем является ваша API myapi.com, а ответвлением /users/all.
  • в services уже на любой вкус можно указать сколько угодно «путей», все они заканчиваются эндпоинтами (endpoints) и имеют в наличие адрес, к которому они «принадлежат».
  • endpoints в пункте acg в конфигурациях — это название метода и его тип запроса HTTP. Пример из конфигураций выше: user.castle.create, post-запрос, на адрес /user/castle. Наличие endpoint полезно, когда один путь поддерживает много типов запроса (get, post, delete для одного адреса). Например, apple.iphone.ten.account может поддерживать endpoints get (тип запроса get), delete (delete), create (post), modify (put) к адресу /apple/iphone/ten/account.
  • Множество эндпоинтов к одному адресу записываются в одну строку к пункту endpoints через запятую — get:get, delete:delete, create:post, modify:put (пример).

Установка acg


Установить acg можно с помощью pip.

$ pip install acg

Pip3:

$ pip3 install acg

Или собрать исходный код:

$ python setup.py install

Команда acg


Создали .acg.yml, вписали туда свои настройки, открыли терминал в директории с конфигурациями:

$ acg

Вы также продолжаете работать с acg, если хотите обновить конфигурации и клиент соответственно. Помните, что на каждую новую загрузку необходимо менять версию вашего клиента-пакета. Не забывайте использовать флаг --no-cache-dir или -U при установке новой версии своего пакета.

Чтобы не было конфликтов, советую удалять все сгенерированные проекты (папки) вашего проекта (каждый раз acg строит проект заново).

Как установить и использовать свой клиент


Установка потребует знакомой вам команды `pip install {name}`, где названием пакета будет значение name в конфигурационном файле.

Использовать также просто, импортируете объект со всеми нужными параметрами из своего установленного модуля. Клиент всегда повторяет название пакета, но дополняет себя частью _client.

Например, вы написали конфигурации под проект telegrambotapi.
Тогда используйте клиент в Python-коде так:

from telegrambotapi import telegrambotapi_client